Design decisions (ADRs)
Denia records architecture decisions as ADRs in
docs/adr/. They are the
source of truth for accepted decisions — this page indexes all 37 and links
each to its source. Architecture changes (runtime isolation, ingress, secrets,
persistence, API, dependencies) require a new or updated ADR.
Status legend: Accepted — in force; Proposed — drafted, not yet ratified; Superseded — replaced by a later ADR.
| ADR | Title | Status |
|---|---|---|
| 001 | Initial Backend Architecture | Accepted |
| 002 | Frontend Effect Logic Layer | Proposed |
| 003 | Linux Runtime Process Runner | Accepted |
| 004 | Embed Web Console in Service Binary | Proposed |
| 005 | Runtime Security Hardening | Accepted |
| 006 | Projects And Versioned Migrations | Proposed |
| 007 | Ingress + TLS | Proposed |
| 008 | Project-Scoped RBAC | Proposed |
| 009 | Observability (Node, Workloads, Access Log) | Proposed |
| 010 | Jobs and Scheduler | Proposed |
| 011 | In-Process OCI Image Acquisition | Proposed |
| 012 | src/ Modularization and Per-Aggregate Repositories | Proposed |
| 013 | Domain Support With HTTP File Verification | Accepted |
| 014 | Per-Service OCI Registry Configuration | Proposed |
| 015 | Streaming OCI Layer Staging | Proposed |
| 016 | Denia-Managed Traefik | Superseded by 020 |
| 017 | Service CRUD API | Proposed |
| 018 | Autoscaling | Accepted |
| 019 | Per-Replica Runtime Filesystem Isolation | Accepted (amended by 026) |
| 020 | In-Process Pingora Ingress | Accepted |
| 021 | Control-Plane SOPS Secret Encryption | Accepted |
| 022 | Persistent OCI Layer Cache With Weekly GC | Accepted |
| 023 | TOML Config File With Env Override | Accepted |
| 024 | Async Deployments With Per-Deployment Log Stream | Accepted |
| 025 | CLI-Driven Host Provisioning | Accepted |
| 026 | Privileged Overlay Mount Before the User-Namespace Unshare | Accepted |
| 027 | Workload Lifecycle Bound to the Daemon | Accepted |
| 028 | Deploy→Autoscale Replica Ownership Handoff | Accepted |
| 029 | Self-Update From Signed GitHub Release Binaries | Accepted |
| 030 | Cross-Platform Client CLI | Superseded by 034 |
| 031 | Hosted OCI Registry | Accepted |
| 032 | HTTP/2 Ingress Hardening | Accepted |
| 033 | Service Console | Accepted |
| 034 | Client-Driven Deploy via Working-Tree Upload | Accepted |
| 035 | Control Domain Over Ingress | Accepted |
| 036 | General-Purpose Protocol Ingress | Proposed |
| 037 | Cross-Platform Client via cfg-Gated Single Crate + crates.io | Proposed |
The decisions that shape the product
- No container runtime (001, 003, 005) — workloads run under Denia-owned namespaces + cgroup v2 + dropped caps, not Docker/containerd/runc.
- Per-replica overlay rootfs (019, amended by 026) — each replica gets an isolated mutable layer; the privileged overlay mount happens before the userns unshare.
- In-process ingress + TLS (020, supersedes 016; 032, 035) — Pingora +
instant-acme, no Traefik/certbot. - Secrets out of the database (021, 023) — SOPS-encrypted files to a host-local age identity; SQLite stores references only.
- Health-gated async deploys (024, 028) — promote only on a passing health check; clean deploy→autoscale handoff.
- Client-driven deploy (034, supersedes 030) —
denia pushuploads the working tree; no local Docker. - Signed self-update (029) — minisign-verified GitHub release binaries, atomic swap.
- Hosted registry (031) — same-origin
/v2OCI Distribution with conservative GC.