techbro 0.0.0-stage → 0.5.0

package/templates/_default/database/migrations/sqlite/20261008120000_create_items.sql

@@ -0,0 +1,5 @@
+CREATE TABLE items (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);

package/templates/_default/docker-compose.prod.yml

@@ -0,0 +1,53 @@
+# Example only: replace credentials with injected secrets and use your registry images.
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      POSTGRES_DB: app
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d app"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  migrate:
+    build: ./database
+    environment:
+      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/app
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  backend:
+    build:
+      context: .
+      dockerfile: apps/backend/Dockerfile
+      args:
+        BUILD_SHA: ${BUILD_SHA:-dev}
+    environment:
+      APP_NAME: my-app
+      APP_PORT: "8080"
+      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/app
+      RUST_LOG: info
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-http://localhost}
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+    stop_grace_period: 30s
+    restart: unless-stopped
+
+  frontend:
+    build: ./apps/frontend
+    depends_on:
+      - backend
+    ports:
+      - "80:8080"
+    restart: unless-stopped
+
+volumes:
+  pgdata:

package/templates/_default/docker-compose.yml

@@ -0,0 +1,69 @@
+# Development stack. Production example: docker-compose.prod.yml
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d app"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  migrate:
+    build: ./database
+    environment:
+      DATABASE_URL: postgres://app:app@postgres:5432/app
+    volumes:
+      - ./database/migrations/postgres:/migrations:ro
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  backend:
+    build:
+      context: .
+      dockerfile: apps/backend/Dockerfile
+      target: dev
+    working_dir: /app
+    command: cargo watch -x 'run -p backend'
+    volumes:
+      - .:/app
+      - cargo-registry:/usr/local/cargo/registry
+      - backend-target:/app/target
+    environment:
+      APP_NAME: my-app
+      APP_PORT: "8080"
+      DATABASE_URL: postgres://app:app@postgres:5432/app
+      RUST_LOG: info
+      CORS_ALLOWED_ORIGINS: http://localhost:5173
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+    ports:
+      - "8080:8080"
+
+  frontend:
+    image: node:22-alpine
+    working_dir: /app
+    command: sh -c "npm ci && npm run dev -- --host"
+    environment:
+      VITE_API_BASE_URL: http://localhost:8080
+      WATCH_POLL: "1"
+    volumes:
+      - ./apps/frontend:/app
+      - /app/node_modules
+    ports:
+      - "5173:5173"
+
+volumes:
+  pgdata:
+  cargo-registry:
+  backend-target:

package/templates/_default/docs/api/README.md

@@ -0,0 +1,41 @@
+# API contract
+
+Machine-readable contract: [`openapi.yaml`](openapi.yaml). JSON uses `camelCase`; timestamps are
+UTC ISO 8601; ids are integers. Every response carries an `x-request-id` header.
+
+Every response also carries a separate `x-trace-id` correlation header, including errors
+and CORS preflights. Send a valid UUID to have it echoed; absent or invalid values are
+replaced with a generated UUID. `apiFetch` generates a fresh UUID per call unless the
+caller explicitly supplies the header (object, tuple array, or `Headers`). `ApiError.traceId`
+reads the response header; the error body's `requestId` contract is unchanged.
+These IDs are for correlation, never authentication. Configured CORS origins may send
+`x-trace-id` and read it on responses; origin/method restrictions remain unchanged.
+
+## Errors
+```json
+{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid input",
+  "details": [{ "field": "name", "message": "Must not be empty" }] },
+  "requestId": "3f1c..." }
+```
+Codes: `VALIDATION_ERROR` (400), `NOT_FOUND` (404), `SERVICE_UNAVAILABLE` (503), `DRAINING` (503), `INTERNAL_ERROR` (500).
+
+## GET /health
+`200` `{ "status": "ok", "version": "0.1.0", "build": "abc123" }` - liveness only. `build` is the
+`BUILD_SHA` set at image build time (`dev` if unset); use it to verify which deployment answers.
+
+## GET /ready
+`200` `{ "status": "ready" }`; `503` error shape when the database check fails (2s timeout), or code `DRAINING` after SIGTERM.
+
+## GET /api/v1/items?page=1&perPage=20
+`perPage` max 100.
+```json
+{ "items": [{ "id": 1, "name": "widget", "createdAt": "2026-10-08T12:00:00.000Z" }],
+  "pagination": { "page": 1, "perPage": 20, "total": 1 } }
+```
+
+## POST /api/v1/items
+Request `{ "name": "widget" }` (trimmed, 1–200 chars). `201` returns the item
+`{ "id": 1, "name": "widget", "createdAt": "..." }`. `400` on invalid input.
+
+## GET /api/v1/items/{id}
+`200` item object; `404` `NOT_FOUND`; `400` if `id` is not an integer.

