Developer reference

Project structure

Locate routes, client transport, domain services and documentation without crossing their responsibilities.

Follow a feature from route to client helper to server service. This map identifies the owning layers; it does not make the database a browser API.

Directory map

Directory	Responsibility
`src/app`	Public, authentication and private Next.js routes; `/api/v1` handlers.
`src/server/api`	Routing, authentication, scopes and structured HTTP errors.
`src/server/services`	User-scoped domain operations and financial read models.
`src/server/security`	Admission, session and request-boundary controls.
`src/server/imports`	Source parsing, preview and import lifecycle work.
`src/lib/api`	Browser request helpers and query cache.
`src/components`	Inquiry views, command dialogs and UI primitives.
`supabase/migrations`	Versioned database changes.
`documentation`	Independent Nextra app, public MDX and content checks.

Example: a money command

The Activity UI collects intent. A helper sends it to the API. The router authenticates and selects an operation. The service checks owned accounts and semantic links, then uses the balanced financial write boundary. The component presents the returned result and refreshes related queries.

A component should not create a second financial write path by calling a Supabase table directly.

Example: a public guide

Change MDX under documentation/content, its _meta.ts ordering when needed, and shared presentation under documentation/app or documentation/components. Preserve existing route URLs and run content checks after editing links.

Continue with frontend responsibilities or domain services.