Porto (Software Architectural Pattern)

Welcome to Porto

• Introduction
• Getting Started
  • Layers Overview
  • 1) Ship Layer
  • 2) Containers Layer
    • Containers
    • Sections
• Components
  • 1) Main Components
    • 1.1) Components Interaction Diagram
    • 1.2) Request Life Cycle
    • 1.3) Main Components Definitions & Principles
      • Routes
      • Controllers
      • Requests
      • Actions
      • Tasks
      • Models
      • Views
      • Transformers
      • Exceptions
      • Sub-Actions
  • 2) Optional Components
• Typical Container Structure
• Porto Quality Attributes
• Implementations (Built with Porto)
• Feedback & Questions

Introduction

Porto is a modern software architectural pattern that offers developers a comprehensive set of guidelines, principles, and patterns to organize their code in a highly maintainable and reusable way. The primary goal of Porto is to help developers create software that is scalable, flexible, and easy to maintain over time.

"Simplicity is the ultimate sophistication." - Leonardo da Vinci

Porto is particularly well-suited for medium to large-sized web projects that require a high degree of flexibility and scalability. With Porto, developers can build highly scalable monoliths that can be easily split into multiple microservices whenever needed. This approach enables the reuse of business logic or application features across multiple projects, making it an ideal choice for teams that work on a variety of different projects.

It is built on a foundation of several established architectural concepts, including Domain Driven Design (DDD), Modular, Micro Kernel, Model View Controller (MVC), Layered, and Action Domain Responder (ADR) architectures. By drawing on these established concepts, Porto provides developers with a reliable and well-tested framework for building software.

In addition to these foundational concepts, Porto also adheres to a set of well-established design principles such as SOLID, OOP, LIFT, DRY, CoC, GRASP, Generalization, High Cohesion, and Low Coupling. These principles are designed to ensure that software built using Porto is maintainable, scalable, and easy to understand.

Overall, Porto is a powerful and flexible software architecture pattern that offers developers a comprehensive set of tools for building scalable, maintainable, and reusable software. Whether you are working on a small project or a large-scale enterprise application, Porto can help you build software that meets your needs today and in the future.

Note: Porto started as an experimental architecture designed to solve common problems that web developers face when building large projects. Since its inception, Porto has become a beloved software architecture pattern among developers, offering a powerful set of tools for building scalable, maintainable, and reusable software. Feedbacks & Contributions are much appreciated.

Getting Started

Layers Overview

Porto is composed of two layers: "Containers" and "Ship".

• The Containers layer holds all your application business logic code.
• The Ship layer holds the infrastructure code (shared code between all Containers).

These layers can be created anywhere inside any framework of your choice. For example, in Laravel or Rails, they can be created in the app/ directory or in a new src/ directory at the root.

By separating your application code into these two layers, Porto allows you to keep your business logic separate from your infrastructure code, making it easier to maintain and update your application over time. The Containers layer contains all of your application-specific code, while the Ship layer contains shared code that can be used across multiple Containers.

This separation of concerns also allows you to easily scale your application by adding or removing Containers as needed, without affecting the underlying infrastructure code. With Porto, you can create a scalable and maintainable software architecture that can adapt to your changing needs over time.

Visual Overview

Before diving deeper, let's take a moment to understand the different levels of code you will have in your codebase:

Code Levels

• Low-level code: the framework code (implements basic operations like reading files from a disk or interacting with a database). Usually lives in the Vendor directory.
• Mid-level code: the application general code (implements functionality that serves the High-level code and relies on the Low-level code to function). Should be in the Ship layer.
• High-level code: the business logic code (encapsulates complex logic and relies on the Mid-level code to function). Should be in the Containers layer.

By understanding these three levels of code, you can better organize your codebase and ensure that each level is responsible for the appropriate tasks. The Low-level code provides the basic functionality for your application, while the Mid-level code serves as a bridge between the Low-level and High-level code. The High-level code contains your application-specific business logic and encapsulates complex operations.

With Porto, you can easily separate your code into these different levels and ensure that each level is responsible for the appropriate tasks. This separation of concerns helps to make your code more maintainable and scalable over time.

Layers Diagram

To better visualize the relationship between the Containers layer, Ship layer, and the underlying Framework, you can think of the Containers layer as cargo containers that rely on the Ship layer (the cargo ship) which in turn relies on the underlying Framework (the sea). This diagram illustrates the relationship between the different layers:

Containers layer (cargo containers) >> relies on >> Ship layer (cargo ship) >> relies on >> Framework (sea)

Monolithic to "Micro" Services

