Clean Architecture Template (CAT)

---

A brick for Mason CLI that generates a clean architecture template for a given feature.

📖 Introduction

This brick was created to improve performance while developing new features for a Flutter project.

For a best fit, the project must follows a set of rules from Clean Architecture, specifically from Clean-Dart

For the purpose of keeping things easy, I have modified some ideas of the Clean-Dart, and implemented some other points that I think it's important for a project.
The complete code structure is the next:

• Domain
  • Entities
  • Failures
  • Repositories
  • Usecases
  • Validators (Not supported)
• Infrastructure
  • Mappers
  • Datasources
  • Errors
  • Repositories
• External
  • Datasources
  • Settings (in some cases)
• Presentation
  • Controllers
    • Bloc
      • Events
      • States
    • Stores
  • Pages (Not supported)
  • Widgets (Not supported)

This structure will be detailed in a ARCHITECTURE.md file (not yet created).

🚀 Getting Started

🧩 Variables

This brick has currently two variables that can be set by the user, they are

• module_name:
  The name of the module you want to generate.

  ⚠️ The brick was projected to work with snake_case names. ⚠️

  Using any other case when setting module_name can result in code not being correctly structured.
  I'll improve this in the future.

  Defaults to feature.

• has_parameters:
  A boolean variable that defines if the module will send parameters to the backend.

  If set to true it will generate a parameters entity and mapper, that will be used throught the layers.
  If set to false it won't generate the entity and mapper.

  Defaults to false.

🔒 Internal Variables

As said, I've modified the Clean-Dart structure while building this brick.
One of those things is that I have some "custom files" that are needed throught the layers, but the brick can't identify those files since you can run it in any folder of the project.
The solution was to create a pre-generation script (basically a hook) that will identify the root of the app (the lib folder) and define some paths from this point.

For example, I have a generic class named Failure that I use in the architecture.
The pre-gen script will get the path of this file and concatenate to the lib path, so it can be set as a variable and imported wherever it's needed.
The user don't have to manually import it.

If, for any reason, the pre-gen script can't find a lib folder it will simply return, the variables won't be setted, and the imports won't appear.

Talking about those internal variables, they are five and their respective values are:

• failure_path:
  The path to the generic Failure, a generic class that all failures in the project must implement.

  Path to file: project_name/lib/app/core/shared/domain/failures/failure.dart

• request_client_path:
  The path to the request client used in the project, in this case I've created an abstraction of a request client, which is what it's going to be imported.

  Path to file: project_name/lib/app/core/packages/request_client/request_client.dart

• services_settings_path:
  The path to the services settings, which is the base endpoint to all requests.

  Path to file: project_name/lib/app/core/shared/external/settings/services_settings.dart

• generic_query_path:
  The path to the generic query structure, which gives the base strcture of query parameters for all requests.

  Path to file: project_name/lib/app/core/shared/infrastructure/mappers/name_method_query_mapper.dart

• message_parser_path:
  The path to a message parser. If the backend returns anything other than a success this class can parse and return a message.

  Path to file: project_name/lib/app/core/helpers/server_error_message_parser.dart

⚙️ How to run it

If you have already used any mason brick you basically know what to do. But I'll explain some details and give some tips.

🛠️ Installing this brick

Here are the steps for you to use this brick

1. Install mason through the dart command
   I found that the best way to install mason is by using their recommended way.

   This can be done by running this dart command in the terminal

   dart pub global activate mason_cli

   Keep in mind that if you use multiple versions of the Dart SDK, for example if you're using FVM, you can see a warning if running the brick with a different dart version than the one you have installed the mason.
   The terminal shows the following message saying it couldn't load the kernel, but it manages to run the brick with no further issues.

   Can't load Kernel binary: Invalid kernel binary format version.

   About the homebrew version...
   I have tried the homebrew version, but it installs a full version of the Dart SDK, even if you already have a version (or multiple) installed.
   It just adds another version of the Dart SDK. This discouraged me to use the homebrew version.

2. Install the CAT brick
   Once mason is installed you have to install the CAT brick to it.
   There are two ways of installing bricks using mason: locally or globally.
   I'd recommend that you install it globally so you can use it in any flutter project, but if you just need it to a single project, you can install it locally.

This brick is hosted in the BrickHub, and you can install it with the commands

# Local install
mason add cat

# Global install
mason add cat -g

Alternatively, you can install it by referencing this repository. You can do this by using the following commands

# Local install
mason add cat --git-url https://github.com/SamuelGadiel/mason_cat

# Global install
mason add cat -g --git-url https://github.com/SamuelGadiel/mason_cat

▶️ Using this brick

There are two ways of using bricks. You can simply execute it in the terminal or, if you're using Visual Studio Code, you can install an extension that will help you running it inside a project.

• Using the VS Code extension
  My favorite way for running this brick is by installing the Mason extension for VS Code.

  This extension allows you to run any brick installed in the machine, locally or globally.
  For this, just right-click the folder where you want to generate the module and select the respective option

  

  It will show a pop-up asking for you to select the brick you want to run, then it will ask for the necessary variables.
  After inserting all the informations the module will be generated.

• Using the terminal
  If you prefer to use the terminal you can basically run this command

  mason make cat

  It will ask for the necessary variables.
  Once you have entered those informations it will generate everything you need for the module

  Another way you can run this command is by passing the variables directly in the command

  mason make cat --module_name 'your_module_name' --has_parameters false

  Mason will ask for any informations that are ommited, in case you don't pass it.

---

⭐️ Credits

The logo is build using an asset from FlatIcon.

Cat image that was used

All credits are given to the respective creators.