API
Architecture notes for apps/api
apps/api is the public HTTP worker for UCD.js.
Role
- Serves the version, file, schema, well-known, and task endpoints.
- Publishes the
.well-knowndiscovery document used by@ucdjs/client. - Owns the API-facing boundary between external consumers and upstream Unicode data services.
Related Docs
Client
The client discovers and consumes the endpoints exposed by this app.
Store App
The hosted store app is a separate filesystem-style surface built on related data.
Worker Utils
Startup, CORS, rate limiting, and error handling are shared from worker-utils.
Data Flow
See how upstream Unicode data becomes API responses and downstream store inputs.
Mental Model
The app has one Hono/OpenAPI process with three concerns:
- register the HTTP surface
- apply shared worker policy
- expose both machine-readable OpenAPI and human-readable API docs
It is the canonical network entrypoint for most public consumers.
Request Flows
Worker startup
Normal API request
Discovery request
OpenAPI document request
Design Notes
- Route modules own endpoint behavior, while
worker.tsowns composition. - OpenAPI and Scalar are first-class parts of the app, not afterthoughts.
- Discovery lives beside the main API because the client depends on one canonical source of endpoint truth.
- Shared middleware keeps this worker aligned with the store worker where possible.
Testing Use
- route registration and request dispatch
.well-knowndiscovery payload correctness- OpenAPI server selection by environment
- error and rate-limit behavior via shared worker-utils integration