Porto is designed to scale with you! While many companies shift from Monolithic to Micro-Services (and more recently Serverless) as they scale up, Porto offers the flexibility to deflate your Monolithic into Micro-Services (or SOA) at any time with minimal effort.

In Porto terms, a Monolithic is equivalent to one cargo ship of Containers, while Micro-Services are equivalent to multiple cargo ships of Containers (disregarding their sizes). This means that with Porto, you can start small with a single, well-organized Monolithic service and grow as needed by extracting containers into multiple services as your team and business grow.

By organizing your code into Containers, which are grouped into isolated Sections, Porto makes it easy to extract individual Sections and deploy them separately as Micro-Services. This allows you to scale your application architecture as your needs evolve over time, without having to rebuild your entire application from scratch.

However, operating multiple services instead of a single Monolithic service can increase the cost of maintenance (with multiple repositories, CI pipelines, etc.) and requires a new approach to service communication. How Sections "Services" communicate with each other is completely up to the developers, although Porto recommends using Events and/or Commands.

With Porto, you can create a scalable and flexible software architecture that can adapt to your changing business needs. This allows you to stay ahead of the competition and provide the best possible experience for your users.

1) Ship Layer

The Ship layer is a critical component of the Porto architecture. It contains the Parent "Base" classes, which are classes extended by every single component, as well as some Utility Code.

The Parent classes in the Ship layer give developers full control over the Container's Components. For example, adding a function to the Base Model class makes it available in every Model in your Containers, saving time and effort.

The Ship layer also plays an important role in separating the Application code from the Framework code. This separation facilitates upgrading the Framework without affecting the Application code, making it easier to maintain and update your application over time.

In Porto, the Ship layer is kept slim and focused, containing only the essential Parent classes and utility code. It does not include common reusable functionalities such as Authentication or Authorization, as these functionalities are provided by the Containers. This gives developers more flexibility to customize their application to meet their specific needs.

By separating the infrastructure code from the business logic code, Porto allows you to keep your application code organized and maintainable, while also providing the flexibility to customize and scale your application as needed.

Ship Structure

The Ship layer is composed of several types of code that work together to power your application:

• The Core Code: This is the engine of the ship that auto-registers and auto-loads all your Container's Components to boot your Application. It contains most of the magical code that handles everything that is not part of your business logic, and mostly contains code that facilitates development by extending the framework features.

• The Containers shared code:

  • Parent Classes: These are the base classes of each Component in your Container. Adding functions to the Parent Classes makes them available in every Container, and Parents are designed to contain shared code between your Containers.
  • Generic Classes: These are reusable features and classes that can be used by every Container, such as Global Exceptions, Application Middleware, Global Config files, and more.

It's important to note that all of the Container's Components must extend or inherit from the Ship layer, particularly the Parent folder.

When separating the Core into an external package, the Ship Parents should extend from the Core Parents (which can be named Abstract, since most of them are supposed to be Abstract Classes). The Ship Parents hold your custom Application shared business logic, while the Core Parents (Abstracts) hold your framework's common code. Essentially, anything that is not business logic should be hidden from the actual Application being developed.

By organizing your code in this way, Porto makes it easy to maintain and update your application over time, while also allowing you to extend and customize the framework features to meet your specific needs.

2) Containers Layer

The Containers layer is the heart of the Porto architecture. Here is where the application-specific business logic lives, including all the Application features and functionalities. You'll spend 90% of your time working in this layer, developing new features, and maintaining existing ones.

One of the main benefits of using Porto is that it manages the complexity of a problem by breaking it down into smaller, more manageable Containers. Each Container is designed to encapsulate a specific piece of functionality, making it easier to develop, test, and maintain.

By organizing your code in this way, Porto helps you to create a more modular and reusable codebase. This makes it easier to scale and maintain your application over time, as well as reducing the amount of code duplication across different parts of your application.

Overall, the Containers layer is the key to building a maintainable and scalable application architecture with Porto.

Containers

A Container is a self-contained module that encapsulates a specific piece of functionality in your application. It can be a feature, a wrapper around a RESTful API resource, or anything else you need.

Example 1:

For example, in a TODO App, the 'Task', 'User', and 'Calendar' objects would each live in a different Container, with its own Routes, Controllers, Models, Exceptions, and more. Each Container is responsible for receiving requests and returning responses from whichever supported UI (Web, API, etc.).

While it's advised to use a Single Model per Container, in some cases, you may need more than one Model, and that's perfectly fine. You could also have Value Objects, which are similar to Models but don't get represented in the DB on their tables but as data on the Models. These objects get built automatically after their data is fetched from the DB, such as Price, Location, Time, and more.

