ADR 0003: MSW + Hono + OpenAPI + Scalar

Status

Accepted as direction. Partially implemented.

Context

The OS shell needs data-backed apps, but the first milestone is still shell-first. Frontend apps should not block on database and auth work, while API shape should still become explicit and inspectable.

Current facts:

• apps/api-worker uses Hono and currently exposes /, /health, /openapi.json, and /docs.
• API worker dependencies include @hono/zod-openapi, zod, and @scalar/hono-api-reference.
• OS shell dev dependencies include msw, openapi-typescript, and openapi-fetch.
• No MSW handlers, generated OpenAPI types, Zod/OpenAPI route registry, or shell API client are wired yet.
• Scalar is available through the local API worker and can be embedded by /app-dev/scalar-api.

Decision

Use this route:

1. MSW for frontend development mocks.
2. Hono for Cloudflare Worker routes.
3. Zod/OpenAPI for typed request and response contracts.
4. Scalar for API exploration and future OS app embedding.
5. TanStack Query for server state in the shell.

Rationale

MSW lets Local Module Apps develop against realistic API shapes without waiting for production data.

Hono fits the Cloudflare Worker target and keeps API code small.

Zod/OpenAPI makes API contracts machine-readable for generated clients, docs, and AI agents.

Scalar starts as a developer iframe app and can become a richer API Explorer once the OpenAPI document is real.

Consequences

• Mock data should move from ad hoc component arrays toward MSW handlers when endpoints stabilize.
• Remote data must not be placed in Zustand.
• API route shape should be designed once and reused by docs, client generation, and tests.
• The shell can stay local-first while still converging on production API contracts.