package/templates/_default/docs/api/openapi.yaml

@@ -0,0 +1,152 @@
+openapi: 3.0.3
+info:
+  title: Project Template API
+  version: 1.0.0
+paths:
+  /health:
+    parameters:
+      - { $ref: "#/components/parameters/TraceId" }
+    get:
+      summary: Liveness
+      responses:
+        "200":
+          description: OK
+          headers:
+            x-trace-id: { $ref: "#/components/headers/TraceId" }
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string, example: ok }
+                  version: { type: string, example: 0.1.0 }
+                  build: { type: string, example: abc123 }
+  /ready:
+    parameters:
+      - { $ref: "#/components/parameters/TraceId" }
+    get:
+      summary: Readiness (database check)
+      responses:
+        "200":
+          description: Ready
+          headers:
+            x-trace-id: { $ref: "#/components/headers/TraceId" }
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string, example: ready }
+        "503": { $ref: "#/components/responses/Error" }
+  /api/v1/items:
+    parameters:
+      - { $ref: "#/components/parameters/TraceId" }
+    get:
+      summary: List items
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: perPage, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+      responses:
+        "200":
+          description: Page of items
+          headers:
+            x-trace-id: { $ref: "#/components/headers/TraceId" }
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items, pagination]
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: "#/components/schemas/Item" }
+                  pagination:
+                    type: object
+                    required: [page, perPage, total]
+                    properties:
+                      page: { type: integer }
+                      perPage: { type: integer }
+                      total: { type: integer }
+        "400": { $ref: "#/components/responses/Error" }
+    post:
+      summary: Create item
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name: { type: string, minLength: 1, maxLength: 200 }
+      responses:
+        "201":
+          description: Created
+          headers:
+            x-trace-id: { $ref: "#/components/headers/TraceId" }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Item" }
+        "400": { $ref: "#/components/responses/Error" }
+  /api/v1/items/{id}:
+    parameters:
+      - { $ref: "#/components/parameters/TraceId" }
+    get:
+      summary: Get item
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+      responses:
+        "200":
+          description: Item
+          headers:
+            x-trace-id: { $ref: "#/components/headers/TraceId" }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Item" }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+components:
+  parameters:
+    TraceId:
+      name: x-trace-id
+      in: header
+      required: false
+      description: Optional correlation UUID, never authentication. Invalid or absent values are replaced; valid values are echoed. Independent of x-request-id and error requestId.
+      schema: { type: string, format: uuid }
+  headers:
+    TraceId:
+      description: Correlation UUID, including on errors. Exposed to configured CORS origins.
+      schema: { type: string, format: uuid }
+  schemas:
+    Item:
+      type: object
+      required: [id, name, createdAt]
+      properties:
+        id: { type: integer, format: int64 }
+        name: { type: string }
+        createdAt: { type: string, format: date-time }
+  responses:
+    Error:
+      description: Error
+      headers:
+        x-trace-id: { $ref: "#/components/headers/TraceId" }
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [error, requestId]
+            properties:
+              error:
+                type: object
+                required: [code, message]
+                properties:
+                  code: { type: string }
+                  message: { type: string }
+                  details:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        field: { type: string }
+                        message: { type: string }
+              requestId: { type: string }

