Routes are the first receivers of the HTTP requests.

The Routes are responsible for mapping all the incoming HTTP requests to their controller's functions.

The Routes files contain Endpoints (URL patterns that identify the incoming request).

When an HTTP request hits your Application, the Endpoints match with the URL pattern and make the call to the corresponding Controller function.

Principles:

• There are three types of Routes, API Routes, Web Routes and CLI Routes.
• The API Routes files SHOULD be separated from the Web Routes files, each in its own folder.
• The Web Routes folder will contain only the Web Endpoints, (accessible by Web browsers); And the API Routes folder will contain only the API Endpoints, (accessible by any consumer App).
• Every Container SHOULD have its own Routes.
• Every Route file SHOULD contain a single Endpoint.
• The Endpoint job is to call a function on the corresponding Controller once a request of any type is made. (It SHOULD NOT do anything else).

Controllers are responsible for validating the request, serving the request data and building a response. Validation and response, happens in separate classes, but triggered from the Controller.

The Controllers concept is the same as in MVC (They are the C in MVC), but with limited and predefined responsibilities.

Principles:

• Controllers SHOULD NOT know anything about the business logic or about any business object.
• A Controller SHOULD only do the following jobs:
  1. Reading a Request data (user input)
  2. Calling an Action (and passing request data to it)
  3. Building a Response (usually build response based on the data collected from the Action call)
• Controllers SHOULD NOT have any form of business logic. (It SHOULD call an Action to perform the business logic).
• Controllers SHOULD NOT call Container Tasks. They MAY only call Actions. (And then Actions can call Container Tasks).
• Controllers CAN be called by Routes Endpoints only.
• Every Container UI folder (Web, API, CLI) will have its own Controllers.

You may wonder why we need the Controller! when we can directly call the Action from the Route. The Controller layer helps making the Action reusable in multiple UI's (Web & API), since it doesn't build a response, and that reduces the amount of code duplication across different UI's.

Here's an example below:

• UI (Web): Route W-R1 -> Controller W-C1 -> Action A1.
• UI (API): Route A-R1 -> Controller A-C1 -> Action A1.

As you can see in the example above the Action A1 was used by both routes W-R1 and A-R1, with the help of the Controllers layer that lives in each UI.

Requests mainly serve the user input in the application. And they are very useful to automatically apply the Validation and Authorization rules.

Requests are the best place to apply validations, since the validations rules will be related to every request. Requests can also check the Authorization, e.g. check if this user has access to this controller function. (Example: check if a specific user owns a product before deleting it, or check if this user is an admin to edit something).

Principles:

• A Request MAY hold the Validation / Authorization rules.
• Requests SHOULD only be injected in Controllers. Once injected they automatically check if the request data matches the validation rules, and if the request input is not valid an Exception will be thrown.
• Requests MAY also be used for authorization, they can check if the user is authorized to make a request.

Actions represent the Use Cases of the Application (the actions that can be taken by a User or a Software in the Application).

Actions CAN hold business logic or/and they orchestrate the Tasks to perform the business logic.

Actions take data structures as inputs, manipulates them according to the business rules internally or through some Tasks, then output a new data structures.

Actions SHOULD NOT care how the Data is gathered, or how it will be represented.

By just looking at the Actions folder of a Container, you can determine what Use Cases (features) your Container provides. And by looking at all the Actions you can tell what an Application can do.

Principles:

