Skip to main content

Calm Finance - Development Documentation

Project Description

The Finance project is a web project that was created with the intention of making it easier for the costumer effectivate transact and receive payments. The project guarantees the possibility of easily managing the user's transactions' history and their personal customers, alongside with their company's information.
The project consumes an API, from Calm Commerce, which gives Finance the capability to store data from the user so it is shown, and for the user to make transactions and manage its company in a simpler way.
The first step of Finance is Earnings. Earnings give the user access to their companies' income. In that way we have, for now, three main screens destined to Earnings. The first one is the Home, or Mini Board. In there, the user can access:
A summary of its earnings, where it's shown the amount of money he has earned, on which it's displayed in chronological order and can show the data by day, week or month. For that, is needed the amount of money he has received, the amount of money he was expecting, the date of the transaction, who made the transaction and the possibility to rearrange that by day, week or month;
An account setup step by step to guarantee the user's best usage of the platform, in there is shown a list of those steps alongside a check mark that alters when the user completes that step. For that, is needed the step's list. Each step should have a title and a variant to see if it's completed. At this point, the account setup list contains:

  • Choose a theme

  • Choose a plan

  • Connect to your store

  • Store listing

  • Publish

  • Connect to accounting;

    A list of the apps that are available for the user to access. For that, is needed: the actual list and the possibility to create an app that can be added to that list. For now, the app needs a name and a route;
    An user guide list, for now, this part is still in planning on what it's going to be shown and how;
    An 'what's new' list. In this section is shown everything that it's new in the platform for the user to check it out. For that, it needs an what's new item, that has a title, a text body and a text button to be displayed.
    An 'setup' list, for now, this part is still in planning on what it's going to be shown and how;
    An 'experts' list, for now, this part is still in planning on what it's going to be shown and how.
    Following the pages' description, in sequence, we have the actual Earnings page. Here is shown a bigger version of the earnings' summary that we have in the Mini Board. So, it's needed the same data, alongside with the possibility to get the data from a set of 2 dates, from an specific source and amount. Also, it's needed the source, hours and stops that it took for that amount.
    Next on the Earnings pages description it's preferences. In preferences the user can check and alter their personal data, the data from their companies and some platform data. To build the preferences page, it will be needed:
    A list of preferences, the preferences item needs an icon, title, subtitle, the list of its subpages, on which each subpage must have a title and the pages and subpages information. For example, on the 'Legal' preferences item, it's possible for the user to check the coverage of their products, where it is located, the amount in the inventory, the cost, the shipping time, the providers' list and if it's available for delivery. Another example is the 'Delivery & Shipping' preferences item. In there it's needed the user's legal name and the product details;
    The other preferences items it's in elaboration for now. But at this time, the list on items are:

  • Legal

  • Bank

  • Withdrawls

    • Schedule
    • Documents

  • Delivery & Shipping

    • Rates
    • Providers
    • Costs

  • Payments & Curiencies

  • Languages

    • Translations

  • Standards

The next step for Finance, after Earnings is Billing. Billing will be able to allow banks to handle transactions from their clients.
Another project linked with Finance is Payroll. Payroll is a platform that allows a company to pay its employees directly from there. The payment can be configured by the company for each employee. The goal is to keep it simple and direct when it comes to handling it's employees payments

Purpose of Documentation​

The purpose of this document is to document all parts of the project. Establishing the project's features, technologies, developments, team, definitions, services and any other element on the composition of the Finance project.
This project it's a guide for developers, designers, and any individual or company participating in this project. It was made to clear as much doubt any participant or contributor of the project may have and register all the progress made along the project's development

Scope​

This document will cover the development process, the tools and technologies that it was used, the team members, the users and the use cases. This document does not include, in first instance, anything not related to the development, as in, the software development. If necessary, on a further update on the document, all that is missing will be located in an seccion here.

Technologies​

  • Flutter: will be used as our framework for cross-platform development.
  • Dart: The programming language used alongside with Flutter
  • NodeJS: The programming language will be used to build the project's API in firebase and integrate the project's API with Stripe's API.
  • GitHub: The code manager chosen for the project.
  • Stripe: The software chosen to manage the payment interactions the users of Finance will be making and managing.
  • Firebase: The server of the application.
  • A tool that the development team, and the company in general, uses to communicate with each other internally.
  • Where all the documents will be stored for easy access of any person involved in the project's development.
  • A tool that will be used for communication with members of the project and, in other cases, with external people or companies that are involved with the product.
  • The tool used to manage the sprint of the week. And track progress of what is done and what needs to be done.