package/templates/_default/docs/decisions/0001-adopt-engineering-convention.md

@@ -0,0 +1,13 @@
+# 0001. Adopt the Engineering Convention
+
+Status: Accepted (2026-10-08)
+
+## Context
+New projects need a consistent stack, structure, and checks.
+
+## Decision
+Follow the Engineering Convention in the root `README.md`: React + Vite frontend, Rust/Axum/SQLx
+backend, SQLite locally, PostgreSQL in shared environments, independent SQL migrations.
+
+## Consequences
+Deviations require an approved exception recorded in this directory.

package/templates/_default/docs/decisions/README.md

@@ -0,0 +1,6 @@
+# Decision records
+
+Record significant decisions and approved exceptions to the convention as ADRs.
+
+File name: `NNNN-short-title.md`. Sections: Status, Context, Decision, Consequences.
+Statuses: Proposed, Accepted, Superseded by NNNN. Do not rewrite accepted records; supersede them.

package/templates/_default/docs/deployment.md

@@ -0,0 +1,46 @@
+# Deployment: blue/green zero-downtime
+
+Hosting specifics (load balancer, orchestrator, cloud) are outside the convention. This page
+describes what the code guarantees and a generic cut-over procedure.
+
+## What the code guarantees
+
+- Stateless process: no local files or in-memory session state. All state lives in the database.
+- Configuration comes only from environment variables (see `.env.example`).
+- `GET /health` is liveness. It never touches the database and returns
+  `{"status":"ok","version":"...","build":"..."}`.
+- `GET /ready` is readiness. It runs `SELECT 1` (2s timeout) and returns 503 when the database
+  is unreachable or when the process is draining (error code `DRAINING`).
+- `build` is the `BUILD_SHA` build arg (`dev` if unset). Compare it across colors to confirm
+  which release serves traffic.
+- SQLite is for local development only. Do not run several instances against a SQLite file.
+
+## SIGTERM drain sequence
+
+1. SIGTERM (or Ctrl-C) arrives. Log: `shutdown signal received, draining`.
+2. The draining flag is set; `/ready` returns 503 `DRAINING`. Load balancers stop routing.
+3. The process waits `SHUTDOWN_DRAIN_SECONDS` (default 5) with the listener still open.
+4. The listener stops accepting; in-flight requests finish.
+5. The pool closes. Log: `shutdown complete`. Exit code 0.
+
+Timing: total stop time = drain seconds + longest in-flight request. Keep
+`stop_grace_period` (30s in `docker-compose.prod.yml`) larger than that sum, and set the drain
+seconds at least as long as your load balancer's probe interval times its failure threshold.
+
+## Migrations
+
+Migrations run separately, before traffic switches (`migrate` service or `scripts/db-migrate`).
+Both colors share one database during cut-over, so every migration must be backward
+compatible with the old release: expand (add), deploy, then contract (remove) in a later release.
+See `database/README.md`. Never edit an applied migration.
+
+## Cut-over steps
+
+1. Run migrations against the target database (expand-only changes).
+2. Start green (new build, `BUILD_SHA=<commit>`) alongside blue.
+3. Wait until green `/ready` returns 200, and `/health` shows the expected `build`.
+4. Switch traffic from blue to green at the load balancer.
+5. Watch logs and error rates for green.
+6. Send SIGTERM to blue and let it drain and exit.
+7. Rollback: switch traffic back to blue while it is still running (before step 6), or start
+   the previous build again. Database changes stay backward compatible, so no schema rollback.

package/templates/_default/docs/docker.md

