The web frontend
puerto nuevo includes web/ unless you pass --sin-web: a React 19 app with daisyUI on
Tailwind, run by Bun. scaffold writes each entity’s screens (list, detail, and a form for
create and edit), so the first thing you scaffold already works in a browser.
make web/install # oncemake web/dev # http://localhost:5173, /api proxied to :8080The frontend keeps its own English vocabulary inside (ProductoRepository, list, get,
items), and speaks the API’s contract at the edge: the routes (/api/productos), the JSON
fields (elementos, limite, desplazamiento, clienteId) and the error codes
(producto.no_encontrado). The HTTP repository is the one place that translates between them.
The contract is the OpenAPI spec
Section titled “The contract is the OpenAPI spec”The backend’s routes are poem-openapi, so the API describes itself. A test in bootstrap.rs
exports the spec to docs/api/openapi.json, and the frontend’s wire types are generated from it
with openapi-typescript.
make web/sync # after a scaffold, and after touching a route or a DTOIt re-exports the spec, regenerates web/src/infrastructure/http/schema.d.ts, and formats
web/. Commit both. Until you run it, make test fails. That failure is the drift check: the
frontend cannot silently disagree with the API.
The same layers as the backend
Section titled “The same layers as the backend”Directoryweb/src/
Directorydomain/producto/
- model.ts Producto, ProductoDraft, enum unions
- errors.ts ProductoError: code is the API’s codigo
- messages.ts what each error code says, and to which field
- repository.ts ProductoRepository, the port
Directoryapplication/ empty until there is real logic
- …
Directoryinfrastructure/
- http/client.ts the openapi-fetch client
- http/schema.d.ts generated by make web/sync
- producto/producto-repository-http.ts DTO ↔ model, with tests
Directorypresentation/
Directorycore/generated/ generated: composition root and route table
- …
- core/routes.tsx yours: routes of your own
Directoryfeatures/producto/
Directorycontainers/ list, detail, form: data and state, with tests
- …
Directoryviews/ list, detail, form: markup only
- …
Directoryshared/ui/ layout, alerts, pagination, field errors
- …
- test-support/producto.ts ProductoMother and an in-memory fake
domain imports nothing, infrastructure imports domain, and only the composition root
imports infrastructure. dependency-cruiser checks it in make web/lint, with the type check
and Biome.
A list comes back from GET /api/productos?limite=20&desplazamiento=0 as
{ elementos, total, limite, desplazamiento }; producto-repository-http.ts turns it into the
screens’ Page (items, total, limit, offset), and each element into a Producto.
Containers call the repository port directly. A frontend CRUD use case would only delegate to
the API, so Puerto does not generate one. When real logic arrives, a rule or two repositories to
orchestrate, write application/<entity>/<action>.ts and point the container at it
(ADR-0013).
Fields become controls
Section titled “Fields become controls”| Field | TypeScript | Control |
|---|---|---|
String, Uuid |
string |
text input, required |
i64, f64 |
number |
number input (step=any for f64) |
bool |
boolean |
checkbox |
DateTime |
string (ISO 8601) |
datetime-local |
opt:T |
T | null |
as T, not required; empty → null |
vec:T |
T[] |
text, comma-separated |
map |
Record<string, string> |
textarea, key=value per line |
| enum VO | "Pendiente" | "Confirmado" | "Cancelado" |
<select> |
ref:Cliente |
string |
<select> of the first 100 clientes; a link on the detail |
Errors land next to their field
Section titled “Errors land next to their field”The frontend does not copy the domain’s validation: the server is the authority. A 422 comes
back with its codigo, and messages.ts, generated from the same list as errores.rs, turns
it into a sentence and a field:
"cliente.email_invalido": "Email is not valid","cliente.validacion.nombre_vacio": "Nombre is required",cliente.validacion.nombre_vacio marks the nombre input. cliente.duplicado goes to the
form’s alert. A code nobody wrote a message for shows the code itself. This file is also where
you translate.
Routes
Section titled “Routes”/productos, /productos/new, /productos/:id and /productos/:id/edit. The list’s page lives
in the URL (?page=2), so reload and back keep it. Add your own routes in
presentation/core/routes.tsx, never in core/generated/, which is rewritten.
bun test with happy-dom and Testing Library. Each container is tested against the in-memory
fake from test-support/, and each HTTP repository against a stubbed fetch. make test and
make lint include web/ whenever the directory exists.