Skip to content

What Puerto is

Puerto is a Rust framework for building backends the way Rails and Laravel let you build them: one command gives you the whole piece, wired and tested. The difference is the shape of what you get. Instead of models and controllers, Puerto generates a Domain-Driven Design project with Clean Architecture: your business rules live in crates that depend on no framework, and everything else is an adapter around it.

puerto nuevo --nombre tienda --db
cd tienda
puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!
make run # Swagger UI on http://localhost:8080

That scaffold writes a Producto entity with its own id type, a validated model, an error enum, a repository port and its Postgres adapter, a migration with a partial unique index, five use cases with their unit tests, five routes with their route tests, the DTOs, the error mapping, the dependency wiring and a React screen for each action. Then it formats everything with cargo fmt. Nothing is left as todo!().

What Puerto generates is in Spanish: the commands, the manifest, the code, the routes and the error codes (contextos/producto/, crear_producto, producto.no_encontrado). Reading a generated project glosses the names you will meet first.

A generator. The puerto CLI writes code from puerto.toml, the manifest that describes your entities, their fields and their use cases. Generated code is yours: plain Rust in your repository, with no macro hiding the wiring, so you, your editor and your agent can follow every call.

A runtime. What is identical in every project and not meant to be edited is not copied in. It lives in crates (puerto-nucleo, puerto-web, puerto-sqlx and the rest) released in lockstep with the CLI, so a fix reaches your project through cargo update. ADR-0017 draws the line.

Convention over configuration. Directory layout, error codes, dependency injection, logging, tests and module declarations are decided once, so every Puerto project looks the same. Whoever opens one, a teammate or an agent, already knows where everything is.

The compiler is the reviewer. Puerto prefers a compile error to a convention you have to remember. Each entity’s id is its own type, so passing a customer id where an order id goes does not compile. In a project with domain events the repository has no guardar (save), so a write that skips the outbox does not compile. Error mappers have no catch-all arm, so a new error variant does not compile until it has an HTTP status.

AI-ready. Every project ships an AGENTS.md, and a CLAUDE.md that imports it, describing its architecture, commands and conventions. Puerto’s tests check it against the generator, so it cannot drift. Add the compiler’s precise errors, and an agent working on a Puerto project gets corrected in seconds instead of in review. See Working with agents.

Rust developers who miss the productivity of Rails, Laravel or Django and do not want to design an architecture from scratch for every service. And teams that write much of their code with coding agents, and want a structure that keeps that code honest.

  • Not a web framework. HTTP is poem with poem-openapi, and the database is SQLx on Postgres. Puerto decides how they fit together; it does not replace them.
  • Not an ORM. Repositories are written-out SQL that you can read and change.
  • Not stable yet. Puerto is 0.x. Breaking changes are listed in the changelog, with a migration guide when there are projects to migrate. 0.21, which changed the layout and the language of everything generated, has none.