Architecture
- Written for
- ＋ Written for
- Deprecated
- ＋ Deprecated
- Applies to
- ＋ Applies to
Architecture
Cookie Munch is a monorepo of small, framework-agnostic TypeScript packages. This page maps the pieces so you know where to look when integrating: what runs in the visitor's browser, what runs on the server, and which surface (dashboard API vs. developer API) you should be calling.
The three runtime surfaces
Surface | Who calls it | Auth | Purpose |
|---|---|---|---|
Embed ( | Visitor browsers | None (public) | Renders the banner, blocks trackers, records consent |
Dashboard API ( | The Cookie Munch web app | Session cookie | Everything the dashboard UI does — property/banner CRUD, org settings |
Developer API ( | Your servers, the SDK, the MCP server | API key ( | Stable, versioned automation surface — the subject of this reference |
This documentation section covers the embed (this page, embed scripts, JavaScript API, data-attributes) and the Developer API (authentication onward). The dashboard API is internal and not covered here — if you need to automate something the dashboard can do, use /v1 instead; it is the versioned, supported surface for external integrations.
Note: The dashboard API and the Developer API are deliberately separate implementations (
control-plane.tsvs.dev-api.tsin the server package) even where they overlap (e.g. banner-library CRUD). This means the Developer API can evolve on its own version/compat guarantees without being coupled to dashboard UI changes.
Request flow, end to end
A visitor loads your page. The
<script>tag you installed (see embed scripts) pullsconsent.jsfrom the embed origin (https://cdn.cookiemunch.netby default, or your own domain if you're self-hosting).consent.jsinstalls the auto-blocker synchronously, before your page's own scripts run, then fetches the site'sSiteConfigfromGET /config/:cbidon the API origin (https://api.cookiemunch.net).Once configured, it renders the banner (or applies implied consent per your region rules), exposes
window.CookieMunch(see JavaScript API), and beacons impressions/consent decisions back to the API — all unauthenticated, since this is public client-side telemetry, not account data.If IAB TCF, GPP, or US Privacy is enabled for the site, a small synchronous stub (
__tcfapi/__gpp/__uspapi) is installed immediately, and the heavierconsent-tcf.jsbundle (which encodes/decodes the IAB TC string) loads lazily in the background so the base embed stays small for sites that don't need it.Your backend — or a script you run in CI, a cron job, or an internal tool — authenticates with an API key and talks to
/v1(this reference) to read consent stats, export audit logs, manage sites, or drive DSAR/vendor/RoPA workflows.
Packages
The functionality behind these surfaces is split into focused workspace packages (packages/*), published as @cookiemunch/*:
Package | Responsibility |
|---|---|
| The embed runtime: consent engine, banner UI, auto-blocker, TCF/GPP/USP bridge, i18n |
| HTTP surfaces: the dashboard API, the |
|
|
| An MCP server exposing |
| Multi-tenant primitives: orgs, sites, members, API keys + scopes, webhooks |
| IAB TCF v2.2 GVL cache, purpose mapping, TC-string encode/decode |
| Data-subject-access-request lifecycle |
| Vendor risk register and RoPA (Records of Processing Activities) |
| Signed ISO/IEC-27560-style consent receipts (HMAC-SHA256) |
| Framework bindings over the core embed |
Deployment model
Cookie Munch is single-tenant self-hosted: one deployment, one Postgres database, serving all your organizations. There is no cross-account data plane to reason about — an API key is scoped to exactly one org, and every cbid path on /v1 is checked for org ownership server-side (a key from org A gets a 404, not a 403, reading org B's site — the API never confirms another org's resource even exists).
Next: Embed scripts for exact installation, or Authentication & scopes to start calling /v1.