It's important to keep in mind that two Models mean two Repositories, two Transformers, and more. Unless you want to use both Models always together, split them into two Containers.

If you have high dependencies between two Containers, placing them in the same Section would make reusing them easier in other projects.

Example 2:

For example, if you look at Apiato, the first project implementing Porto, you will notice that Authentication and Authorization are both features provided as Containers.

By breaking down your application into smaller, more manageable Containers, Porto makes it easier to develop, test, and maintain your codebase over time.

Basic Containers Structure

Container 1
	├── Actions
	├── Tasks
	├── Models
	└── UI
	    ├── WEB
	    │   ├── Routes
	    │   ├── Controllers
	    │   └── Views
	    ├── API
	    │   ├── Routes
	    │   ├── Controllers
	    │   └── Transformers
	    └── CLI
	        ├── Routes
	        └── Commands

Container 2
	├── Actions
	├── Tasks
	├── Models
	└── UI
	    ├── WEB
	    │   ├── Routes
	    │   ├── Controllers
	    │   └── Views
	    ├── API
	    │   ├── Routes
	    │   ├── Controllers
	    │   └── Transformers
	    └── CLI
	        ├── Routes
	        └── Commands

Containers Communication

Containers can communicate with each other in a variety of ways within the same Section:

• A Container may depend on one or many other Containers.
• A Controller may call Tasks from another Container.
• A Model may have a relationship with a Model from another Container.
• Other forms of communication are also possible, such as via Events and Commands.

If you use Event-based communication between Containers, you can use the same mechanism after splitting your codebase into multiple services.

Note that if you're not familiar with separating your code into Modules/Domains or if you prefer not to use that approach, you can create your entire Application in a single Container. However, this is not recommended and may not be as scalable or maintainable over time.

Sections

Section are another very important aspect in the Porto architecture.

A Section is a group of related containers. It can be a service (micro or bigger), or a sub-system within the main system, or anything else.

Think of a Section as a rows of containers on a cargo ship. Well organized containers in rows, speeds up the loading and unloading of related containers for a specific customer.

The basic definition of a Section is a folder that contains related Containers. However the benefits are huge. (A section is equivalent to a bounded context from the Domain-driven design) Each section represents a portion of your system and is completely isolated from other sections.

A Section can be deployed separately.

Example 1:

If you're building a racing game like Need for Speed, you may have the following two sections: the Race Section and the Lobby Section, where each section contains a Car Container and a Car Model inside it, but with different properties and functions. In this example the Car Model of the Race section can contain the business logic for accelerating and controlling the car, while the Car Model of the Lobby Section contains the business logic for customizing the car (color, accessories..) before the race.

Sections allows separating large Model into smaller ones. And they can provide boundaries for different Models in your system.

If you prefer simplicity or you have only single team working on the project, you can have no Sections at all (where all Containers live in the containers folder) which means your project is a single section. In this case if the project grew quickly and you decided you need to start using sections, you can make a new project also with a single section, this is known as Micro-Services. In Micro-Services each section "project portion" live in its own project (repository) and they can communicate over the network usually using the HTTP protocol.

Example 2:

In a typical e-commerce application you can have the following sections: Inventory Section, Shipping Section, Order Section, Payment Section, Catalog Section and more...

As you can imagine each of these Sections can be a micro-service by itself. And can be extracted and deployed on its own server based on the traffic it receives.

Sections Communication

• A Section MUST be isolated and SHOULD NOT depend on any other Section.
• A Section MAY listen to events fired by other Sections. (Commands can be used as an alternative to events.)

This architecture allows for a loose coupling between Sections, enabling a more scalable and flexible system. Events and commands can be used to communicate between different Sections, allowing for easy expansion and modification of the system over time.

Components

In the Container layer, there's a set of Components "Classes" with predefined responsibilities. Every single piece of code you write should live in a Component (class function). Porto defines a huge list of those Components for you, along with a set of guidelines to follow when using them, to keep the development process smooth.

Components ensure consistency and make your code easier to maintain as you already know where each piece of code should be found.

Components Types

Every Container consists of a number of Components, in Porto the Components are split into two Types: Main Components and Optional Components.

• Main Components: the essential Components that you will need for your Container. These Components are mandatory and are meant to be used to achieve the main functionality of your Container.

• Optional Components: these are Components that you can use to add additional functionality to your Container. They are optional and you can choose to use them or not, depending on your requirements.

By using these Components, you can create a modular and reusable codebase, making it easier to maintain and modify your code in the future.

1) Main Components

You must use these Components as they are essential for almost all types of Web Apps:

Routes - Controllers - Requests - Actions - Tasks - Models - Views - Transformers.

