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 --locked

puerto 0.21.0 · MIT · Rust 1.85+


One 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.

ManifestCargo Producto ·42 files written ·8 patched ·114 in the project
Cargo
puerto nuevo
--eventos
--auth

Events and local accounts need --db.

Run
$ puerto nuevo --nombre tienda --db --sin-demo
$ puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!
Files
contextos/producto/dominio/6
contextos/producto/aplicacion/7
contextos/producto/infraestructura/5
contextos/producto/rest/6
migraciones/1
presentacion/cableado/2
presentacion/api/2
web/19
project root2
stdout
$ 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
  1. rest

    Routes, DTOs, response enums, error mapping, route tests

    rest_<c> depends on aplicacion_<c>, dominio_<c>

  2. infraestructura

    Adapters: in-memory or Postgres repositories, units of work, mail senders

    infra_<c> depends on dominio_<c>

  3. aplicacion

    Use cases, one file each: params, trait, double, implementation, tests

    aplicacion_<c> depends on dominio_<c>

  4. dominio

    Models, typed ids, value objects, errors, repository ports, events

    dominio_<c> depends on nucleo and puerto-nucleo only

One context, from the outside in. Dependencies point inward only, and each layer of each context is its own crate, so Cargo checks the rule. 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.

CargoCommandWhat you get
Entitiespuerto 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 objectsemail:Email:String estado:Estado:enum:Borrador/PagadoA type per concept, validated once in the domain, unwrapped at the edges.
Postgrespuerto nuevo --dbSQLx queries checked at compile time, migrations written for you, unique indexes that respect soft deletes.
Domain eventspuerto nuevo --db --eventos db|kafkaA transactional outbox and a worker. At-least-once delivery, retries with backoff, nothing dropped without a dead letter.
Mailpuerto generar correo bienvenida --tras cliente_creado --para emailA port, three templates, and a consumer that sends it once per event.
Authpuerto nuevo --auth oidc|localAuth0, Keycloak or your own accounts. Routes protected by default, roles in one attribute.
Frontendweb/React typed from the OpenAPI spec, with the same dependency rule as the backend.
In SpanishRepositorioProducto · crear_producto · /productosEverything generated is written in Spanish, from types to routes and error codes. One glossary names it all.
Agent rulesAGENTS.mdArchitecture, 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.

Working with agents
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 error

24 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
  1. 0001Enum value objects implement FromStr
  2. 0002Response enums allow large_enum_variant
  3. 0003Unique indexes are partial
  4. 0004generate use-case never overwrites and patches routes.rs
  5. 0005SQL reserved words are rejected only in --db projects
  6. 0006Logging through tracing, not a Logger port
  7. 0007Error contract: the code is name, validation is 422
  8. 0008Liveness, readiness and graceful shutdown in every project
  9. 0009Generated projects pin their toolchain and use edition 2024
  10. 0010Generated agent rules have a root entry point and are tested
  11. 0011Templates own the shape of generated code; types.rs owns the per-field decisions
  12. 0012Presentation holds use case ports; routes are tested with mocks
  13. 0013Web frontend: React + daisyUI on Bun, structure generated by Puerto, wire types from OpenAPI
  14. 0014Entity ids are generated newtypes
  15. 0015Repositories return one RepositoryError
  16. 0016Lists are offset pages, capped in the domain
  17. 0017Runtime crates next to the generator
  18. 0018Domain events: unit of work, outbox, pluggable transport
  19. 0019Generated code is formatted by cargo fmt
  20. 0020Mail: a port per mail, templates in infrastructure, sent from the worker
  21. 0021Auth: one Authenticator port, two adapters (OIDC, local sessions)
  22. 0022References between entities are typed ids, checked by foreign keys
  23. 0023Un crate por contexto y capa en los proyectos generados
  24. 0024Lo que genera Puerto, en castellano

Three commands
to a running API.

  1. 1

    Install the CLI.

    cargo install puerto --locked
  2. 2

    A workspace with a crate per layer, a frontend and Postgres.

    puerto nuevo --nombre tienda --db
  3. 3

    Every layer of an entity. Then make run.

    puerto generar scaffold Producto -- nombre:String precio:i64 sku:String!
Follow the quick start