# Cake20 Architecture for Coding Agents

## Responsibility map

| Surface | Responsibility | Website source may depend on it |
| --- | --- | --- |
| Cake20.js | Public name for the View and Runtime website source model | Yes, through its source contract |
| `@cake20/view` | TSX screen language, compiler, and browser adapter | Through Runtime globals |
| Cake20 Gateway | Public static and dynamic website traffic | No direct website imports |
| Cake20 Core | Visual editing, MCP, review, deployment, child supervision | Through MCP only |
| `@cake20/runtime` | Website APIs, types, request runtime, auth, storage | Yes, via globals/contracts |
| `@cake20/provider` | Private AI, browser, mail, messaging, payment execution | No direct website imports |
| `@cake20/worker` | Shared DB, ZIP, and XLSX execution engine | No direct website imports |
| `@cake20/cli` | Local and remote workflow around Runtime | Commands only |
| Cake20 Hub | Account and central connection | No direct website access |
| Cake20 CDN | Public browser assets and versioned modules | Only documented public URLs |
| Package server | Versioned `@cake20/*` packages | CLI/Runtime installation |

Do not reproduce control-plane behavior inside a website. Website code should express
only that website's UI, domain logic, schema, tasks, routes, and public configuration.

## Execution targets

Design Preview:

- UI-only Vite process.
- Uses deterministic API mocks derived from server source and Preview data.
- Does not imply production readiness.

Debug review:

- Separate `build/debug` output, URL, and process used to verify source before
  publishing.
- Browser assets live in `build/debug/app`.
- Shares the website PostgreSQL database, Redis namespace, and `files` storage with
  the production release; legacy `test` data targets are aliases for the shared data.
- Disables scheduled background tasks and does not replace the running production
  release.

Production:

- Prepared release runs with the installed compatible Runtime.
- Browser assets live in `build/release/app`.
- Source, persistent files, database, and release output have separate lifecycles.
- Publishing builds the reviewed source into `build/release`; it does not authorize
  arbitrary data writes.

CLI local mode:

- `package.json` `data: "auto"` resolves to local data.
- CLI manages PGlite and starts or reuses the packaged Worker through local IPC.
- Users do not start Worker manually or configure a Worker port.

CLI server-data mode:

- CLI authenticates with Cake20 before using the private server Worker gateway.
- Website source and generated `db` types remain identical to local mode.
- Older servers may use the compatible database tunnel.

Cake20 Core mode:

- `package.json` `data: "auto"` resolves to server data.
- MCP controls source and operational actions for exactly one connected website.
- Core starts Provider and Worker independently of website startup, supervises their
  health, and shuts them down with the Core process.
- Gateway receives public website HTTP and WebSocket traffic. It serves static
  releases directly and routes dynamic releases independently of the Core UI.

## Source-to-runtime flow

1. Runtime reads and validates the `package.json` configuration.
2. Runtime validates source paths and cross-runtime imports.
3. UI source is compiled with Cake20 View, Cake20 UI, Tailwind, auto-imports, and
   Runtime globals.
4. Server handlers, hooks, routes, tasks, jobs, types, and utilities are prepared.
5. Database model files are combined into the generated Prisma schema when present.
6. A release records required runtime modules and task schedules.
7. Runtime starts the release with website-specific environment, storage, Worker,
   Redis, limits, and authenticated integration contracts.

Builds read the original workspace directly. The editor and MCP may continue saving
source, but changes made during a build require a new review or release build to
establish the verified result.

## Runtime, Provider, and Worker boundary

- Runtime is the website programming contract and keeps lightweight request-path work.
- Provider executes AI, Codex, Playwright-backed MCP browser checks, SMTP, Gmail,
  Telegram, and payment integrations outside Core. Core owns Provider authentication,
  recovery, and local IPC.
- Worker executes Prisma-compatible delegates, array transactions, DB metering, and
  ZIP and XLSX transformations outside website processes.
- Core authorizes and routes AI and MCP browser requests to Provider. Runtime receives
  only the authenticated mail, messaging, and payment contracts required by website
  source.
- Runtime keeps the public row-based `excel` API and storage paths while Worker owns
  XLSX parsing and serialization. Workbook editing is not supported.
- Provider and production Worker are private infrastructure with no public website API.
- Website source never imports Provider or Worker, and never depends on their IPC paths.
- There is no shared/public Provider selection. Login identifies the user's assigned
  Core, which supplies managed services without exposing Provider details.
- Interactive transactions and raw Prisma APIs require an explicit compatibility
  migration; do not silently rewrite them.

## Compatibility rule

- Treat installed TypeScript declarations as exact API truth.
- Use this site for stable platform semantics and constraints.
- Patch Runtime upgrades should preserve built website and template compatibility.
- A Runtime minor or major change can recommend rebuilding generated frontend assets,
  but old compatible artifacts remain usable until explicitly replaced.
- Never assume an undocumented internal service endpoint is public.

## Data boundaries

- `package.json`: public Cake20 settings, available as the global `project` object.
- Secrets: encrypted control-plane settings, server-only.
- `files`: persistent website file storage, accessed through `storage`.
- PostgreSQL: website relational data, accessed through generated `db` methods.
- Redis: Runtime session/cache infrastructure and approved website operations.
- Design Preview, debug review, and production use the same website database, Redis
  namespace, and persistent storage. Only code output and processes are separated.
- Release output: immutable generated code and UI assets, never persistent data.

## Security boundaries

- Browser code cannot receive Secrets or server credentials.
- Server code must re-check authorization even when the client route is protected.
- Database and Redis writes remain limited to the targets and scope in the current MCP
  user request; destructive operations must be explicitly included in that request.
- Website source cannot spawn processes or execute uploaded files in production.
- Use Cake20 MCP as the control plane; do not request direct server access.