Skip to content

The puerto.toml manifest

puerto.toml is the source of truth of a project. The generators write it; cableado, bootstrap.rs, eventos.rs, registro.rs and the frontend’s generated files are derived from it; and puerto validar checks the code against it. You can edit it by hand; run puerto generar bootstrap and puerto validar afterwards.

A complete example, from a project with a database, events, auth and a mail:

puerto.toml
[proyecto]
nombre = "tienda"
db = true
web = true
eventos = "db"
auth = "local"
[[entidad]]
nombre = "Cliente"
casos_de_uso = [
"crear_cliente",
"obtener_cliente",
"listar_clientes",
"actualizar_cliente",
"borrar_cliente",
]
db = true
[[entidad.campos]]
nombre = "email"
tipo = "String"
objeto_valor = "Email"
[[entidad.campos]]
nombre = "nombre"
tipo = "String"
[[entidad]]
nombre = "Producto"
casos_de_uso = [
"crear_producto",
"obtener_producto",
"listar_productos",
"actualizar_producto",
"borrar_producto",
"publicar_producto",
]
db = true
publicos = [
"listar_productos",
"obtener_producto",
]
eventos = ["producto_publicado"]
[entidad.roles]
borrar_producto = ["admin"]
[[entidad.campos]]
nombre = "nombre"
tipo = "String"
[[entidad.campos]]
nombre = "sku"
tipo = "String"
unico = true
[[entidad]]
nombre = "Pedido"
casos_de_uso = [
"crear_pedido",
"obtener_pedido",
"listar_pedidos",
"actualizar_pedido",
"borrar_pedido",
]
db = true
[[entidad.campos]]
nombre = "cliente_id"
tipo = "Uuid"
referencia = "Cliente"
[[entidad.campos]]
nombre = "estado"
tipo = "String"
objeto_valor = "Estado"
clase_objeto_valor = "enum"
variantes = [
"Pendiente",
"Confirmado",
"Cancelado",
]
[[objeto_valor]]
nombre = "Email"
tipo = "String"
[[consumidor]]
nombre = "avisar_producto_nuevo"
eventos = [
"producto_creado",
"producto_publicado",
]
[[correo]]
nombre = "bienvenida"
tras = ["cliente_creado"]
Key Type Set by Meaning
nombre string nuevo --nombre The project’s name: crates, database, topics
db bool nuevo --db Postgres through SQLx. Absent means false
web bool nuevo (default), --sin-web The React frontend in web/
eventos "db" | "kafka" nuevo --eventos Domain events and their transport. Needs db
auth "oidc" | "local" nuevo --auth Authentication mode. local needs db
Key Type Set by Meaning
nombre string scaffold, dominio PascalCase. Each entity is a context, contextos/<snake>/
casos_de_uso string[] scaffold, caso-de-uso Every use case cableado builds. The five CRUD ones make it a CRUD entity, with routes and screens
db bool scaffold in a db project Postgres repository instead of in memory
publicos string[] scaffold --publico Auth projects: use cases whose routes need no token
roles table scaffold --rol Auth projects: caso_de_uso = ["rol", …]; the caller needs all of them
eventos string[] generar evento Custom event types, beyond _creado, _actualizado, _borrado
Key Type Meaning
nombre string snake_case
tipo string String, i64, f64, bool, Uuid, DateTime<Utc>, HashMap<String, String>, or Option<…> / Vec<…> of them. See Field types
unico bool A partial unique index, and 409 on a duplicate
objeto_valor string The value object wrapping it, local or shared
clase_objeto_valor "enum" An enum value object; tipo is then String
variantes string[] Its PascalCase variants
referencia string Another CRUD entity whose id this field holds; tipo is then Uuid or Option<Uuid>. A foreign key in db projects. See References

Shared value objects, declared by generar objeto-valor: nombre (PascalCase) and tipo (its inner primitive). They live in the nucleo crate. A field that names one without a type uses this one.

Events projects. Written by generar consumidor: nombre (snake_case, the handler’s file and its consumer group) and eventos (the event types it handles). A consumer whose file is missing makes validar fail and generar bootstrap refuse.

Written by generar correo: nombre, and tras when the worker sends it after events.

  • Names: PascalCase entities, snake_case fields and use cases, no Rust keywords, no SQL reserved words in db projects, no names the generated code or another context already uses.
  • Types: every field type is one Puerto generates, and every shared value object exists.
  • Consistency: eventos and auth = "local" need db; every declared entity, consumer and mail has its files; in web projects, every CRUD entity has its screens; in auth projects, each route’s BearerAuth and #[requiere_rol] match publicos and roles; every referencia names another declared CRUD entity, is a Uuid or Option<Uuid>, and closes no cycle between contexts.
  • The runtime: a warning for each puerto-* crate on another minor than the CLI.