• Every Action SHOULD be responsible for doing a single Use Case in the Application.
• An Action MAY retrieves data from Tasks and pass data to another Task.
• An Action MAY call multiple Tasks. (They can even call Tasks from other Containers as well!).
• Actions MAY return data to the Controller.
• Actions SHOULD NOT return a response. (The Controller's job is to return a response).
• An Action SHOULD NOT call another Action (If you need to reuse a big chunk of business logic in multiple Actions, and this chunk is calling some Tasks, you can create a SubAction). See the SubAction section below.
• Actions are mainly used from Controllers. However, they can be used from Events Listeners, Commands and/or other Classes. But they SHOULD NOT be used from Tasks.
• Every Action SHOULD have only a single function named run().
• The Action main function run() can accept a Request Object in the parameter.
• Actions are responsible of handling all expected Exceptions.

The Tasks are the classes that hold the shared business logic between multiple Actions accross different Containers.

Every Task is responsible for a small part of the logic.

Tasks are optional, but in most cases you find yourself in need for them.

Example: if you have Action 1 that needs to find a record by its ID from the DB, then fires an Event. And you have an Action 2 that needs to find the same record by its ID, then makes a call to an external API. Since both actions are performing the "find a record by ID" logic, we can take that business logic and put it in it's own class, that class is the Task. This Task is now reusable by both Actions and any other Action you might create in the future.

The rule is, whenever you see the possibility of reusing a piece of code from an Action, you should put that piece of code in a Task. Do not blindly create Tasks for everything, you can always start with writing all the business logic in an Action and only when you need to reuse it, create an a dedicated Task for it. (Refactoring is essential to adapt to the code growth).

Principles:

• Every Task SHOULD have a single responsibility (job).
• A Task MAY receive and return Data. (Task SHOULD NOT return a response, the Controller's job is to return a response).
• A Task SHOULD NOT call another Task. Because that will takes us back to the Services Architecture and it's a big mess.
• A Task SHOULD NOT call an Action. Because your code wouldn't make any logical sense then!
• Tasks SHOULD only be called from Actions. (They could be called from Actions of other Containers as well!).
• Tasks usually have a single function run(). However, they can have more functions with explicit names if needed. Making the Task class replace the ugly concept of function flags. Example: the FindUserTask can have 2 functions byId and byEmail, all internal functions MUST call the run function. In this example the run can be called at the end of both funtions, after appending Criteria to the repository.
• A Task SHOULD NOT be called from Controller. Because this leads to non-documented features in your code. It's totally fine to have a lot of Actions "example: FindUserByIdAction and FindUserByEmailAction where both Actions are calling the same Task" as well as it's totally fine to have single Action FindUserAction making a decision to which Task it should call.
• A Task SHOULD NOT accept a Request object in any of its functions. It can take anything in its funtions parameters but never a Request object. This will keep free to use from anwyhere, and can be tested independently.

The Models provide an abstraction for the data, they represent the data in the database. (They are the M in MVC).

Models are responsible for how the data should be handled. They make sure that data arrives properly into the backend store (e.g. Database).

Principles:

• A Model SHOULD NOT hold business logic, it can only hold the code and data that represents itself. (it's relationships with other models, hidden fields, table name, fillable attributes,...)
• A single Container MAY contain multiple Models.
• A Model MAY define the Relations between itself and any other Models (in case a relation exist).

Views contain the HTML served by your application.

Their main goal is to separate the application logic from the presentation logic. (They are the V in MVC).

Principles:

• Views can only be used from the Web Controllers.
• Views SHOULD be separated into multiple files and folders based on what they display.
• A single Container MAY contain multiple Views files.

Transformers (are the short name for Responses Transformers).

They are equivalent to Views but for JSON Responses. While Views takes data and represent it in HTML, Transformers takes data and represent it in JSON.

Transformers are classes responsible for transforming Models into Arrays.

Transformers takes a Model or a group of Models "Collection" and converts it to a formatted serializable Array.

Principles:

• All API responses MUST be formatted via Transformers.
• Every Model (that gets returned by an API call) SHOULD have a Transformer.
• A single Container MAY have multiple Transformers.
• Usually every Model would have a Transformer.

Exceptions are also a form of output that should be expected (like an API exception) and well defined.

Principles:

• There are container Exceptions (live in Containers) and general Exceptions (live in Ship).
• Tasks, Sub-Tasks, Models and any class in general can throw a very specific Exception.
• The caller MUST handle all expected Exceptions from the called class.
• Actions MUST handle all Exceptions, and making sure they don't leak to upper Components, and cause unexpected behaviors.
• Exceptions names SHOULD be as specific as possible and they SHOULD have a clear descriptive messages.

SubActions are designed to eliminate code duplication in Actions. Don't get confused! SubActions do not replace Tasks.

While Tasks allows Actions to share a piece of functionality. SubActions allows Actions to share a sequence of Tasks.

The SubActions are created to solve a problem. The problem is: Sometimes you need to reuse a big chunk of business logic in multiple Actions. That chunk of code is already calling some Tasks. (Remember a Task SHOULD NOT call other Tasks) so how shall you reuse that chunk of code without creating a Task! The solution is create a SubAction.

Detailed Example: assuming an Action A1 is calling Task1, Task2 and Task3. And another Action A2 is calling Task2, Task3, Task4 and Task5. Notice both Actions are calling Tasks 2 and 3. To eliminate code duplication we can create a SubAction that contains all the common code between both Actions.

Principles:

• Sub-Actions MUST call Tasks. If a Sub-Actions is doing all the business logic, without the help of at least 1 Tasks, it probably shouldn't be a Sub-Action but a Task instead.
• A Sub-Action MAY retrieves data from Tasks and pass data to another Task.
• A Sub-Action MAY call multiple Tasks. (They can even call Tasks from other Containers as well!).
• Sub-Actions MAY return data to the Action.
• Sub-Action SHOULD NOT return a response. (the Controller job is to return a response).
• Sub-Action SHOULD NOT call another Sub-Action. (try to avoid that as much as possible).
• Sub-Action SHOULD be used from Actions. However, they can be used from Events, Commands and/or other Classes. But they SHOULD NOT be used from Controllers or Tasks.
• Every Sub-Action SHOULD have only a single function named run().

In Porto, your application business logic lives in Containers. Porto Containers are similar in nature to the Modules (from the Modular architecture) and Domains (from the DDD architecture).

Containers can depend on other Containers, similar to how a layer can depend on other layers in a layered architecture.

Porto's rules and guidelines minimizes and defines the dependecies directions between Containers, to avoid circular references between them.

And it allows the grouping of related Containers into sections, in order to reuse them together in different projects. (each Section contains a reusable portion of your application business logic).

In terms of dependency management, the developer is free to move each Container to its own repository or keep all Containers together under single repository.

Porto aim to reduce maintance cost by saving developers time. It's structured in a way to insure code decoupling, and forces consistency which all contribute to its maintainability.

Having a single function per class to describe a functionality, makes adding and removing features an easy process.

Porto has a very organized code base and a zero code decoupling. In addition to clear development workflow with predefined data flow and dependencies directions. That all contributes to its scalability.

Extremely adhering to the single responsibility principle by having single function per class, results in having super slim classes, which leads to easier testability.

In Porto each component expect the same type of input and output, which makes testing, mocking and stabbing very simple.

The Porto structure itself makes writing automated tests a smooth process. As it has a tests folder at the root of each Container for contaning the unit tests of your Tasks. And a tests folder in each UI folder for contaning the functional tests (for testing each UI's separately).

The secret of making the testing and debugging easy, is not only in the organization of the tests and pre defined responsiblity of the components but also in the decoupling of your code.

With Porto you can easily accommodate future changes with the least amount of efforts.

Let's assume you have a web app that serves HTML and recently you decided that you need to have a Mobile app, hence you need an API.

Porto has pluggable UI's (WEB, API & CLI) and this allows writting the business logic of your application first, then implementing a UI to interact with your code.

This gives the flexibility to adding interfaces whenever needed and adapting to future changes, with the least effort possible.

it is all possible because the Actions are the central organizing principle "not the controller" which are shared across multiple UI's. And the UI's are separated from the application business logic and separated from each others within each Container.

Porto makes it super easy to locate any feature/functionality. And to understand what's happening inside it.

That due to the usage of the domain expert language when naming the classes "components". As well as the single function per class golden rule. Which allows you to find any Use Case (Action) in your code by just browsing the files.

Porto promises that you can find any feature implementation in less than 3 seconds! (example: if you are looking for where the user address is being validated - just go to the Address Container, open the list of Actions and search for ValidateUserAddressAction).

Porto's takes future growth into consideration and it ensures your code remains maintainable no matter what the project size becomes.

It achieves this by its modular structure, separation of concerns and the organized coupling between the internal classes "Components".

This allows modifications to be made without undesirable side effects.

Porto gives the ability to move quickly and easily.

It's easy to make framework upgrades due to the complete separation between the App and the framework code through the Ship layer.