@@ -0,0 +1,63 @@
+# Docker
+
+## Development stack
+
+```bash
+npm run docker:dev     # docker compose up --build
+npm run docker:down
+```
+
+Services: `postgres` (17, user/password/db `app`, port 5432), `migrate` (one-shot sqlx CLI),
+`backend` (http://localhost:8080), `frontend` (Vite dev server, http://localhost:5173, source
+bind-mounted). Ports 8080 and 5173 must be free. The browser calls the backend directly via
+`VITE_API_BASE_URL=http://localhost:8080`; CORS allows `http://localhost:5173`.
+
+## Hot reload
+
+- Backend: the `dev` stage of `apps/backend/Dockerfile` adds cargo-watch. The workspace is
+  bind-mounted at `/app`; `cargo-registry` and `backend-target` named volumes keep builds fast.
+  Saving a Rust file rebuilds and restarts the server (first start compiles everything).
+- Frontend: Vite HMR on the bind mount. `WATCH_POLL=1` makes `vite.config.js` use polling,
+  which is needed for bind mounts on macOS.
+
+## Production images
+
+```bash
+docker build -f apps/backend/Dockerfile -t backend .            # context: template root
+docker build -t frontend apps/frontend                           # context: apps/frontend
+docker build -t migrate database                                 # context: database
+# or: npm run docker:build  (backend and frontend)
+```
+
+- Backend: multi-stage Rust build with a cached dependency layer, runs as non-root user `app`
+  on port 8080. The base image tag must match `rust-toolchain.toml`.
+- Frontend: Vite build served by `nginx-unprivileged` on port 8080. Build args:
+  `VITE_API_BASE_URL` (default empty, same origin) and `VITE_APP_NAME`.
+- Migrate: sqlx CLI with `database/migrations/postgres` baked in.
+
+`docker-compose.prod.yml` is an example that runs these images with PostgreSQL. It needs
+`POSTGRES_PASSWORD` and optionally `CORS_ALLOWED_ORIGINS`; the frontend is published on port 80
+and the backend is not published.
+
+## Environment variables
+
+Backend: `APP_NAME`, `APP_PORT`, `DATABASE_URL`, `RUST_LOG`, `CORS_ALLOWED_ORIGINS`.
+Migrate: `DATABASE_URL`.
+
+## SPA fallback and proxying
+
+`apps/frontend/nginx.conf` serves `index.html` for unknown paths (`try_files ... /index.html`),
+so client-side routes such as `/items` work on reload. `/api/`, `/health` and `/ready` are
+proxied to `http://backend:8080`, so the production frontend can use same-origin API calls.
+
+## Migrations
+
+The app never migrates. The `migrate` service runs `sqlx database create && sqlx migrate run`
+and the backend waits for it to complete successfully. To run migrations manually use
+`scripts/db-migrate postgres|sqlite`.
+
+## Switching DATABASE_URL
+
+Change `DATABASE_URL` in the compose file (for `migrate` and `backend`) or `.env`, for example
+`postgres://user:password@host:5432/dbname`. The migrate image only carries PostgreSQL
+migrations; SQLite is for local development outside Docker.

package/templates/_default/docs/getting-started.md

