Cake20 Service Architecture

Deployment layout at a glance

Cake20 separates central services, public traffic and management on each server, and per-website execution. Gateway handles HTTP and WebSocket traffic, Core supervises Provider and Worker, and Runtime runs each dynamic website independently.

• One central set: Hub, Docs, AI context, CDN, and Package
• Each server: Cake20 Gateway and Cake20 Core with private Provider and Worker children
• Site traffic: Gateway serves static releases directly and forwards dynamic sites to Runtime
• Installed packages: @cake20/runtime, @cake20/provider, @cake20/worker, and @cake20/cli
• Per website: source, release, PostgreSQL DB, and files; only dynamic sites need a process

How components connect

Hub: Central control plane for multiple Core servers

Hub is not a website Runtime. It manages accounts and multiple Cake20 Core servers, locates the Core that owns a site, and routes central login and management requests to the correct server.

• Track Core registration, health, capacity, location, version, and setting differences.
• Coordinate group/scheduled deployments, job locks, retries, aborts and full rollbacks.
• Manage source and data backups, recovery checks, and Hub's own backups.
• Manage accounts, subscriptions, audits, secure sessions, notifications, and metric history.
• Move members and sites between Core servers with pre- and post-move integrity checks.
• Each Core remains responsible for its website source, databases, and processes.

Gateway: The public traffic entry point

Cake20 Gateway maps each server's web-* address and custom domains to websites. Ordinary site requests bypass Core and go directly to a static release or a running Runtime process.

• Gateway is an independent Bun service deployed beside Core, not an @cake20 package.
• Route HTTP and WebSocket traffic with the same domain rules.
• Serve static release files without a site process and proxy dynamic sites to Runtime.
• Persist authenticated route snapshots from Core and refresh them through immediate notifications and periodic sync.
• Ask Core to wake a sleeping site, while leaving explicitly stopped sites offline.
• Batch active-user and visit counts back to Core.
• Keep cached routes and traffic to running sites available while Core restarts.

Core: Per-server website control plane

Cake20 Core manages the browser editor, Preview, AI Chat, review, deployment, and website lifecycle on one server. Gateway handles ordinary site traffic, letting Core focus on management and execution control.

• Manage website creation/deletion, templates, domain settings, logs, and execution status.
• Build domain-to-target route snapshots and send them to authenticated Gateway instances.
• Keep shared DB, Redis, and files data while building, starting, and recovering separate debug and release code.
• Start Provider and Worker with Core and supervise their health, restart, and shutdown.
• A site start never replaces the shared Worker. Only the Core keeper replaces a confirmed unhealthy Worker and restarts connected sites in sequence.
• Continue to serve editor-only Preview and template paths inside Core.
• Core remains responsible for local websites if Hub is temporarily unavailable.
• Call @cake20/runtime instead of copying Runtime implementation into Core.

Core restarts and availability boundaries

Separating public traffic into Gateway limits website disruption when Core is restarted or replaced.

• Running static and dynamic sites and established WebSocket connections survive a Core restart.
• The manager, editor, AI, build, deployment, and new start or wake actions wait for Core to return.
• A sleeping site cannot wake without Core, but already running Runtime processes are unaffected.
• Gateway is the server's shared traffic entry point and requires health monitoring and automatic restart.

Provider: External service process managed by Core

@cake20/provider is a private package that executes AI, Codex, Playwright-backed MCP browser checks, mail, Gmail, Telegram, and payments outside Core. Core owns its lifecycle and authentication; users do not configure it.

• Core and Provider communicate through local IPC rather than a public service port.
• Core authorizes MCP browser tools and deployment audits; Provider runs the browser.
• The administration UI has no shared Provider concept or Provider address setting.
• cake login finds the assigned Core and stores its CLI connection automatically.
• CLI Runtime receives mail, Gmail, Telegram, and payment connections through authenticated Core APIs.
• Integration settings and credentials stay on the Core server and never enter source or browser code.

