Architecture overview

Client and server

The browser client talks to the Hono server exclusively through ORPC — typed RPC-style procedures generated from packages/contracts. There are no ad-hoc REST handlers for product features: contracts define inputs/outputs, the server implements handlers, the client uses TanStack Query integrations.

OpenAPI and the Scalar browser UI are derived from the same router for partners who want HTTP-level docs (/openapi.json, /openapi).

Services layer

packages/services holds domain services (for example users, routes, items). Dependencies (db, redis, storage clients, …) are constructor-injected; service code does not read process.env. The app layer (apps/server) reads configuration and constructs services.

Data and rules

• Canonical schema — Drizzle table modules under packages/postgres/src/schema/.
• Narrative and table inventory — docs/data-model.md.
• Business rules and rule IDs — docs/rules.md.
• Mutation sequences for user actions — docs/workflows.md.

Frontend patterns

• File-based routes under apps/client/src/routes/ with TanStack Router.
• useSuspenseQuery for reads (with Suspense boundaries) and useMutation for writes, per team conventions.
• Forms use TanStack Store and Zod validation rather than uncontrolled HTML forms everywhere.

For more, see docs/architecture.md in the repository.