# Porto SAP: Separating Business Logic from Infrastructure

> Porto is an architectural pattern that divides application code into business-oriented Containers and an infrastructure Ship layer. It is aimed at teams seeking consistent boundaries across monoliths and microservices, but adoption requires disciplined adherence to its component model.

**Mahmoudz/Porto** — A software architectural pattern that provides a comprehensive set of guidelines, principles, and patterns to organize code for high scalability, maintainability and reusability.

- Repository: https://github.com/Mahmoudz/Porto
- Website: http://porto.zalt.me
- Stars: 1,635 · Forks: 177
- Language: Unknown
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mahmoudz-porto

## Porto SAP Targets Backend Boundary Drift

Porto addresses a specific architectural problem: application code tends to accumulate features until business rules and infrastructure concerns become difficult to separate. The README contrasts this outcome with the common reaction of splitting a monolith into microservices, which can distribute the existing disorder across more services. Porto instead starts with code boundaries inside the application. Business logic belongs in Containers, while infrastructure belongs in the Ship layer. This division gives backend teams a concrete criterion for deciding where implementation code should live.

The intended audience is developers working on systems that may begin as a monolith and later move toward microservices. It also applies to teams handling systems described as high-trust or security-critical, although the README does not provide a security certification, control checklist, or compliance claim. Porto SAP is the edition intended for code that people read, review, and extend by hand, with AI acting as an assistant. A separate Porto AI edition is described as being in private testing. That distinction matters when evaluating this repository because the public documentation linked here is specifically for the human-written edition.

The project is not presented as a generator, framework, compiler, or runtime. It is a pattern and accompanying documentation. Consequently, Porto's value depends on whether developers can apply its boundaries consistently to the conventions already used by a project.

## Porto Divides Containers and Ship Infrastructure

The central mechanism is a two-layer application structure. Containers encapsulate business logic. The Ship layer contains infrastructure-related code. The README presents this separation as the basis for moving from a monolithic deployment to microservices without changing the overall organization of application code. In practical terms, the pattern treats deployment distribution as a change to where self-contained containers run, rather than as permission to mix business rules with transport, persistence, or other infrastructure concerns.

The repository includes diagrams named `porto_layers.svg` and `porto_container_interactions.svg`, which document the intended relationships. Their existence shows that the pattern has a visual model, but the README does not specify framework adapters, language bindings, directory templates, or automatic enforcement mechanisms. Porto should therefore be evaluated as an architectural rule set, not as a tool that can restructure an existing repository on its own.

This design also creates a strict review question for each class or module: does it express business behavior, or does it implement infrastructure? The README does not enumerate every technology that belongs in Ship. That missing classification guidance is significant for a real codebase, because database access, messaging, caching, and external service integration will require project-specific placement decisions.

## Actions Coordinate Single-Responsibility Tasks

Porto adds a second boundary inside each Container. Business logic is organized into Actions and Tasks. An Action initiates a sequence of Tasks, while each Task exposes one public function named `run()` and represents a single responsibility. This gives a Container an explicit coordination layer and a smaller unit for reusable work.

The documented interaction model can be stated as a simple flow. A caller invokes business behavior exposed by a Container. An Action coordinates the work required for that behavior. The Action invokes one or more Tasks, and each Task performs its assigned responsibility through `run()`. Infrastructure requirements are then handled by the Ship side of the architecture. The README does not show a complete code example, error model, dependency-injection setup, or transaction boundary, so those details cannot be treated as predefined parts of the pattern.

The `run()` rule is useful because it narrows the expected public surface of a Task. It does not, by itself, prove that a Task is cohesive or independently reusable. Teams still need to define what counts as one responsibility, how Tasks receive dependencies, and whether an Action may call other Actions. Porto offers a structural convention here, but the README leaves implementation policy to the adopting team.

## Reading Porto SAP Documentation Before Adoption

The README does not provide package installation commands, language-specific setup instructions, or a runnable starter repository. Instead, it directs readers to the Porto SAP documentation at `porto.zalt.me/docs/Intro`. There is therefore no supported installation tutorial that can be reproduced from the repository information without guessing a language, framework, package manager, or directory layout.

A first useful use begins with the linked introduction and the two architecture diagrams referenced by the README. Select one existing backend feature and classify its code into Containers, Actions, Tasks, and the Ship layer. The expected result is a written boundary map, not a running command. Record ambiguous files rather than forcing them into a layer without an explicit project rule.

