Next steps before full Swagger docs and UX/UI

Do these in order so the API contract is stable and the front end has a clear target.

1. Auth and identity

Login / token endpoint
There is no in-app login. JWTs are assumed to come from an external IdP. Before UI:
- Either add POST /auth/login (or /auth/token) that accepts credentials, looks up users + user_roles, and returns a JWT with roles and (for vendor users) vendorId, or
- Document the exact JWT shape and how your IdP must set roles and vendorId so the UI can integrate.
User and role management (optional)
Schema has users, roles, user_roles, but no API. For a self-contained product, add CRUD for users and assignment of roles (and vendor_id for vendor users) so admins can onboard users and vendors without touching the DB directly.

Request validation
Add JSON Schema (or Zod) for request bodies and path/query params on all routes so invalid input returns 400 with a consistent error shape instead of 500 or undefined behavior.
Error response format
Standardize error payloads (e.g. { error: string, code?: string, details?: unknown }) and document them so Swagger and the UI can show the same errors.
Optional: list pagination
List endpoints (vendors, offers, assets, sites, etc.) return full arrays. Add limit/offset or page/pageSize and a total/cursor so the UI and docs can assume a stable list contract.

Wire permissions to routes
requirePermission exists but is not used on route handlers. For each route, add the appropriate requirePermission(...) (or equivalent) so that missing permission returns 403 with a clear message. This makes the API safe to document and use from the UI.

Document all paths
OpenAPI currently documents only health, vendors, offers, purchase-orders, and ingestion. Add the rest so Swagger matches the real API:
- Assets: GET/POST /assets, GET/PATCH/DELETE /assets/:id
- Sites: GET/POST /sites, GET/PATCH/DELETE /sites/:id, and nested (rooms, rows, racks, positions) if exposed
- Workflow: POST /workflow/offers/:id/risk-score, POST /workflow/purchase-orders/:id/submit, approve, reject, PATCH status
- Inspection: templates and runs
- Shipments: CRUD
- Asset components: CRUD
- Capacity: GET endpoints
- Integrations: UniFi, product-catalog, Proxmox, mappings
- Maintenances: CRUD
- Compliance profiles: CRUD
- UniFi controllers: CRUD
- Reports: BOM, support-risk
- Upload: POST /upload (multipart)
Request/response schemas
For each path, add requestBody and responses with schema (or $ref to components/schemas) so Swagger can show request/response bodies and generate client types.
Security per path
Mark which paths use BearerAuth, which use IngestionApiKey, and which are public (e.g. health).

env.example
Add INGESTION_API_KEY (and any OIDC/SSO vars if you add login) so deployers and the docs know what to set.
API base URL for web
Ensure the web app can be configured with the API base URL (e.g. env VITE_API_URL or similar) so Swagger and the UI both target the same backend.

Stabilize the contract
Add or expand API tests for critical paths (e.g. vendors, offers, purchase-orders, workflow, ingestion) so that when you add Swagger and the UI, changes to the API are caught by tests.
Optional: contract tests
Consider testing that responses match a minimal schema (e.g. required fields) so the OpenAPI spec and the implementation stay in sync.

API client
Add a minimal API client (fetch or axios) that sends the JWT (and x-org-id if required) so all UI calls go through one place and can be swapped for generated clients later.
Auth in the client
Implement login (or redirect to IdP), store the token, and attach it to every request; handle 401 (e.g. redirect to login or refresh).
Feature flags or minimal nav
Add a simple nav or list of areas (e.g. Vendors, Offers, Purchase orders, Assets, Sites) so the “full UX/UI” phase can fill in one screen at a time without redoing routing.

After the above:

Full Swagger
Serve the OpenAPI spec (e.g. from /api/openapi.json or /api/docs) and mount Swagger UI (or Redoc) so all operations and schemas are discoverable and try-it-now works.
Full UX/UI
Build out screens, forms, and flows using the stable API and client; keep OpenAPI and the UI in sync via the same base URL and error format.

#	Area	Action
1	Auth	Login/token endpoint or IdP contract; optional users/roles API
2	API contract	Request validation; consistent error format; optional pagination
3	RBAC	Use requirePermission on routes; return 403 where appropriate
4	OpenAPI	Document all paths, request/response schemas, security
5	Env	env.example (INGESTION_API_KEY, etc.); web API base URL
6	Tests	Broader API tests; optional contract/schema tests
7	Web baseline	API client, auth (token + 401), minimal nav/routes
8	Swagger + UI	Serve spec + Swagger UI; build out full screens