Skip to content

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.

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.

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.

The manifest is the source of truth. After the scaffold above it reads:

puerto.toml
[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 = true

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

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:

Cargo.toml
[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.