Practices​

  • Git Workflow​

    This section of the document will be written some development patterns that will be used in the project's development process.
    For starters, all the developers must push all their code to the private repository at the end of each day. That's because it will give the project manager time to check the development of the team and it will make sure that the code is on it's latest version, and that reduces a lot of merge conflicts that may appear.
    The repository have 3 permanent branches:

  • Main
  • Prod
  • Dev

  • Main

    This branch has the production code on it, ready to be used by the user. This branch can't be used for developing. The only persons authorized to use this branch is the Project Manager, the project's technical leaders or a chosen developer.
    The only thing that goes into the main branch is the merge with the prod branch.

  • Prod

    This branch contains the final production code, ready to be used by the user and ready to be merged with the main branch. The only persons authorized to use this branch is the Project Manager, the project's technical leaders or a chosen developer.

  • Dev

    This branch contains the latest version of the development of the application. It's from this branch that the developers can create new branches for building features, fixing bugs and testing the components of the application. But, the developers team can't merge any branch with the dev branch unless the Project Manager or the project's technical leaders give the permission to do so.
    This branch, when evaluated, is to be merged with the prod branch.

  • Auxiliary Branches

    The auxiliary branches are used for building features, fixing bugs, testing components and managing other situations that can appear during the development process. All these branches have a limited life. As soon as the problem is solved or the feature is ready, this branch needs to be merged with the dev branch, so the other developers can work on the latest version of the application.
    The branches need to be clear on their names (names that can't be used are: master, main, dev, developer, release, sprint, hotfix, names not related with what the branch is supposed to do), and each branch must be specific to only one function. They need to follow this pattern:

  • feature/nameOfTheFeature
  • fix/nameOfTheBug

  • Commits

    To keep the git history legible, the commits will have a pattern. This pattern has two parts, the type and the description.

  • Type

    The type can be one of these options:

  • feat: new feature or new update on a feature
  • fix: bug fix
  • refactor: code refactoring
  • update: packages, configs, build, etc updates. (None code alteration of any functionality)
  • test: addition, refactoring, removal of tests. (None code alteration of any functionality)

  • Description

    The description should answer the question: "what was done?" and if possible answer "and why?" too. Be as short and concise as possible.

    An example on how the commits should look like:

  • feat: pagination on the home page started.
  • fix: fixed the primary color on the dark theme
  • refactor: eliminated unused code to clear space in the project.
  • update: updated all the packages in the pubspec.yaml to avoid conflicts
  • test: testing all search possibilities

  • Jira Workflow​

    Jira is the tool we use to keep track of the progress that we make in the project. For best usage of the tool, the team needs to update the Jira all the time. When a task is assigned, when it starts, when it is finished, so in that way, all the team will be on the same page.

  • Communication​

    The team must be in constant communication with each other. Any doubt, incertain, or suggestion it is recommended to be shared with the team, only in that way the team will be helpful in the situation. Besides, it's the best way for the team to learn and connect with each other, not only work.
    The communication is recommended to be on the Finance's Google Chat group, but feel free to contact any member of the team or the company for help. But, it's important that what is learned is shared with the team. This way, all the team gains new knowledge and experiences.

  • Flutter​

    For the Flutter development to be as simple as possible, it's important to follow, as much as possible, the little rules regarding the Clean Code and Clean Architecture books. This means, developing and organizing the code in a way that's easy to understand and maintain.
    We intend to avoid as much code repetition as possible and we want to make our code and widgets reusable for future applications or updates. To keep that working, while developing, try to separate the screen's fragments in components/widgets and store them in their respective folders.
    As we want to make our code simple to maintain, we are also using the ThemeData class to set static definitions for our components in the screens, so, in case we have a redesign, or layout changes, it's easier to change in the code.
    Finance is a webapp, so it's important to be responsive. To guarantee that, we are using the responsive widgets/components that Flutter provides, such as: LayoutBuilder, MediaQuery, Padding and others. For the LayoutBuilder, we created an adaptation to build a desktop screen, a tablet screen and a mobile screen in an easier and organized way.
    As developing, it's important to remove unused code, as soon as it's not being used anymore. Keep the classes clean and easy to understand. There are some important rules from Clean Code that we want to keep in mind. One is that a method should do only one thing, avoid code repetition and refactor as much code as possible, to make it easier to maintain.

​

​

Practices​

  • Git Workflow​

    This section of the document will be written some development patterns that will be used in the project's development process.
    For starters, all the developers must push all their code to the private repository at the end of each day. That's because it will give the project manager time to check the development of the team and it will make sure that the code is on it's latest version, and that reduces a lot of merge conflicts that may appear.
    The repository have 3 permanent branches:

  • Main
  • Prod
  • Dev

  • Main

    This branch has the production code on it, ready to be used by the user. This branch can't be used for developing. The only persons authorized to use this branch is the Project Manager, the project's technical leaders or a chosen developer.
    The only thing that goes into the main branch is the merge with the prod branch.

  • Prod

    This branch contains the final production code, ready to be used by the user and ready to be merged with the main branch. The only persons authorized to use this branch is the Project Manager, the project's technical leaders or a chosen developer.

  • Dev

    This branch contains the latest version of the development of the application. It's from this branch that the developers can create new branches for building features, fixing bugs and testing the components of the application. But, the developers team can't merge any branch with the dev branch unless the Project Manager or the project's technical leaders give the permission to do so.
    This branch, when evaluated, is to be merged with the prod branch.

  • Auxiliary Branches

    The auxiliary branches are used for building features, fixing bugs, testing components and managing other situations that can appear during the development process. All these branches have a limited life. As soon as the problem is solved or the feature is ready, this branch needs to be merged with the dev branch, so the other developers can work on the latest version of the application.
    The branches need to be clear on their names (names that can't be used are: master, main, dev, developer, release, sprint, hotfix, names not related with what the branch is supposed to do), and each branch must be specific to only one function. They need to follow this pattern:

  • feature/nameOfTheFeature
  • fix/nameOfTheBug

  • Commits

    To keep the git history legible, the commits will have a pattern. This pattern has two parts, the type and the description.

  • Type

    The type can be one of these options:

  • feat: new feature or new update on a feature
  • fix: bug fix
  • refactor: code refactoring
  • update: packages, configs, build, etc updates. (None code alteration of any functionality)
  • test: addition, refactoring, removal of tests. (None code alteration of any functionality)

  • Description

    The description should answer the question: "what was done?" and if possible answer "and why?" too. Be as short and concise as possible.

    An example on how the commits should look like:

  • feat: pagination on the home page started.
  • fix: fixed the primary color on the dark theme
  • refactor: eliminated unused code to clear space in the project.
  • update: updated all the packages in the pubspec.yaml to avoid conflicts
  • test: testing all search possibilities

  • Jira Workflow​

    Jira is the tool we use to keep track of the progress that we make in the project. For the best use of the tool, the team needs to update the Jira all the time. When a task is assigned, when it starts, when it is finished, so in that way, all the team will be on the same page.

  • Communication​

    The team must be in constant communication with each other. Any doubt, incertain, or suggestion it is recommended to be shared with the team, only in that way the team will be helpful in the situation. Besides, it's the best way for the team to learn and connect with each other, not only work.
    The communication it is recommended be on the Finance's Google Chat's group, but feel free to contact any member of the team or the company for help. But it's important that what is learned is shared with the team. This way, all the team gains new knowledge and experiences.

Development​

  • Project Architecture​

  • android

  • ios

  • assets

    • fonts: where all the external fonts are located
    • images: where all the constant images are locates

  • build

  • lib

    • bloc: where all the bloc files are locates
    • components: components that are used in different screens must be located here
    • model: all the models for the objects that are used are located here
    • pages: contains all the pages. The pages will be described in the next section
    • services: contains all the things related to the API
    • utils
      • constants: contains all the constants used in the project
        • intl: contains the files related to the languages of the application
      • helpers: all files/methods that are used to format, verify or help in any way any functionality are located here
      • styles
        • text_styles: contains all the configuration related to the texts that appears on the application
        • themes: contains all the themes that the application uses
    • main.dart

  • test

    • widget_test.dart

  • web

  • .gitignore

  • .metadata

  • README.md

  • pubspeck.lock

  • pubspec.yaml

​

  • Pages​

    All the pages' folders follow the same architecture as the base_page example.

  • base_page

    • responsive
      • base_page_large.dart
      • base_page_medium.dart
      • Base_page_small.dart
    • base_page.dart

  • home_page - mini_board

  • preferences_page

Earning_page​

Services​

  • Stripe API​

  • Finance API​

Pubspec.yaml​

  • dio: Used to handle http requests
  • intl_utils: Used to handle translations
  • shared_preferences: Used to storage user preferences
  • shimmer: Used to apply the shimmer effect
  • google_fonts: Used to get more fonts
  • fluttertoast: Used for text styling