Quillet
Menu
Menu

How the parts fit

4 min read

Quillet is one process that serves two APIs and the dashboard, and each of its clients (the dashboard, the CLI, the SDK and your site) reaches it with its own kind of credential.

Why one process serves both APIs and the dashboard

A content manager and an engineer touch different parts of Quillet, and it helps to know which part answers whom. When a page shows old copy, or a request answers 403, the first question to ask is which surface was called and with which credential.

The shape is small on purpose. One image runs one process. That process serves the management API, the delivery API and the dashboard's files. There is no separate frontend service to keep in step, so there is one thing to deploy and one thing to scale. Behind the process sit two stores and a place for bytes. Mongo holds every document and the record of every file. The files' bytes live on a mounted disk or in an S3-compatible bucket. Redis holds sessions, rate-limit counters and the delivery cache.

What each part calls, and with which credential

Everything that writes goes through /api/v1; your site only ever reads /d/v1, and only with a delivery key.

The two APIs

The management API lives under /api/v1. Content is written, versioned and published there, and it is also where projects, environments, keys and webhooks are managed. It reads drafts as well as published content, so it is never cached.

The delivery API lives under /d/v1/<project>/<env>. It serves published content, resolved for a locale, and its answers are cached. Without a preview token, nothing on it can reach a draft, another environment or a write. That is true by construction, not by policy, which is why it can sit behind a CDN without anyone reasoning about who is asking. A preview token widens it for fifteen minutes, and never from the cache: with one, it answers one document's draft in one locale and lists every draft in the environment by key, title and tags. Files are served beside it, at /d/v1/<project>/assets/<id>.

The parts that call them

Part Who uses it Calls Credential
Dashboard content managers, owners /api/v1 an account, signed in
CLI, a CI job, a build that writes engineers /api/v1 a CLI key or a personal token
Your site, through the SDK or fetch readers /d/v1 a delivery key
A browser drawing an image readers /d/v1/<project>/assets/<id> none, for a public file

The SDK, @quilletcms/sdk, is a read client for the delivery API. It runs in Node, in a browser, in Next.js and at build time. The CLI, @quilletcms/cli, is the part that writes: it pushes and pulls a folder of files, publishes, and takes backups. Your site is yours, and Quillet sends it nothing unless you subscribe a webhook.

How to

Two requests show the split. The first asks the API whether it can reach both of its stores:

curl -s http://localhost:3000/readyz

It answers {"status":"ok","mongo":"up","redis":"up"}. The second asks the management API who you are, using a CLI key:

curl -s -u '<keyId>:<secret>' http://localhost:3000/api/v1/auth/me

It answers "kind":"key" with the project, the environment and the scopes the key holds. Send a delivery key to the same route and it is refused with a 403, because a delivery key belongs to /d/v1 and nowhere else.

Limits

  • Mongo must run as a replica set. A push and a promotion are transactions.
  • The webhook worker runs inside the API process. With several replicas, only one of them at a time polls for due deliveries.
  • There is no CDN in the box. You may put one in front of the API, but never in front of the storage bucket, which stays private.
  • The interactive API reference at /api/docs exists only in development.
  • Search inside the dashboard, over drafts, is not built. Delivery search reads published content.
  • There is no MCP server, and there is no SDK for a language other than JavaScript.

Last updated