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 --dbcd tiendapuerto generar scaffold Producto -- nombre:String precio:i64 sku:String!make run # Swagger UI on http://localhost:8080That 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.
Two halves
Section titled “Two halves”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.
Three principles
Section titled “Three principles”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.
Who it is for
Section titled “Who it is for”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.
What it is not
Section titled “What it is not”- 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.