Skip to content

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 # once
make web/dev # http://localhost:5173, /api proxied to :8080

The 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 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 DTO

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

  • 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).

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

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:

web/src/domain/cliente/messages.ts (excerpt)
"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.

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