Worker: Shared server and local execution engine

@cake20/worker runs database and file transformation work outside website Runtime processes. Core starts Worker independently of website startup, and each website registers the DB connection it needs through local IPC.

• Production Worker has no public domain or service port and accepts local IPC only.
• It handles Prisma-compatible DB work, array transactions, DB size, ZIP, and XLSX transforms.
• Runtime retains single-sheet row data and storage paths while Worker handles XLSX.
• Website source keeps using db, zip, and excel APIs and never imports Worker.
• Local CLI starts the packaged Worker automatically or reuses an existing local Worker.
• CLI server mode enters through the Core authentication gateway.
• When Worker is replaced, Core reconnects affected websites and recovers their processes.
• Interactive transactions and raw Prisma APIs remain explicit migration cases.

Runtime: Independently installed website engine

@cake20/runtime is an independently versioned engine installed from the Package server, not a copy embedded in Core. Core and CLI share its source checks, UI build, API, PostgreSQL, storage, and server execution features.

• Local mode uses PGlite under data/postgres and an automatic CLI Worker.
• Server mode uses private Worker PostgreSQL execution with one DB per website.
• dev runs UI HMR, API, DB, and seed together; design and preview run only the UI.
• build creates a release; start runs the prepared production release.
• Installed packages and production releases use compiled JavaScript and built UI assets.
• A Runtime version difference is reported, while compatible releases continue to run.
• @cake20/db and @cake20/view are Runtime dependencies and are not duplicated by websites.

CLI: Use the Runtime without Cake20 Core

@cake20/cli uses a compatible Runtime version range and provides the cake command. You can create, validate, develop, back up, build, and run a project locally without registering the folder or Cake20 ZIP in Core.

• Prepare projects and development tools with cake init, prepare, and doctor.
• Develop and run folders or ZIP archives with cake dev, design, preview, build, start, and run.
• Inspect and move local or server PostgreSQL data with cake db version, export, and import.
• cake login connects the assigned Core; cake deploy reviews and publishes the site.
• Standalone Runtime use does not require a Core or Hub connection.

CDN: Browser common asset distribution

https://cdn.cake20.com serves versioned browser ES modules, CSS, fonts, and static assets shared by Cake20 websites.

• Provide compatible CodeMirror, Prisma language, Tiptap Rich Editor, DataTables, and Responsive modules.
• Self-host WOFF2 fonts and CSS such as IBM Plex Sans and Lilex.
• Keep published version URLs immutable and publish upgrades at new paths.
• Do not import CDN modules from server APIs, tasks, or jobs.
• Never place Secrets, credentials, or user-private data on the public CDN.

Package: Cake20 Package Registry

https://package.cake20.com distributes @cake20 scoped packages. Package metadata and installation are readable, while publishing is restricted to operator accounts.

• Publish @cake20/runtime, @cake20/provider, @cake20/worker, and @cake20/cli independently.
• @cake20/db provides the standard PostgreSQL, Prisma adapter, and PGlite stack.
• @cake20/view provides the standard Cake20 View, Router, Cake20 UI, and build-tool stack.
• @cake20/exceljs and @cake20/nitropack are managed packages for long-term preservation and compatibility.
• Route only the @cake20 scope to Package; use the default npm registry for public packages.

Program deployment and persistent-data boundary

Service programs deploy as replaceable releases. User source, databases, package data, and backups live in separate -files storage, so deploying a program does not delete or overwrite persistent data.

• Core website source·Release·files: cake20-core-files
• Hub distribution assets/backup: cake20-hub-files
• CDN public assets: cake20-cdn-public
• Package tarball·metadata·authentication file: cake20-package-files
• CLI persistent local DB and upload: project's data/postgres and files
• Run CLI --memory: Use OS temporary folder and remove on exit
• A website's shared DB is isolated from the Manager DB, and program releases do not overwrite shared website data.