Architecture at a glance
One diagram covers the whole request path. Each hop below it explains one box in the diagram.
The diagram
Section titled “The diagram”The hops
Section titled “The hops”1. Callers
Section titled “1. Callers”Three kinds of caller share one API:
| Caller | How it signs in | What it gets |
|---|---|---|
| The browser SPA (single-page application) | A session cookie, after a password, MFA, or SSO login | The full workspace UI |
| An app | OAuth 2.1 with PKCE. The user consents and elects one role | The rights of that role, cut down by the app’s grant |
| An agent | MCP (Model Context Protocol) under one pinned role | The tools that role may see |
Static API keys and backend service accounts also enter here. A request with
no credential runs under the seeded anonymous role — its read grants are
the whole public API surface. A presented but invalid credential always
answers 401; it never downgrades to anonymous.
2. Entry — HTTP and MCP
Section titled “2. Entry — HTTP and MCP”The Crystal backend serves the routes. Document routes look like
/Api/{domain}/{doctype}; platform routes start with an uppercase segment
(/Api, /OAuth, /Ws, /Healthcheck). The auth chain rejects an invalid
credential before any handler runs.
3. Auth context
Section titled “3. Auth context”Facet bundles the caller into an auth context: the principal, the one role it acts under, and — for apps — the grant. Roles never merge. Humans, apps, and agents all act under this one model, so enforcement behaves the same on every channel.
4. Enforcers
Section titled “4. Enforcers”The read and write enforcers turn role permissions into database checks:
- A permission names an action, a doctype path, and an optional row scope.
- Row scopes compile to SQL predicates. A list returns only the rows the role can see.
- Field tags mask invisible fields on reads and refuse writes into them.
- A denied single read answers the same
404as a missing document.
5. Mutation log
Section titled “5. Mutation log”An accepted write appends one row to the mutations table: who acted, through
which channel, on which document, with what change, and what caused it — a
request, an action, a hook, a rollback. The table is append-only. A retention
job replaces history older than the retention window with one snapshot row.
6. Projections
Section titled “6. Projections”A PostgreSQL trigger applies each mutation to the projections table, which
holds the current state: the content, the display name, the search text, and
the backlinks. Reads never parse the log. They read projections, with the
role’s scope predicates applied. Each row stores the id of its last mutation;
that value is the ETag (concurrency token) for optimistic writes.
7. Event bus
Section titled “7. Event bus”After the database commit, the write path publishes events to Redis Streams. Consumers react: domain hooks run Lua, webhooks deliver signed envelopes, replication copies fields across domains, and the WebSocket bridge pushes live updates to browsers. Delivery is at-most-once by decision. The data of record stays in PostgreSQL.
Reactions that write documents re-enter at hop 2, under the identity the reaction runs as, and leave their own audit rows.
See it yourself
Section titled “See it yourself”The served OpenAPI document describes the v1 API surface. It needs a signed-in caller, like every control-plane read:
curl -sS -H "Authorization: Bearer $FACET_TOKEN" \ https://your-facet-host/Api/openapi.jsonRelated
Section titled “Related”- Security & governance overview — the enforcement rules in detail.
- What is Facet — the product story behind this diagram.
- Glossary — the terms used above.
- Internals on GitHub: rbac.md, mutation.md, event.md.