@@ -0,0 +1,214 @@
+# Getting started
+
+A walkthrough for a new developer right after cloning. The conventions behind it are in `README.md`.
+
+## 1. Setup
+
+```bash
+scripts/setup                  # creates .env, npm ci, cargo fetch
+cargo install sqlx-cli --no-default-features --features sqlite,postgres   # once per machine
+scripts/db-migrate sqlite      # creates local.db and applies database/migrations/sqlite
+cargo install cargo-watch      # once per machine, backend hot reload
+cargo watch -x 'run -p backend'      # http://localhost:8080, restarts on source changes
+npm --prefix apps/frontend run dev   # http://localhost:5173, Vite HMR
+```
+
+Hot reload: Vite updates the frontend in the browser without a refresh. `cargo watch` rebuilds
+and restarts the backend on every save (`cargo run -p backend` works too, without reload). Inside
+Docker, `docker compose up` does the same for both apps; see `docs/docker.md`.
+
+Open http://localhost:5173. The Welcome page shows backend status (`/health` and `/ready`), the
+steps of the sample feature, and a link to the Items page (`/items`) with a form to add an item.
+The Vite dev server proxies `/api`, `/health` and `/ready` to the backend on port 8080
+(`apps/frontend/vite.config.js`). The curl examples in section 4 do the same from a terminal.
+
+Run all checks with `scripts/check`. Optional: `scripts/install-hooks` runs them before every push.
+
+## 2. The sample feature, end to end
+
+`items` goes through every layer. Excerpts are from the real files.
+
+### Migrations (`database/migrations/<engine>/20261008120000_create_items.sql`)
+
+```sql
+-- postgres
+CREATE TABLE items (
+    id BIGSERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- sqlite
+CREATE TABLE items (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+```
+
+Same logical schema, different types: SQLite stores the timestamp as ISO 8601 text.
+
+### Model (`apps/backend/src/models/item.rs`)
+
+```rust
+pub fn validate_name(raw: &str) -> Result<String, AppError> {
+    let name = raw.trim();
+    if name.is_empty() {
+        return Err(AppError::validation("name", "Must not be empty"));
+    }
+    ...
+}
+
+// CAST keeps created_at decodable as text on both SQLite and PostgreSQL.
+pub async fn find(pool: &AnyPool, id: i64) -> Result<Option<Item>, sqlx::Error> {
+    sqlx::query_as::<_, Item>(concat!("SELECT ", columns!(), " FROM items WHERE id = $1"))
+        .bind(id)
+        .fetch_optional(pool)
+        .await
+}
+```
+
+SQL is explicit and parameterized. sqlx 0.9 requires static SQL strings, hence `concat!`.
+
+### Controller (`apps/backend/src/controllers/items.rs`)
+
+```rust
+pub async fn get(
+    State(state): State<AppState>,
+    id: Result<Path<i64>, PathRejection>,
+) -> Result<Json<Item>, AppError> {
+    let Path(id) = id.map_err(|_| AppError::validation("id", "Must be an integer"))?;
+    item::find(&state.pool, id)
+        .await?
+        .map(Json)
+        .ok_or(AppError::NotFound)
+}
+```
+
+Handlers stay thin: parse input, call the model, map to a response.
+
+### Routes (`apps/backend/src/routes.rs`)
+
+```rust
+.route("/health", get(health::health))
+.route("/ready", get(health::ready))
+.route("/api/v1/items", get(items::list).post(items::create))
+.route("/api/v1/items/{id}", get(items::get))
+```
+
+### Errors (`apps/backend/src/error.rs`)
+
+`AppError` implements `IntoResponse` and produces the convention's shape:
+
+```json
+{ "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "requestId": "..." }
+```
+
+Database and internal errors are logged with `tracing::error!` and returned as a generic
+`INTERNAL_ERROR`; internals are never exposed.
+
+### Frontend API client (`apps/frontend/src/api/items.js`)
+
+```js
+export function listItems({ page = 1, perPage = 20 } = {}) {
+  const query = new URLSearchParams({ page: String(page), perPage: String(perPage) });
+  return apiFetch(`/api/v1/items?${query}`);
+}
+```
+
+### Hook (`apps/frontend/src/hooks/useItems.js`)
+
+```js
+const create = useCallback(async (name) => {
+  const check = validateItemName(name);
+  if (!check.ok) {
+    setError(check.message);
+    return false;
+  }
+  const created = await createItem({ name: name.trim() });
+  setItems((current) => [created, ...current]);
+  return true;
+}, []);
+```
+
+Client validation (`src/models/items.js`) is for usability only; the backend is authoritative.
+
+### Page (`apps/frontend/src/pages/ItemsPage.jsx`)
+
+```jsx
+export default function ItemsPage() {
+  const { items, loading, error, create } = useItems();
+  ...
+  {loading ? <p className="text-sm">Loading...</p> : <ItemList items={items} />}
+```
+
+## 3. Add your own feature
+
+Schema and API contract changes need tech-team approval before implementation (convention
+sections 8, 9 and 15).
+
+1. Migration: add `<YYYYMMDDHHMMSS>_<description>.sql` to both `database/migrations/postgres/`
+   and `database/migrations/sqlite/`. Never edit a migration already applied to a shared
+   environment; add a corrective one.
+2. Model: `apps/backend/src/models/<name>.rs` (types, validation, SQL), register in `models/mod.rs`.
+3. View: response types in `apps/backend/src/views/` if the list/response shape differs.
+4. Controller: `apps/backend/src/controllers/<name>.rs`, register in `controllers/mod.rs`.
+5. Route: add to `router` in `apps/backend/src/routes.rs`.
+6. API docs: update `docs/api/README.md` and `docs/api/openapi.yaml`.
+7. Frontend: `src/api/<name>.js`, `src/models/<name>.js`, `src/hooks/use<Name>.js`,
+   `src/pages/<Name>Page.jsx`; wire the page in `App.jsx`. Add `/something` to the Vite proxy if
+   it is not under `/api`.
+8. Tests: model unit tests, an integration test in `apps/backend/tests/api.rs`, and Vitest tests.
+   Verify Postgres-bound SQL against a real PostgreSQL.
+9. Run `scripts/check`.
+
+## 4. Curl examples
+
+```bash
+curl -i localhost:8080/health
+# 200 {"status":"ok","version":"0.1.0","build":"dev"}
+
+curl -i localhost:8080/ready
+# 200 {"status":"ready"}   (503 error shape if the database check fails)
+
+curl -i -X POST localhost:8080/api/v1/items \
+  -H 'content-type: application/json' -d '{"name":"widget"}'
+# 201 {"id":1,"name":"widget","createdAt":"2026-10-08T12:00:00.000Z"}
+
+curl 'localhost:8080/api/v1/items?page=1&perPage=20'
+# 200 {"items":[{"id":1,"name":"widget","createdAt":"..."}],
+#      "pagination":{"page":1,"perPage":20,"total":1}}
+
+curl localhost:8080/api/v1/items/1
+# 200 {"id":1,"name":"widget","createdAt":"..."}
+
+curl -i -X POST localhost:8080/api/v1/items \
+  -H 'content-type: application/json' -d '{"name":"  "}'
+# 400 {"error":{"code":"VALIDATION_ERROR","message":"Invalid input",
+#      "details":[{"field":"name","message":"Must not be empty"}]},"requestId":"..."}
+```
+
+Every response includes an `x-request-id` header; send your own to propagate one.
+It also includes a separate `x-trace-id`: `apiFetch` generates a fresh UUID for each call
+unless explicitly supplied. The backend echoes valid UUIDs or replaces absent/invalid
+values, including on errors. JSON request spans contain both `request_id` and `trace_id`;
+search logs by the response trace header (or `ApiError.traceId`) without logging payloads.
+Neither ID is authentication; error JSON still uses only the existing `requestId` field.
+
+```bash
+curl -i localhost:8080/health -H 'x-trace-id: 5d632031-f1ac-4a8f-8837-b4b2bef63596'
+```
+
+## 5. Removing the sample
+
+Delete:
+
+- `database/migrations/*/20261008120000_create_items.sql` (only before it is applied anywhere
+  shared; otherwise add a drop migration)
+- `apps/backend/src/models/item.rs`, `controllers/items.rs`, `views/items.rs` and their `mod.rs`
+  lines; the `/api/v1/items` routes in `routes.rs`
+- the items tests in `apps/backend/tests/api.rs` (keep the health/ready test; `app()` applies
+  the migration, so point it at your own)
+- `apps/frontend/src/api/items.js`, `hooks/useItems.js`, `models/items.js` (+ test),
+  `pages/ItemsPage.jsx`, `components/ItemList.jsx` (+ test); update `App.jsx`
+- the items sections of `docs/api/README.md` and `docs/api/openapi.yaml`