rust-template/docs/architecture.md

Architecture

browser  →  Vite :5173  --proxy /api,/health-->  Axum :8080  →  PostgreSQL
                 ↑                                    │
                 └── generated client  ←  openapi.json ← utoipa-axum router

Why this shape

One workspace. The server owns HTTP and persistence. The web app owns interaction. The contract package is generated, never edited.

Config is shared on purpose. config/default.toml is read by both AppConfig::load and apps/web/vite.config.ts, so the reverse proxy target cannot drift from the bind address.

Request path

1. Vite binds 127.0.0.1 (not localhost) so the browser never hits IPv6 ::1.
2. Browser calls /api/v1/items.
3. Vite proxies to http://127.0.0.1:8080.
4. SetRequestIdLayer assigns X-Request-Id.
5. request_logging records method, path, status, latency, request id.
6. Handler returns Result<T, ApiError>. Errors become a single JSON envelope.

Adding an endpoint

1. DTO in apps/server/src/models.
2. Handler in apps/server/src/handlers with #[utoipa::path].
3. Register it with .routes(routes!(your_handler)) in routes/mod.rs.
4. just generate-api.
5. Call the new function from apps/web/src/api/generated.ts.