Scaffold. Structure. Ship.
A Rust framework that generates a Domain-Driven Design backend, with its database, events, auth and frontend, from one manifest.
cargo install puerto --lockedOne command.
Every layer.
Pick an entity and the flags of puerto nuevo. Every file below was written by puerto 0.21.0 itself, captured when this site was built. Nothing is typed for the page.
$ puerto nuevo --nombre tienda --db --sin-demo
✓ .zed/snippets/rust.json + sql.json (Zed — loaded automatically from project root)
✓ .zed/snippets/typescript.json + tsx.json (the web/ frontend)
✓ .vscode/puerto.code-snippets + puerto.sql.code-snippets (VS Code — loaded automatically)
✓ .vscode/puerto.ts.code-snippets (the web/ frontend)
nvim+LuaSnip: require("luasnip.loaders.from_vscode").lazy_load({ paths = { "./.vscode" } })
├── nucleo/ (shared value objects)
├── contextos/ (one crate per context and layer)
├── presentacion/ (the binaries and their wiring)
├── web/ (React frontend)
└── Cargo.toml
✓ Project 'tienda' created.
Next steps:
cd tienda
make run
make web/install && make web/dev # in another terminal
API docs available at http://localhost:8080
Frontend available at http://localhost:5173
Add an entity with: puerto generar scaffold <Name>
$ puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!
✓ contextos/producto/dominio/ — model, errors, repository port, MadreProducto
✓ contextos/producto/aplicacion/ — create, get, list, update, delete
✓ contextos/producto/infraestructura/ — RepositorioProductoPostgres
✓ contextos/producto/rest/ — routes, dto, responses, errors
✓ web/ — list, detail and form screens, HTTP repository
✓ Done. Zero manual wiring.
The API changed. Next: make web/sync (exports the spec, regenerates the web types)
✓ Migration 'crear_tabla_producto' created in migraciones/
Schema pre-filled — run: make sqlx/migrate && make sqlx/prepare
Same shape,
every project.
Shipping got fast when every container became the same size. Puerto does that to your code: four crates per context, one dependency rule, the same files in the same places. Whoever opens a Puerto project, a new hire or an agent, knows where everything is on day one.
The rule is not a convention you keep. Each layer is a crate, so a domain model that reaches for the database does not compile.
How the layers fit together- rest
Routes, DTOs, response enums, error mapping, route tests
rest_<c> depends on aplicacion_<c>, dominio_<c>
- infraestructura
Adapters: in-memory or Postgres repositories, units of work, mail senders
infra_<c> depends on dominio_<c>
- aplicacion
Use cases, one file each: params, trait, double, implementation, tests
aplicacion_<c> depends on dominio_<c>
- dominio
Models, typed ids, value objects, errors, repository ports, events
dominio_<c> depends on nucleo and puerto-nucleo only
presentacion/, the wiring and the binaries, sees them all.What comes
on board.
Each line is a flag or a command, and a guide. What a project does not ask for, it does not compile.
| Cargo | Command | What you get |
|---|---|---|
| Entities | puerto generar scaffold Producto -- nombre:String sku:String! | A model with its own id type, five use cases, five routes, the wiring and the screens. Every piece with its tests. |
| Value objects | email:Email:String estado:Estado:enum:Borrador/Pagado | A type per concept, validated once in the domain, unwrapped at the edges. |
| Postgres | puerto nuevo --db | SQLx queries checked at compile time, migrations written for you, unique indexes that respect soft deletes. |
| Domain events | puerto nuevo --db --eventos db|kafka | A transactional outbox and a worker. At-least-once delivery, retries with backoff, nothing dropped without a dead letter. |
puerto generar correo bienvenida --tras cliente_creado --para email | A port, three templates, and a consumer that sends it once per event. | |
| Auth | puerto nuevo --auth oidc|local | Auth0, Keycloak or your own accounts. Routes protected by default, roles in one attribute. |
| Frontend | web/ | React typed from the OpenAPI spec, with the same dependency rule as the backend. |
| In Spanish | RepositorioProducto · crear_producto · /productos | Everything generated is written in Spanish, from types to routes and error codes. One glossary names it all. |
| Agent rules | AGENTS.md | Architecture, commands and review tiers for every coding agent, tested against the generator. |
Written by agents.
Reviewed by rustc.
An agent that has used repositories elsewhere reaches for guardar, save. In a Puerto project with domain events, the repository has none: writes go through a unit of work that records the event. So the mistake is not a bug found in production. It is this, captured from a real cargo check on a generated project.
Every project also ships an AGENTS.md with its architecture, its commands and which changes a person must read, and Puerto’s own tests keep it true.
async fn ejecutar(&self, params: ParamsPublicarProducto) -> Result<Producto, ErrorProducto> {
tracing::info!(id = %params.id, "publicar_producto: inicio");
let mut producto = self
.repositorio
.buscar_por_id(params.id)
.await?
.ok_or(ErrorProducto::NoEncontrado)?;
producto.actualizado_en = chrono::Utc::now();
self.repositorio.guardar(&producto).await?;
Ok(producto)
}error[E0599]: no method named `guardar` found for struct `Arc<(dyn RepositorioProducto + 'static)>` in the current scope
--> contextos/producto/aplicacion/src/publicar_producto.rs:51:26
|
51 | self.repositorio.guardar(&producto).await?;
| ^^^^^^^ method not found in `Arc<(dyn RepositorioProducto + 'static)>`
For more information about this error, try `rustc --explain E0599`.
error: could not compile `aplicacion_producto` (lib) due to 1 previous error24 decisions,
written down.
Every trade-off that the code cannot show has a record: the context, the alternatives, what it costs. So the next person, or the next agent, inherits the reason instead of undoing it.
Read the decisions- 0001Enum value objects implement FromStr
- 0002Response enums allow large_enum_variant
- 0003Unique indexes are partial
- 0004generate use-case never overwrites and patches routes.rs
- 0005SQL reserved words are rejected only in --db projects
- 0006Logging through tracing, not a Logger port
- 0007Error contract: the code is name, validation is 422
- 0008Liveness, readiness and graceful shutdown in every project
- 0009Generated projects pin their toolchain and use edition 2024
- 0010Generated agent rules have a root entry point and are tested
- 0011Templates own the shape of generated code; types.rs owns the per-field decisions
- 0012Presentation holds use case ports; routes are tested with mocks
- 0013Web frontend: React + daisyUI on Bun, structure generated by Puerto, wire types from OpenAPI
- 0014Entity ids are generated newtypes
- 0015Repositories return one RepositoryError
- 0016Lists are offset pages, capped in the domain
- 0017Runtime crates next to the generator
- 0018Domain events: unit of work, outbox, pluggable transport
- 0019Generated code is formatted by cargo fmt
- 0020Mail: a port per mail, templates in infrastructure, sent from the worker
- 0021Auth: one Authenticator port, two adapters (OIDC, local sessions)
- 0022References between entities are typed ids, checked by foreign keys
- 0023Un crate por contexto y capa en los proyectos generados
- 0024Lo que genera Puerto, en castellano
Three commands
to a running API.
- 1
Install the CLI.
cargo install puerto --locked - 2
A workspace with a crate per layer, a frontend and Postgres.
puerto nuevo --nombre tienda --db - 3
Every layer of an entity. Then make run.
puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!