Architecture Decision Records (ADR Register)
Architecture Decision Records capture why the platform is built the way it is —
the decision, its context, and its consequences. They were previously scattered
across four folders with colliding numbering (two different ADR-001s). This
register is the single entry point; each entry links to the source record.
:::info Consolidation in progress The records still live in their original folders while they are reconciled and renumbered into a single sequence. This page is the canonical index in the meantime — start here. :::
Deployer architecture ADRs
The numbered decision record for the deployer’s architecture (microservices, runner modes, state, sync-waves, patches, multi-tenancy).
- ADR-001: Microservices Architecture for the Orchestrator Portal
- ADR-002: Server / Runner Dual-Mode Binaries
- ADR-003: Server-Sent Events for Real-Time Deployment Logs
- ADR-004: File-Based Instance State
- ADR-005: Rendered-Manifests Mode (Local Templating, Plain YAML in Git)
- ADR-006: Application-of-Applications, Not ArgoCD ApplicationSet
- ADR-007: Sync-Wave Ordering Driven by a Versioned Release Graph
- ADR-008: Fork-and-Pin Upstream openDesk
- ADR-009: Checkpoint-Based Step Resumption and Upgrade Classification
- ADR-010: Always-Re-Run Steps
- ADR-011: Prerequisite Steps Run Before ArgoCD Sync
- ADR-012: ArgoCD Sync Wait and Bounded Recovery
- ADR-013: Two-Stage Patch Architecture for Upstream Customisations
- ADR-014: Declarative YAML Patches for Render-Time Fixes
- ADR-015: customerId as the Multi-Tenancy Key
- ADR-016: Registered-User-Keyed Sizing Tiers
- MonitoringSystem
Platform domain ADRs
Cross-cutting platform decisions by domain: infrastructure, deployer, monitoring, backup, IdP, web UI, secrets.
- ADR-001: Infrastructure Provisioning via STACKIT
- ADR-002: OpenDesk Application Deployment via Rendered-Manifests GitOps
- ADR-003: Observability Stack — Prometheus, Grafana, and Alerting
- ADR: Backup and Restore Strategy
- ADR-005: Automated External IDP Configuration via Deployer Pipeline
- ADR-006: Web UI and Multi-Service Orchestration Architecture
- ADR-007: Secrets Management and Security Architecture
Focused ADRs
Narrowly-scoped decisions (YAML overrides, config-in-git, notes automation, safe-destroy).
- ADR: Advanced YAML Override System
- ADR: Config in Git — where deployer configuration lives and how it's applied
- ADR: Automating the Notes (Impress) initialization fix
- ADR: Safe Destroy — Blast Radius Validation Layer
- Deploy phase ownership — who installs what
- IDP Integration Architecture — How It Works Today
- Platform releases and channels
- Tier-driven infrastructure inheritance
Workflow ADRs
Release and sync-strategy decisions.