Service boundaries
Which responsibility lives where, and how the pieces talk to each other.
Each responsibility has exactly one home. The boundaries below are what make the system safe to change.
Identity and sessions — apps/api
The API owns product identity, sessions, and API keys. The web console
forwards same-origin /api paths to the API and never implements a second
session engine. Browser traffic carries only cookies it legitimately owns;
the API verifies the principal on every operation.
Data integration — apps/api
Connection providers (Google Sheets/Drive, HTTPS JSON, PostgreSQL), dataset definitions and captures, and the bounded-read rules live in the API. The web presents them; it never queries databases directly.
Charts and artifacts — apps/api + contracts
Chart validation and artifact persistence run in the API against the shared contract packages. Public responses expose frozen approved metadata and media only; private storage stays private behind authenticated delivery.
Rendering — workers only
Heavy rendering (server-side SVG/PNG for charts, frames/MP4 for motion) runs exclusively in worker processes, isolated per workload so a long render cannot starve anything else. The API submits jobs and serves the resulting outputs. See the worker protocol.
Agent surfaces — MCP endpoints
MCP servers proxy to the same validated service operations — no parallel business logic. Remote endpoints authenticate with scoped credentials or OAuth and publish protected-resource metadata.
The web console — presentation only
apps/web contains route composition, domain state, and presentation. Its
rules:
- No database drivers, no storage SDKs, no second backend.
- Client state (Redux Toolkit Query) caches only safe metadata; secrets and passwords bypass Redux entirely.
- Protected layouts validate the session server-side before mounting user-keyed state.
Why these boundaries
- One authority per concern — no divergent implementations of identity, ownership, or revision semantics.
- Contracts over copies — every cross-service payload is a shared schema, validated at the boundary.
- Fail closed — redirects across service hops are rejected; authorization is verified per request, not assumed from layout.