The repository root contains `docs/`, `assets/`, and a `yarn.lock`, but neither the README nor the listed files establish that Porto is published as a Yarn package or that a generated project should be installed with Yarn. A lockfile alone is not installation evidence. Readers who need executable setup instructions should verify that the linked documentation supplies instructions for their specific language and framework. Until that is documented, adoption begins with architectural analysis rather than `yarn install` or an invented package command.

## Porto Can Carry Architectural Debt Into More Services

The main failure mode is boundary leakage. If business operations remain embedded in Ship components, or if Actions and Tasks become large orchestration units, the nominal structure will not provide the separation promised by the pattern. The README does not document an automated dependency check, so violations may depend on code review and developer discipline.

The microservices claim also requires caution. Porto can keep the application structure stable as containers are moved between deployments, but it does not remove distributed-system problems. The README says nothing about service discovery, data ownership, network failure, tracing, deployment orchestration, or consistency. Moving a container into a service does not automatically make its database boundaries, transactions, or external calls safe.

Porto is also the wrong tool for a small codebase that needs one library or a few endpoints and does not require an explicit architectural taxonomy. Introducing Actions, Tasks, Containers, and Ship can add structure without solving an immediate constraint. Likewise, teams unable to enforce naming and dependency rules may find the pattern descriptive rather than operational. Its benefits depend on consistent classification, not merely adding the terminology.

## MIT License and Recent Repository Activity

Porto is distributed under the MIT License. That permits use, modification, distribution, and sublicensing under the license's stated conditions, including preservation of its copyright and permission notice. This is a factual summary of the identifier, not legal advice. Teams copying substantial portions into internal architecture documents or software should review the actual `LICENSE` file for their compliance process.

The repository is not archived, and its last push was on 2026-07-04. It also has no GitHub releases. That means there is no published release history here from which to infer a stable versioning or upgrade schedule. Maintenance activity must be judged from repository facts rather than marketing language, and the absence of releases leaves questions about how breaking documentation or pattern changes will be communicated.

The upgrade cost depends on how deeply Porto has been adopted. A documentation-only team can revise layer assignments cheaply. A mature codebase may need dependency review, class and module changes, tests around Action and Task behavior, and coordination between Container and Ship code. The README does not provide migration scripts or a formal compatibility policy.

## Porto Differs from Unstructured Monolith-to-Microservices Migration

A real alternative is to begin with a conventional monolith organized primarily by technical layer, then split it into services only when operational needs justify the distribution. That approach may use controllers, services, repositories, and shared infrastructure directories, with deployment boundaries evolving separately. Porto's distinction is that it makes the deployable business-oriented unit the primary structural boundary and explicitly reserves Ship for infrastructure.

This difference affects change management. A technical-layer monolith can let a feature span several directories that share one technology classification. Porto asks teams to keep the feature's business sequence inside Containers and move infrastructure concerns outward. When a container later becomes a service, the documented intent is to preserve that organization. Neither approach automatically defines data migration or distributed transaction policy, and the README does not provide a framework-specific alternative implementation.

The relevant choice is therefore organizational. Choose Porto when consistent business-unit boundaries and a later migration path justify a new taxonomy. Retain a conventional layered monolith when the team values minimal structural overhead and already has effective module boundaries. Porto is more prescriptive about naming and responsibility, but it also asks for more review discipline.

## Conclusion

Backend teams that want one explicit structure across monoliths and microservices can adopt Porto SAP after confirming that their developers will enforce the Container, Action, Task, and Ship boundaries. Projects that need an immediately executable framework, prescribed framework integrations, or documented deployment commands should first check the linked documentation, because this repository describes an architectural pattern rather than a ready-made application package. The first adoption decision is therefore whether its self-contained units fit the team's existing code and review process.

## FAQ

### What problem does Porto solve?

Porto organizes application code into Containers for business logic and a Ship layer for infrastructure. It is intended to preserve a consistent structure when moving between monolithic and microservice deployments.

### What is the difference between Porto SAP and Porto AI?

Porto SAP is for code that people read, review, and extend by hand, with AI assistance. Porto AI is described as a separate private-testing edition for codebases maintained primarily by autonomous AI agents.

### How do Actions and Tasks differ in Porto?

Actions initiate sequences of work, while Tasks each have one public `run()` function and represent a single responsibility. The README does not provide a complete implementation example.

## Sources

- [Issues](https://github.com/Mahmoudz/Porto/issues)
- [License: MIT](https://github.com/Mahmoudz/Porto/blob/master/LICENSE)
- [Mahmoudz/Porto on GitHub](https://github.com/Mahmoudz/Porto)
- [Project website](http://porto.zalt.me)
- [README](https://github.com/Mahmoudz/Porto/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mahmoudz-porto