Anatomy of a project
A Puerto project is a Cargo workspace with four crates per entity, one per layer, plus the
binaries that wire them and a React frontend. Each entity is a context, under contextos/. This
is tienda, with one entity, after puerto generar scaffold Producto:
- puerto.toml the manifest: entities, fields, use cases
- AGENTS.md rules for coding agents (CLAUDE.md imports it)
- Makefile run, test, lint, format, migrate…
- rust-toolchain.toml Rust 1.95.0, pinned
- Cargo.toml the workspace: members by glob, every crate in workspace.dependencies
Directorynucleo/ shared value objects: no I/O
- …
Directorycontextos/
Directoryproducto/ one context: four crates
Directorydominio/ dominio_producto: the domain, no framework
Directorysrc/
- lib.rs one pub mod per file
- modelo.rs Producto, IdProducto, PropsProducto, the rules
- errores.rs ErrorProducto: machine-readable codes
- repositorio.rs RepositorioProducto, the port, + its mock
- valores.rs when a field has a value object
- pruebas/madres.rs MadreProducto, for tests in every crate
Directoryaplicacion/ aplicacion_producto: the use cases
Directorysrc/
- crear_producto.rs params, trait, mock, implementation and tests
- …
Directoryinfraestructura/ infra_producto: adapters of the domain’s ports
- src/repositorio.rs RepositorioProductoEnMemoria, or …Postgres with –db
Directoryrest/ rest_producto: the HTTP API, poem-openapi
Directorysrc/
- rutas.rs ApiProducto: five endpoints, with route tests
- dto.rs the wire types
- respuestas.rs one response enum per endpoint
- errores.rs a_respuesta_error: ErrorProducto → HTTP status
Directorypresentacion/
Directorycableado/ the composition root: repositories and use cases, regenerated
- …
Directoryapi/ the binary
Directorysrc/
- main.rs starts the server from puerto-web
- app.rs yours: middleware and routes of your own
- generado/bootstrap.rs mounts the APIs on cableado, regenerated
Directoryweb/ React + daisyUI on Bun: same layers, see The web frontend
- …
- docs/api/openapi.json the API contract, exported by a test
--db adds migraciones/ (the SQL of the whole database), the migrador crate,
docker-compose.yml and a Postgres repository per entity. --eventos adds a second binary,
presentacion/worker/. --auth adds the usuario context and its routes. Each has its own guide.
Reading a generated project
Section titled “Reading a generated project”Puerto is built for its author’s own projects, which are written in Spanish, so everything it generates is in Spanish too (ADR-0024). Puerto’s own source and this site stay in English. The names you will meet first:
| In the code | Means |
|---|---|
contextos/, nucleo |
contexts, core (the shared value objects) |
dominio, aplicacion, infraestructura (infra_<c>), presentacion |
domain, application, infrastructure, presentation |
cableado |
wiring: the composition root |
CasosDeUso; crear_, obtener_, listar_, actualizar_, borrar_ |
use cases; create, get, list, update, delete |
ejecutar |
execute, the one method of a use case |
repositorio: guardar, buscar_por_id, buscar_todos |
repository: save, find by id, find all |
modelo, errores, valores, rutas, respuestas |
model, errors, value objects, routes, responses |
madres (MadreProducto): aleatorio, con_<campo>, construir |
object mothers: random, with a field, build |
pruebas, dobles (MockRepositorioProducto) |
tests (the feature that exposes test helpers), test doubles |
creado_en, actualizado_en, borrado, borrado_en |
created at, updated at, deleted, deleted at |
codigo, mensaje; limite, desplazamiento, elementos |
code, message; limit, offset, items |
deberia_…_cuando_…; Preparar, Actuar, Comprobar |
should … when …; Arrange, Act, Assert |
generado, migraciones, migrador |
generated, migrations, migrator |
Every generated name is in the glossary.
Three kinds of file
Section titled “Three kinds of file”What makes a Puerto project safe to regenerate is that each file has one owner.
Regenerated. Rewritten from puerto.toml by every command that changes the manifest. They
start with a GENERADO comment (AUTO-GENERATED in web/). Never edit them by hand: change
the manifest and run the generator.
| File | Rewritten by |
|---|---|
presentacion/cableado/, presentacion/api/src/generado/bootstrap.rs |
scaffold, caso-de-uso, presentacion, bootstrap |
contextos/<c>/dominio/src/eventos.rs |
scaffold, evento, bootstrap (events projects) |
presentacion/worker/src/generado/registro.rs |
consumidor, correo --tras, bootstrap (events projects) |
web/src/presentation/core/generated/* |
scaffold, web, bootstrap (web projects) |
docs/api/openapi.json, web/src/infrastructure/http/schema.d.ts |
make web/sync |
Written once, then yours. A generator writes them when it creates the piece, then never
touches them again. Models, use cases, repositories, routes, consumers, mail templates, screens:
almost everything. Edit them freely. puerto generar scaffold refuses to overwrite an entity
that already has files, and --forzar is the explicit way to discard your changes.
Patched. A few files get a line added and nothing else: aplicacion_<c>/src/lib.rs and
rutas.rs (a pub mod and an Api<Entidad> field per new use case), the root Cargo.toml and
presentacion/api/Cargo.toml (the crates of a new context), and puerto.toml itself.
puerto.toml
Section titled “puerto.toml”The manifest is the source of truth. After the scaffold above it reads:
[proyecto]nombre = "tienda"web = true
[[entidad]]nombre = "Producto"casos_de_uso = [ "crear_producto", "obtener_producto", "listar_productos", "actualizar_producto", "borrar_producto",]
[[entidad.campos]]nombre = "nombre"tipo = "String"
[[entidad.campos]]nombre = "precio"tipo = "i64"
[[entidad.campos]]nombre = "sku"tipo = "String"unico = truepuerto validar checks it against the code (a declared entity with no files, a consumer with no
handler, a route whose roles disagree with the manifest) and puerto listar prints what it
declares. The full schema is in the puerto.toml reference.
The runtime crates
Section titled “The runtime crates”Code that is the same in every project is a dependency, declared once in the root Cargo.toml
under [workspace.dependencies] and inherited by each crate:
[workspace.dependencies]puerto-web = "0.21"puerto-nucleo = "0.21"puerto-nucleo (repository error, paged lists, the ports) is the only one the domain may import:
it has no driver, no runtime and no I/O. puerto-web carries poem and stays in the rest_<c>
crates and api. puerto-sqlx carries sqlx and stays in the infra_<c> crates and the
binaries. The runtime crates reference lists them all.