Project Structure

Summary

Despite of Avantus is an unique Symfony application, the code structure is organized to serve different internal and externals services. The idea behind this documentation is to provide a clear description of project structure and the style guide which programmers need to follow while coding into the Avantus.

General structure

The general structure is the same as any standard Symfony Application. Check the picture below.

• bin: Executable files (e.g. bin/console).
• config: Configuration files from project, please note that the only accepted format is YAML instead of YML.
• docs: Project documentation folder. Migrating now to the cloud...
• public: This is the directory for all public and static files like images, stylesheets and Javascript files that need to be served to the front.
• src: Where the project source lives.
• templates: Where the twig files are located. Noted that only few sections into the Avantus requires templates.
• test: Automatic tests (e.g. Unit tests).
• var: Generated files (cache, logs, etc.).
• vendor: The third-party dependencies.

Src structure

• Apis: This directory contains the Avantus Apis. Please note that each folder inside belongs to specific Api application. We don't merge the content between Apis, in case we need something common between two or more Apis, automatically we move to Shared folder. Each Api folder contains his own structure as per needs.
• Commands: Commands is the namespace for all available Symfony Commands into the Avantus. Please note that the Commands here serves to all system and is not restricted to one specific scope.
• Connectors: Contains implementation for all our external services. Also note that connectors are not restricted to specific scope, can be used everywhere where is needed.
• Linkers: Linkers contains the clasess that handle the logic for externals services which send request to Avantus. Instead of generate the request from Avantus to point B, like in Connectors, Linkers expose urls that receive request from point B, these can be externals services or also cronjobs. The result of the processing normally has direct impact in our DB. One of the main uses is to updated entities in our DB that also are hosted in external services.
• Model: Contains all the model classes of Avantus database. This includes Repositories, Entities, Migrations, etc.
• Utils: Contains all the clases that serves utilities to the global Avantus. Please note that the files here are used everywhere due this is the global Utils folder. It does mean is not restricted to any scope or context. Example of functionalities here are Logger and Notification services.
• Workflow: Contains the classes for handling the process that can be executed every some period of time and respond to cronjob in the system. In this part of the code is used the Symfony cron-bundle. The entities which belong to this mini application has the prefix "wf_"

Please note that when you add new helper file to the Utils folder, you first need to be sure can be used everywhere and is not something specific for one part of the Avantus. You also should program as generic as possible to suit your needs. Also note that a change in the classes here may affect the behavior of parts of the code that use it.

Src/Apis structure

• AdminPortal: This Api handles the server side for the Admin Portal frontend. Use the Shared files for some general files and operations, but the main code lives in here. The entities which belong to this logic have the prefix "ap_".
• CustomerPortal: This Api handles the server side for the Customer Portal frontend. Use the Shared files for some operations, but the main code lives in here. The entities which belong to this logic have the prefix "cp_".
• Shared: Contains all clases that are common for all Apis.

All the Apis contain the same structure except some that maybe can not need some folder like EventListeners, but this is not a limitation and developers can create more folder when the existing ones do not meet the needs.The common folders into the Apis directories are described below.

• Controller: Handles the request from the client side, its the entry point for the client requests, has the responsability to receive the request, validate the data received, send to handlers for business processing, and return the response received from handlers to the client. Note that Controllers receive ApiRequest object and responds ApiResponse object.
• Handlers: Normally exists one Handler class per Controller class, but can be the case that one Controller use as menu handler as the needs. Handlers are responsible for processing the data and make the business logic. Handlers assume that data is clean, valid and sanity. But all the business validation MUST to be done into the handlers class, like user not found, duplicate entry, etc. Handlers MUST to return always and ApiResponse object, this is mandatory requirement. ApiResponse object can be success response or even ErrorResponse that also extends from ApiResponse class.
• Http: Contains the Request and Response objects used by the entry points. All objects into the Request folder extends from ApiRequest class, and all objects into the Response folder extends from ApiResponse class. Request are the object expected when client send the request and response is the reply object from server. The Request class are used into the Controllers class and Response class are used into the Handlers class due are the return object in the functions.
• DTO: These are abstractions of our Model data. Intances of this classes are returned to the client as pure data response. DTOs are very useful when we want to return to client a representation of our models that in fact are not the exactly copy of the model, in somehow allow to hide real data representation.
• Traits: Traits used in the Apis context.
• Util: Contains all the clases that serves utilities to the Apis. Please note that the files here are used only in the Apis context. There are others folders utils which offers and expose functions to others scopes.

Src/Command structure

• Command: The Symfony commands classes.
• Data: Some util data like hardoced files which are used by the commands.
• Services: Services which process the command business logic. Please note that the Symfony Command clasess contains only the console entry point but the real process take place into the Services clasess. The normal why to handle this is creating one Service class per Command.

Src/Connectors structure

Contains implementation for all our external services. Also note that connectors are not restricted to specific scope, can be used everywhere where is needed.

Despite of the structure inside, MUST to exist a global class that exposes the functions of the connector. The structure for each connectors is the same and basically follow the same like Http folder into the Apis.

• Dto: Contains the DTO for the specific connector. Note that connectors MUST to be isolated, in short words, can not be dependencies between them. This also include separated Dto classes.
• Request: Contains the clasess type Request used to connect to the external service.
• Response: Contains the classes type Response used to handle the response from the external service.

Src/Linkers structure

• Controller: Symfony controllers classes that expose the routes to external services.
• Managers: Its the Legacy version of linkers. Contains the old linkers version in Avantus. This Managers should be migrated to new structure or even rewrited.
• Services: Contains the services classes that process the logic for the controllers classes.

Src/Model structure

• Entity: The Symfony entity which represent the DB data.
• Interfaces: Helpers used into the entities classes.
• Migrations: Contains the migrations classes. We use DoctrineMigrations Bundle.
• Repository: Contains the repositories classes for each entity.
• Utils: Contains all the clases that serves utilities to the Model. Please note that the files here are used only in the Model context or scope. There are others folders utils which offers and expose functions to others scopes.