Architecture Overview
Detent separates three jobs that most configuration systems blur together: deciding what the configuration is, distributing it, and serving it to code. Each runs at a different speed and fails differently, and keeping them apart is what lets a read stay a few hundred nanoseconds while distribution can be down for an hour.
The Big Picture
Section titled “The Big Picture”This is the managed profile, the topology Detent’s production contract targets.
The Actors
Section titled “The Actors”| Actor | What it does | Runs on | Binary |
|---|---|---|---|
| Producer | Writes knob changes as namespaced transactions | Anywhere that reaches the authority | Your service, or curl |
| Authority | Orders, stores and serves the source of truth | Three machines, one voter each | detent-authority --authority authority.json |
| Relay | Optional fan-out: one upstream subscription per bundle, many agents | Between the authority and agent hosts | detent-relay |
| Agent | Receives snapshots and deltas, publishes immutable generations | Every application host | detent-agent --managed managed.json |
| Client | Maps the selected generation and reads in memory | Every application host | Your app (detent::Client), detent get |
Voters, relays and agents are all daemons; “daemon” names no role. Each actor has its own page: Authority, Relay, Agent and Delivery and Local Images for the agent’s generations, and Read Path for the client. Detent’s actors in the repository is the full reference: endpoints, files, build options, default directories and restart behavior for every actor.
Three Planes
Section titled “Three Planes”Data Plane: Reads
Section titled “Data Plane: Reads”The read path runs inside your process and does nothing but memory access: validate the name, check the CLI override table, load the current snapshot pointer, look up the knob, and evaluate it. No network, disk, lock or allocation. See Read Path.
Update Plane: the Client’s Background Thread
Section titled “Update Plane: the Client’s Background Thread”One background thread per client picks up new state from its source. With
managed delivery, it watches the agent’s selected descriptor and maps each
new generation. With a file source, it fetches candidates, validates them
completely, gates them by version, merges them over the baked defaults, and
publishes the result with one atomic store. Failures never reach readers. See
Update Path.
Control Plane: Distribution
Section titled “Control Plane: Distribution”The authority accepts transactions and replicates them durably across its voters; relays and agents carry the committed state to every host as snapshots and deltas. See Authority and Relay.
Design Principles
Section titled “Design Principles”- Reads never wait on distribution. A distribution failure degrades freshness, never availability.
- Immutable snapshots, atomic swaps. Readers see one complete, validated configuration or the previous one, never a mixture.
- Fail fast on programmer errors. A missing knob is a bug, so it’s loud; an unreachable source is an outage, so it’s quiet and observable.
- Whole-definition replacement. A knob is an atomic unit; there’s no field-level merge to reason about.
- Everything is bounded. Request bodies, snapshot sizes, queues, history, retained memory and disk are all limited before allocation.
- Measured, not asserted. Performance claims come with a reproducible benchmark and its caveats.
Where to Read More
Section titled “Where to Read More”- Read Path and Update Path: the client.
- Agent: host-local reads.
- Durable Authority: transactions and durable consensus.
- Relay: optional durable fan-out.
- Delivery and Local Images: managed distribution and immutable generations.
- Dependencies: the libraries Detent is built from.
- Design Documents: the full engineering record in the repository.