Monorepo overview

The platform is one repository: a pnpm workspace driven by Turborepo. Three apps ship to production, a dozen packages hold the shared code, and the starters and the product's own website live next to them so they are built and type-checked with the same toolchain. This page is the map. The rules you follow while working in it are in Conventions; docs/ARCHITECTURE.md in the repository is the source of truth for module boundaries and the tenancy model, and this page follows it.

Toolchain

The workspace globs are in pnpm-workspace.yaml:

packages:
  - "apps/*"
  - "packages/*"
  - "starters/*"
  - "sites/*"

Only @biomejs/biome, @resvg/resvg-js, sharp and esbuild are allowed to run install scripts (allowBuilds).

Top-level layout

apps/
  dashboard/   The app agencies and clients log into. Auth, agencies, workspaces, CMS editor,
               brand, social, Studio, toolkit, MCP endpoint, delivery of the handleiding. :4100
  web/         Multi-tenant public web app: delivery API /api/v1, legacy hosted site
               renderer, statistics collection, forms. :4101
  agent/       Kwisple Agent: answers kwisple.assistant/v1 tasks and the assistant chat with
               a language model. The only process that talks to a model. :4110
packages/      Shared code (below).
starters/
  next/        Starter for a client site repository (Next.js 16 + @kwisple/sdk). :4102
  astro/       Starter for a client site repository (Astro + @kwisple/sdk/astro). :4104
sites/
  kwisple/     The product's own website, made with the product (Astro). :4105
docs/          Internal design documents, the handleiding (served on /hulp) and this
               developer documentation.
tools/         Repository scripts: i18n and action checks, release dry run, Lighthouse
               guard, backup drill, go-live scripts, the rule-based assistant stub.
infra/         docker-compose for local Postgres + S3 storage + Mailpit, the production
               compose file, the Caddyfile and the backup image.
e2e/           Playwright tests of the core flows against a running dashboard.
Dockerfile     Multi-target production image (dashboard, web, worker, agent, migrate).
.github/workflows/ci.yml   The CI pipeline.

Apps

apps/dashboard (@kwisple/dashboard, port 4100)