Views: should be used in case the App serves HTML pages.
Transformers: should be used in case the App serves JSON or XML data.

For detailed definitions and principles of each of the main components, please refer to the "Some Components Definitions & Principles" section below.

1.1) Main Components Interaction Diagram

1.2) The Request Life Cycle

The Request Life Cycle is the process through which an API call navigates through the main components of a Porto application. The following steps describe a basic API call scenario:

1. The User calls an Endpoint in a Route file.
2. Endpoint calls a Middleware to handle the Authentication.
3. Endpoint calls its corresponding Controller function.
4. The Request object, which is automatically injected in the Controller, applies the request validation and authorization rules.
5. Controller calls an Action and passes the data from the Request object to it.
6. Action executes the business logic, or it can call as many Tasks as needed to execute reusable subsets of the business logic.
7. Tasks execute reusable subsets of the business logic, with each Task responsible for a single portion of the main Action.
8. Action prepares the data to be returned to the Controller, and may collect data from the Tasks if needed.
9. Controller builds the response using a View or Transformer, and sends it back to the User.

It is important to note that the Request object handles request validation and authorization rules, while the Action executes the business logic. The Tasks can be used to execute reusable subsets of the business logic, with each Task responsible for a single portion of the main Action. The View or Transformer is used to build the response that is sent back to the User.

1.3) Some Components Definitions & Principles

Click on the arrows below to read about each component.

2) Optional Components

There are several optional components that can be added to your application based on your specific needs. While not all of them may be necessary, some are highly recommended. These components include:

• Tests: for automated testing of your application
• Events: for broadcasting and listening to application events
• Listeners: for handling application events
• Commands: for creating custom CLI commands
• Migrations: for managing changes to your database schema
• Seeders: for seeding your database with test data
• Factories: for generating test data
• Middlewares: for handling HTTP requests and responses
• Repositories: for abstracting data persistence logic
• Criteria: for querying your database with complex criteria
• Policies: for defining authorization policies
• Service Providers: for registering services with the application container
• Contracts: for defining interfaces to be implemented by classes
• Traits: for sharing code between classes
• Jobs: for executing long-running tasks in the background
• Values: for representing simple value objects
• Transporters: for sending and receiving data between systems
• Mails: for sending email messages
• Notifications: for sending notifications to users
• And more...: add additional components as needed

Feel free to add these components to your application as needed to improve its functionality and maintainability.

Typical Container Structure

A Container with a list of Main and Optional Components.

Container
	├── Actions
	├── Tasks
	├── Models
	├── Values
	├── Events
	├── Listeners
	├── Policies
	├── Exceptions
	├── Contracts
	├── Traits
	├── Jobs
	├── Notifications
	├── Providers
	├── Configs
	├── Mails
	│   ├── Templates	
	├── Data
	│   ├── Migrations
	│   ├── Seeders
	│   ├── Factories
	│   ├── Criteria
	│   ├── Repositories
	│   ├── Validators
	│   ├── Transporters
	│   └── Rules
	├── Tests
	│   ├── Unit
	│   └── Traits
	└── UI
	    ├── API
	    │   ├── Routes
	    │   ├── Controllers
	    │   ├── Requests
	    │   ├── Transformers
	    │   └── Tests
	    │       └── Functional
	    ├── WEB
	    │   ├── Routes
	    │   ├── Controllers
	    │   ├── Requests
	    │   ├── Views
	    │   └── Tests
	    │       └── Acceptance
	    └── CLI
	        ├── Routes
	        ├── Commands
	        └── Tests
	            └── Functional

Porto Quality Attributes

The benefits of using Porto.

Implementations

Feel free to list your implementation here.

List of projects implementing the Porto architecture.

• PHP
  • Laravel
    • Apiato (By the Porto creator) A PHP Framework for building scalable API's on top of Laravel.
    • Laravel Large Project An example project to show how to build large projects with Porto.
  • Zend Expressive
    • Expressive Porto An implementation of the Porto architecture with Zend Expressive.
• JavaScript
• Python
  • Django
    • PyPorto A design for building scalable and testable applications with Django Rest Framework.
• Ruby
• Java
• C#
• ...

Get in Touch

Your feedback is important.

We hope this documentation has provided you with a comprehensive overview of Porto SAP and its benefits. As with any software architecture pattern, Porto is continually evolving, and we welcome your feedback and contributions to help make it even better. If you have any suggestions or questions about Porto, feel free to reach out.

Author

Mahmoud Zalt Twitter: @mahmoudz Site: zalt.me

Donations

Become a Github Sponsor.
Direct donation via Paypal.
Become a Patreon.

License

MIT © Mahmoud Zalt