| title | Explanation |
|---|---|
| description | The "why" — conceptual deep-dives. |
Conceptual deep-dives that explain why the system works the way it does. Read these when you want to build a mental model rather than complete a task.
These pages are the canonical reference for design rationale.
Where they disagree with how-to guides, the how-to guide is
wrong; where they disagree with SPEC.md,
SPEC is the source of truth and we want to know — file an issue.
- Design principles — the six rules that decide every architectural argument.
- Architecture tour — the end-to-end picture: agent + control plane, three execution modes, plugin model.
- WAL pipeline — streaming as the data plane;
single / replica-offload / dual / sync-target / cascading
modes; the optional
archive_*belt-and-suspenders paths. - Durability modes — deferred chunk writes
- one barrier per segment;
per-segmentvsper-chunk; why pg_hardstorage is an async archiver, not a synchronous standby.
- one barrier per segment;
- Patroni failover deep-dive — the four cooperating mechanisms (REST awareness, slot continuity strategies A/B/C, dual-slot, sync-target) and timeline storage.
- Content-addressed storage — FastCDC + page-aligned splits, plaintext SHA-256 keys, per-tenant fingerprint resistance.
- Envelope encryption — RKEK / BDEK / per-chunk Kc, AES-GCM-SIV vs AES-GCM-FIPS, KEK rotation flow.
- TDE awareness — handling source PG with Transparent Data Encryption (CYBERTEC PGEE, pg_tde, EDB TDE): the one config flag, what does and doesn't change under TDE, the failure modes if it's forgotten.
- Audit chain — hash-chained Merkle audit log,
transparency-log anchoring, what
audit verify-chainactually checks. - LLM safety stack — the five gates (preview-required, replay-protected execute, typed confirmation, RBAC, n-of-m, anomaly refusal) plus signed evidence bundles.
- Threat model — attacker capabilities the design defends against, and what is explicitly out of scope.
- Three execution modes — embedded, agent + control plane, sidecar; when to pick each.
- Coordination without etcd — the progressive ladder from JSON state files up to opt-in etcd.
- Tier-1 vs Tier-2 plugins —
compile-time vs
go-plugin, trust posture, registry roadmap. - Verify-sandbox tradeoffs — Docker default vs Firecracker microVM; isolation vs setup cost.
- [pg_hardstorage vs pgBackRest, WAL-G, Barman] (comparison-pgbackrest-walg-barman.md) — honest comparison; what each tool does best; when to pick which.