> drobek docs: Architecture — https://www.drobek.app/docs/architecture (drobek v0.5.2). For agents: https://drobek.app/llms.txt # drobek — architecture drobek is a cloud workspace for web apps that people build with their own AI agent. The agent connects over MCP and works **directly in drobek**: it writes files, drobek compiles them in-process with esbuild and returns the compile result in the same response, every write becomes an immutable version with an instant preview host, and a version goes live when the user asks for it. An app's backend is never code the agent writes: it is a set of **platform modules** (TypeScript, installed by the operator) that the app calls through a small browser SDK. The dashboard is for what does not belong in a chat with an LLM: secrets, confirmations, domains, data, users, logs. This document is the map of how that works. The neighbours: [`SELF-HOSTING.md`](https://www.drobek.app/docs/self-hosting) (running it), [`MODULES.md`](https://www.drobek.app/docs/modules) (the module contract and the built-in modules), [`AGENT.md`](https://www.drobek.app/docs/agent) (the agent-facing contract), [`SECURITY.md`](https://www.drobek.app/docs/security) (the threat model), [`LICENSING.md`](https://www.drobek.app/docs/licensing) (AGPL and the SaaS boundary). ## 1. One process, one image ``` dashboard host (PUBLIC_APP_URL) apps origin (*.APPS_DOMAIN + custom domains) ──────────────────────────────── ───────────────────────────────────────────── MCP client ──► /mcp (Streamable HTTP, Bearer) . published version browser ──► / (React Router 7 SSR dashboard) --preview. newest version that compiled MCP client ──► /oauth/*, /.well-known/* (OAuth 2.1 AS) --v. exactly version N browser ──► /api/* (dashboard JSON API) shop.example.org (verified) published version /__drobek/sdk.js, /__drobek/v1//… ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ caddy: TLS for the dashboard host, *.APPS_DOMAIN and verified custom domains ──► drobek:3000 │ ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ drobek — one Node 22 process (apps/server, Express) │ │ 1. apps-host middleware (@drobek/serving): an app host is answered here and never reaches the dashboard │ │ 2. origin check (@drobek/auth): mutating dashboard requests from app / null / foreign origins → 403 │ │ 3. /health, /version, /api/internal/tls/ask (internal address only) │ │ 4. /mcp: @drobek/oauth resource server (Bearer → user, scopes, audience) + @drobek/mcp tool bodies │ │ 5. everything else: React Router (@drobek/dashboard routes, OAuth AS routes, /llms.txt, /report …) │ │ in-process jobs (apps/server/server/jobs.ts): blob GC, slug release, domain re-check, audit, files sweep │ └──────────────┬───────────────────────────────────────────┬────────────────────────────────┬──────────────────┘ │ postgres-js + drizzle │ ioredis │ SMTP (nodemailer) or Resend Postgres 17: users, workspaces, apps, Redis 7: sessions, rate limits, any SMTP server versions + blobs, module data, OAuth, OTP counters, leases, caches, (EMAIL_TRANSPORT; Mailpit in dev) API keys, domains, abuse, audit serve-cache bust pub/sub ``` - **`apps/server`** is the only process: Express with `@react-router/express` for the dashboard, `mountMcpResource` for `/mcp` and the apps-host middleware in front of everything. There is no worker container and no job queue; background work runs on timers inside the process, each under a Redis lease so only one replica does it. - **One image**, `ghcr.io/freema/drobek` (root `Dockerfile`, targets `dev` and `runner`; linux/amd64 releases). The image applies every pending migration on start (core journal `__drizzle_migrations_core`, one `__drizzle_migrations_mod_` per module) and **refuses to start** on a placeholder secret, a weak `TLS_ASK_TOKEN`, a missing `APPS_DOMAIN` in production or a module it cannot load. - **Feature logic lives in packages**, not in `apps/server`: the server wires them together. The main ones: | Package | Holds | | --- | --- | | `@drobek/apps` | apps, globally unique slugs, versions, publish/restore, host classification, single-writer lease, blob GC, takedown, deletion, the public gallery | | `@drobek/compile` | the in-process esbuild compiler over an in-memory file map | | `@drobek/serving` | the apps-host handler: host → app → version → file, CSP, caches, password gate, TLS `ask` | | `@drobek/modules` | the module contract, registry, router, runtime, SDK build, limits provider, end-user sessions | | `@drobek/mcp` | the MCP tool bodies; `@drobek/oauth` = OAuth 2.1 AS + MCP resource server + API keys | | `@drobek/agent-dx` | the briefing, the tool manifest, limits, error catalogue, `/llms.txt` renderers | | `@drobek/dashboard` | the dashboard routes and their server halves | | `@drobek/auth`, `@drobek/tenancy`, `@drobek/audit` | dashboard sign-in (e-mail code, Google), sessions, rate limits, origin check; workspaces and roles; the audit log | | `@drobek/domains`, `@drobek/email`, `@drobek/insights`, `@drobek/proxy` | custom domains; the one mail transport of the dashboard and the modules (`EMAIL_TRANSPORT=smtp` via nodemailer, or `resend` via the Resend HTTP API over `fetch`); the error beacon and request stats; upstream registry, envelope crypto, SSRF guard | | `@drobek/core`, `@drobek/db`, `@drobek/sdk` | env/config, health, logger, Caddyfile generator; drizzle schema + migrations; the browser SDK core | | `modules/{auth,email,forms,data,proxy,files}` | the built-in platform modules (`drobek-module-`) | | `create-drobek-module` | the scaffold for external modules; with `@drobek/modules` + `@drobek/sdk` published to npm as `@freema/drobek-modules` + `@freema/drobek-sdk` from each release tag (`scripts/npm-packages.mjs` bundles the private packages in; modules install them under the `@drobek/*` names via npm aliases) | ## 2. Workspaces, apps and versions - A **workspace** has members with a role: `workspace-admin`, `editor` or `viewer`. Every user has a personal workspace. `SUPERADMIN_EMAIL` (a list) names the operator's super-admins; super-admin is an env flag, not a role row. Sign-up is open: anyone can create workspaces and build and preview apps. - **Who may publish** (`PUBLISH_APPROVAL`, `open` by default, plus a super-admin's per-workspace state `default` / `allowed` / `blocked`, `workspaces.publish_approved_at` / `publish_blocked_at`): a super-admin publisher is always allowed, a blocked workspace is refused in both modes (`publish_blocked`), an allowed one or one with a super-admin member may publish, otherwise `open` allows and `approval` refuses (`publish_not_approved`, naming `OPERATOR_EMAIL` or the first super-admin, recording an approval request and e-mailing the operator at most once per 24 h). `@drobek/apps` `publish()` checks it inside its transaction, so the MCP tool, the dashboard publish and the rollback share one gate. Super-admins decide at `/admin/publishing` or with the super-admin-only MCP tool `set_workspace_publishing`; blocking and unblocking e-mail the workspace's editors and admins. `PUBLISH_NOTIFY` (`first` / `every`) e-mails the operator after a publish without holding it up. Everything else about an app is never gated. - An **app** belongs to one workspace and has a **globally unique slug** (a host label; `--` is not allowed in a slug, so the preview and version host names never collide with another app). `create_app` picks a free slug and falls back to `-<4 hex>`. A deleted app keeps its slug for 30 days, then the slug is released. - A **version** is an immutable, numbered snapshot of the app's files (`app_versions` + `version_files`): the sources the agent wrote AND the compiled output, plus who made it, the agent's one-line `reasoning` and the compile status. File bytes are content-addressed blobs in Postgres (`blobs`, sha256, deduplicated across versions and apps); unreferenced blobs are garbage-collected hourly after a 7-day grace period. - **Publishing** moves one pointer, `apps.published_version_id`, to a version that compiled. Rolling production back is publishing an older version. `restore_version` rolls the working copy back by writing a NEW version with the old files — history is never rewritten. There is no git and there are no branches. - **The public gallery** (`GALLERY_ENABLED`, off by default): an editor+ lists a PUBLISHED app with a ≤ 160-character public description (`apps.gallery_listed` / `gallery_description`) in the dashboard, or an agent does with `set_gallery_listing` and the user's explicit yes (`user_confirmed: true`). `GET /api/public/gallery` on the dashboard host returns name, description, production URL, `apps.published_at` (set by every publish) and `modules` (names with non-empty saved configurations, without config values or pending proposals; not a claim of current usage or availability), newest first with a cursor or in numbered pages (`?page`, with `pages` / `total`), searchable (`?q`, name or description, ignoring case and combining accents) and sortable by name (`?sort=name`) or popularity (`?sort=popular`: 5 × likes + opens in the last 30 days), CORS `*`, cached 60 s — no owner data. Each item carries `likes` (`gallery_likes`, one row per app and signed-in account, liked on the dashboard page `/gallery/like/`) and `opens` (`gallery_opens`, a count per app and UTC day, raised by the redirect `/gallery/open/` for a GET that is not a prefetch, per-IP limited; nothing about the visitor is stored) with their `likeUrl` / `openUrl`. It filters at query time (listed, published, public, not taken down, not deleted, not hidden by a super-admin); unpublish and takedown also clear the flag. With `GALLERY_FRAME_ANCESTORS` the operator's gallery website may frame the production host of an app it shows (a live preview): the app hosts' resolve row carries `galleryVisible` (the same conditions), and a listing change busts the serve cache. - **Duplicating a gallery app**: the owner opts in with "Allow duplicates" (`apps.gallery_allow_duplicate`, off by default, kept while unlisted; the agent's `allow_duplicate` rides on the listing's confirmation). Each gallery item then also carries `duplicable`, `duplicateUrl` (the dashboard's `/duplicate/`, null when not duplicable) and `duplicates` (live copies). The dashboard page (sign-in first, `returnTo` back) and the MCP tool `duplicate_app` run the same code: @drobek/apps `duplicateAppFiles` copies the PUBLISHED version's files (source and built, with its compile status — no recompile) as version 1 of a new, unpublished app in a workspace where the person is an editor+, storing `apps.duplicated_from_app_id` / `duplicated_from_slug` (the app header shows "Duplicated from"); @drobek/modules `duplicateModuleConfigs` then proposes the source's saved module configs through the copy's normal `configure` path, so a change that needs confirmation waits on the copy's Modules page. The whole `proxy` config (upstreams of the source workspace) and every value holding an e-mail address are dropped; secrets, pending proposals, data, end users, uploads, app assets (stored per app on disk), domains and the listing are never copied. Audited as `app.duplicate` in the target workspace and `app.duplicated` in the source's (without the copier); `DUPLICATES_PER_USER_HOUR` (default 10) caps copies per person, counted from those audit rows. - **One writer at a time**: a write takes the app's Redis lease (`drobek:applock:`, 3 minutes, renewed per write). Another user's agent gets `app_locked`; the same user's other sessions take the lease over. ## 3. The compile step `write_files` (1–20 changes) → validate the paths and limits → scan for secrets (a hit refuses the write and stores nothing) → compile → store the new version (also when the compile failed, so no work is lost) → notify the serve cache. The compile result is part of the tool response. - `@drobek/compile` runs esbuild **in-process** (`context()` + `rebuild()`) over an in-memory file map. A virtual-filesystem plugin resolves relative imports only inside that map — **never the disk**. Bare imports resolve only through the app's `drobek.json` import map to pinned `https://` URLs (esm.sh), marked external: the browser loads them, the server never fetches them. `drobek` maps to the platform SDK (`/__drobek/sdk.js`); `drobek/` imports inline module components (compiled with the app's own React). - `src/main.{tsx,ts,jsx,js}` → `/main.js`, the CSS it imports → `/main.css`, `drobek.json` `entries` → more bundles. An app without `src/main.*` is plain HTML served as written. The compiler prepends the error-beacon import to every JS entry (`"beacon": false` opts out). - Limits (`COMPILE_*`): 200 files, 512 KiB per file, 5 MiB per version, an import depth of 50, 10 s per build (cancelled with its own `ctx.cancel()`), 4 builds at once and a FIFO queue whose wait answers `busy`. - **The server never executes app code** — not at compile time (the esbuild plugins are drobek's, not the author's), not to render, not to test. What it produces is served to browsers and runs there only. ## 4. Origins and hosts | Origin | Serves | Never | | --- | --- | --- | | dashboard host (`PUBLIC_APP_URL`) | dashboard, dashboard API, OAuth AS, `/mcp`, `/llms.txt`, `/report` | any app file or app JavaScript | | `.` | the published version (indexable) | the dashboard session cookie is never read here | | `--preview.` | the newest version that compiled (`noindex`) | | | `--v.` | exactly version N (`noindex`) | | | a verified custom domain | the published version (indexable) | | - `APPS_DOMAIN` should be a **different registrable domain** from the dashboard's (cookies, the Public Suffix List, phishing optics); every app is its own origin, so apps are isolated from each other and from the dashboard by the browser's same-origin policy. - Host classification (`@drobek/apps` `classifyHost`) is shared by serving, the origin check and the TLS `ask`. An unknown foreign host is the dashboard's (and 404s there); a registered but unverified custom domain answers 404 on the apps side. - A **custom domain** is a CNAME (or ALIAS / matching A/AAAA at an apex) to `.` plus a TXT record `_drobek.`; verified names are re-checked daily and lose their verification on a definitive DNS failure. One domain can be **primary**: the production host then answers 302 to it. - Dev: `APPS_DOMAIN=apps.localhost:3041` — browsers resolve `*.localhost` to loopback, so there is nothing to put in `/etc/hosts`. ## 5. Serving `@drobek/serving` answers every app-host request in a fixed order, each step before any byte of the app is touched: 1. method: GET/HEAD (plus the password-unlock POST); else **405**; 2. `/.well-known/drobek-report` → the report pointer (works for any host); 3. the unknown-host limiter: a client IP past `APPS_UNKNOWN_HOST_LIMIT` "no app here" answers per window gets **429** (without a lookup for hosts the cache does not know as live apps); 4. the app lookup — a miss is a counted **404** page; misses are kept in a separate negative cache for 30 s, hits in the positive cache for 60 s; 5. `X-Drobek-App: ` on every response from here on; 6. a taken-down app: **451** on every host and path (JSON 451 on platform paths), before the redirect, the password gate and the modules; 7. the primary-domain **302** (production host, GET/HEAD page requests); 8. visibility: a `password` app shows the password page (**401**) until the host-only `__Host-drobek_app_access` cookie (HMAC, key derived from `DROBEK_MASTER_KEY`) is set; 9. `/__drobek/*`: the SDK, the module routes and the beacon — handed to the module runtime, never to the app's files; 10. the version the host serves (**404** "not published" / "nothing compiled"), then the file: built output wins over sources, `.ts/.tsx/.jsx` sources and `drobek.json` are never served, extension-less paths fall back to `index.html`, `ETag` = sha256 → **304**; 11. no such file: the app's **asset** at that path, if any (see below). **Assets** (video, audio, images, fonts) share the app's URL space: the asset `img/s1.jpg` answers `/img/s1.jpg`, so a page keeps its own relative paths (`