Architecture

API Map

Source: apps/api-worker/src/index.ts

Current API Worker

Source: apps/api-worker/src/index.ts

Method	Path	Status	Purpose
`GET`	`/`	Implemented	Returns `Hello Hono!`. Smoke test only.
`GET`	`/health`	Implemented	Returns `{ ok, service, time }` for worker health.
`GET`	`/openapi.json`	Implemented	Returns the first minimal OpenAPI document for local API exploration.
`GET`	`/docs`	Implemented	Serves Scalar API Reference for the local worker.

The current OpenAPI document is a small hand-authored skeleton. Zod/OpenAPI route registration is still planned.

Current Shell API Usage

Current facts:

No fetch(...) calls were found in apps/os-shell/src.
QueryClientProvider is wired in apps/os-shell/src/providers, but no useQuery calls are active yet.
openapi-fetch is installed but not used.
msw is installed as a dev dependency but no handlers are present.
/app-dev/scalar-api embeds the local Scalar docs at http://localhost:8787/docs.
Local fixtures live in packages/os-apps/src/shared/mock-data.ts and app-local arrays.

Planned First OS Shell APIs

Method	Path	Scenario	Notes
`GET`	`/api/apps`	App Store, registry inspection, community app discovery.	Should return manifest summaries, not executable UI.
`GET`	`/api/settings`	Load synced shell display/user preferences.	Mirrors localStorage-backed settings.
`PATCH`	`/api/settings`	Persist changed preferences.	Should accept partial updates.
`GET`	`/api/windows/layout`	Restore persisted window sizes/positions across sessions.	Current local size persistence is localStorage only.
`PUT`	`/api/windows/layout`	Save window layout hints.	Should be user/session scoped.
`GET`	`/api/user/session`	Profile, shell identity, signed-in state.	Needed before real user-aware OS surfaces.

API Ownership

Hono worker owns HTTP routes, validation, and edge runtime behavior.
Zod/OpenAPI owns request and response shape.
Scalar can expose API docs and exploration.
Shell apps should call typed clients through app-local API modules or shared API clients.
Zustand should not hold remote data responses.

Data Flow

Prox OS documentation reference.

OS Apps

Reusable app implementations now live primarily in packages/os-apps and are imported by apps/os-shell through the existing registry and renderer bridge.

On this page

Current API Worker Current Shell API Usage Planned First OS Shell APIs API Ownership