The dashboard is the product. It owns authentication (Better Auth), the three-level tenancy (platform → agency → workspace), every editor (CMS entries, brand kit, social posts, Studio canvas), the toolkit, billing, requests, notifications, the Websitecheck, the MCP endpoint for agents (/api/mcp), the CLI endpoints (/api/cli/*), the apps API (/api/apps/v1) and the handleiding on /hulp.

Important folders under apps/dashboard/src:

apps/web (@kwisple/web, port 4101)

One deployment serves every client site that the platform renders itself and the delivery API for custom-code sites. src/proxy.ts reads the Host header, maps it to a site key and rewrites the request into the internal /-sites/[key]/[locale]/… tree (or /-preview/… for live preview). Everything under /api is left alone:

src/blocks/* holds the renderers of the legacy hosted blocks (see The content engine).

apps/agent (@kwisple/agent, port 4110)

A small node:http service (src/server.ts) that answers POST / tasks (social.captions, social.ideas, website.review) and POST /chat (the assistant chat, NDJSON stream), with GET /health. It depends on @kwisple/core and nothing else from the platform; the model sits behind the Model interface in src/model.ts (ClaudeModel reads ANTHROPIC_API_KEY). It runs with tsx (pnpm agent at the root).

Packages

Every package exports TypeScript source directly ("exports": { ".": "./src/index.ts" }); the monorepo never builds them for internal use. Only @kwisple/cms, @kwisple/sdk and create-kwisple-site are published to npm; they get a dist/ through tools/build-package.mjs and swap their exports with publishConfig at publish time.

Dependency direction

Taken from docs/ARCHITECTURE.md §2; never the reverse.

core ← brand ← social
core ← db ← jobs
core, db ← analytics
cms, core, db, storage ← content
cms ← sdk                          (client site repos; never imports db)
core, db, brand, storage, social, ui, cms, content, analytics, jobs ← apps/dashboard, apps/web
core ← apps/agent                  (nothing else from the platform)

Rules that follow from it:

• Apps never import from other apps. apps/web and apps/dashboard talk over HTTP (/api/revalidate) and through the database, never through imports.
• The agent only imports @kwisple/core (protocol types and schemas). It has no database, no storage and no knowledge of the dashboard's internals; it reaches platform data through the MCP endpoint with a short-lived chat token, with exactly the rights of the person.
• Content reads and writes go through @kwisple/content. Apps never query cms_* tables.
• Every tenant-scoped query goes through forWorkspace(db, workspaceId) from @kwisple/db.
• @kwisple/cms and @kwisple/sdk are published packages used inside client repositories, so they stay free of server dependencies.

Starters and sites

pnpm build at the root excludes the starters and the product site (--filter=!@kwisple/starter-next --filter=!@kwisple/starter-astro --filter=!@kwisple/site-kwisple); they are type-checked and tested like everything else.

Ports at a glance

Turborepo tasks

turbo.json defines build (depends on ^build, caches .next/** and dist/**), dev (persistent, uncached), typecheck and test (both depend on ^build) and start. Root scripts wrap them:

Environment variables the tasks may read are listed in globalPassThroughEnv in turbo.json; a new variable must be added there or Turborepo hides it from the task.

Request paths

A public site request (custom-code site)

visitor ──► client site (own repo, Next.js or Astro, own hosting)
              │  @kwisple/sdk createClient(...).entryByPath(...)
              ▼
            apps/web  /api/v1/entry        Authorization: Bearer <site token>
              │  authenticate(req, "read")  → authenticateToken (cms_api_token, cached 60 s)
              │  cachedRead(...)            → unstable_cache, tags cms:site:<id> (+ entry tags), 1 h
              │  findEntry(ctx, …)          → @kwisple/content → forWorkspace(db, ws) → cms_* tables
              ▼
            JSON { entry }  (private, max-age=60, stale-while-revalidate=600)

When an editor publishes, the dashboard calls afterContentChange (lib/services/cms-publish.ts): it POSTs the changed tags to apps/web /api/revalidate and, for a headless site, sends the signed webhook to the site's /api/revalidate, which purges the SDK's kwisple:all tag. The next visitor gets fresh content; nothing is rebuilt.

A public site request (legacy hosted site)

visitor ──► apps/web (Host: client.be or <slug>.<PLATFORM_DOMAIN>)
              │  proxy.ts: host → site key, locale prefix, preview token check
              │  rewrite → /-sites/[key]/[locale]/[[...slug]]   (ISR, revalidate = false)
              │  lib/site.ts getSite…  (unstable_cache: host:*, site:<id>, brand:<ws>, agency:<id>)
              │  @kwisple/content findEntry → RenderBlocks (apps/web/src/blocks)
              ▼
            HTML, cached until a tag purge from the dashboard

A dashboard request

browser ──► apps/dashboard  /w/<workspace>/social
              │  proxy.ts: session cookie present? else redirect to /login/<workspace>;
              │            sets x-kwisple-workspace header for texts that name the agency
              │  layout + page (Server Components)
              │    requireWorkspace(slug)  → session, resolveWorkspaceAccess
              │                              (platform admin / agency member / workspace member,
              │                               access policy → grants, "Bekijk als klant" cookie)
              │    can(ctx, "social.view")  → hide or redirect(NO_ACCESS)
              │    services (lib/services/*) with ctx.wdb = forWorkspace(db, workspace.id)
              ▼
            HTML; later interactions call server actions (lib/actions/*), which run
            requireWorkspace + can() again, validate with Zod, write through services and
            revalidatePath(...)

Heavy work (renders, exports, mails, webhooks) is never done in these requests: the action calls enqueue(...) and the worker picks it up (Jobs and the worker).

Where to read next

• Local setup: get all of this running on your machine.
• Conventions: the rules with the why.
• Tenancy and permissions, The content engine, Jobs and the worker, Languages and design system.
• Adding things: recipes, Testing and checks, Deploying the platform.