Architecture Decision Records¶
Architecture Decision Records for ABOS. Each ADR is immutable once accepted; supersede rather than edit.
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-0001 | Orchestration-first, not system-of-record | Accepted | 2026-07-25 |
| ADR-0002 | Engines vs products | Accepted | 2026-07-25 |
| ADR-0003 | Config, not code, for client specificity | Accepted | 2026-07-25 |
| ADR-0004 | Structured predicates only for rules | Accepted | 2026-07-25 |
| ADR-0005 | Rule precedence | Accepted | 2026-07-25 |
| ADR-0006 | Control plane holds the map, not client content | Accepted, superseded in part by ADR-0042 | 2026-07-25 |
| ADR-0007 | Multi-tenant deployment topology | Accepted | 2026-07-25 |
| ADR-0008 | Data residency and region | Accepted | 2026-07-25 |
| ADR-0009 | LLM provider strategy | Accepted | 2026-07-25 |
| ADR-0010 | Secrets handling | Accepted (extended by ADR-0027) | 2026-07-25 |
| ADR-0011 | Surfaces: BOS Console vs Client App | Accepted, superseded in part by ADR-0037 | 2026-07-25 |
| ADR-0012 | Client exit / data ownership | Accepted | 2026-07-25 |
| ADR-0013 | Tenant deployment modes (Demo / Pilot / Full) | Accepted | 2026-07-25 |
| ADR-0014 | VPS provisioning & server hardening baseline | Superseded by ADR-0021–0027 | 2026-07-25 |
| ADR-0015 | Staging and production environments | Accepted | 2026-07-25 |
| ADR-0016 | Golden templates vs disposable demo vs client pilot | Accepted | 2026-07-25 |
| ADR-0017 | Employees as Principals; cross-employee isolation via Postgres RLS | Accepted | 2026-07-31 |
| ADR-0018 | Hermes Agent not adopted; Hermes models a future self-hosted candidate | Accepted | 2026-07-31 |
| ADR-0019 | SkillOpt: optional, deferred learned-layer optimiser | Accepted | 2026-07-31 |
| ADR-0020 | WebAssembly/WASI held as a watch item for per-tool sandboxing | Accepted (Watch) | 2026-07-31 |
| ADR-0021 | Host baseline and hardening | Accepted | 2026-08-17 |
| ADR-0022 | Edge routing, TLS and hostname scheme | Accepted, superseded in part by ADR-0040 | 2026-08-17 |
| ADR-0023 | Container and tenant isolation | Accepted | 2026-08-17 |
| ADR-0024 | Ansible repository layout and provisioning model | Accepted, superseded in part by ADR-0042 | 2026-08-17 |
| ADR-0025 | Control-plane co-location and migration trigger | Accepted | 2026-08-17 |
| ADR-0026 | Backup and retention posture | Accepted | 2026-08-17 |
| ADR-0027 | Secrets and credential custody | Accepted, superseded in part by ADR-0039 and ADR-0042 | 2026-08-17 |
| ADR-0028 | Documentation surface | Accepted | 2026-08-17 |
| ADR-0029 | Deployment targets from a single repository | Accepted, superseded in part by ADR-0040 | 2026-08-17 |
| ADR-0030 | Multi-host composition: what is global, what is per host | Accepted | 2026-08-17 |
| ADR-0031 | Tailscale for administrative access | Accepted | 2026-08-18 |
| ADR-0032 | The brain: execution model and data access | Accepted | 2026-08-18 |
| ADR-0033 | Employee/HR management is a Product on ABOS, dogfooded on Octopodia's own tenant | Proposed | 2026-07-18 |
| ADR-0034 | Alerting and notification model | Accepted | 2026-08-19 |
| ADR-0035 | Scheduling capability model | Accepted | 2026-08-19 |
| ADR-0036 | Alert delivery: one sender, one scoped app, a secret per host | Accepted | 2026-10-11 |
| ADR-0037 | BOS Console: scope, operating principle and data boundary | Accepted, superseded in part by ADR-0041 | 2026-10-11 |
| ADR-0038 | Tenant link and metrics ingest | Accepted | 2026-10-11 |
| ADR-0039 | Console runner and secrets custody | Accepted, superseded in part by ADR-0042 | 2026-10-11 |
| ADR-0040 | Console access: Cloudflare Tunnel, Access and a tailnet break-glass | Accepted | 2026-10-11 |
| ADR-0041 | Masked in-place view of the corrections behind a count | Accepted | 2026-10-13 |
| ADR-0042 | Inventory repository, tenant secrets and new vault passwords | Accepted | 2026-10-15 |
Superseded ADRs¶
ADR-0014 recorded nine unrelated decisions in one document, so no single part could be revised without reopening all of it. It is split as follows:
| ADR-0014 section | Now |
|---|---|
| §1 provider, sizing | ADR-0021 |
| §1 control-plane co-location | ADR-0025 |
| §2 SSH, §3 firewall | ADR-0021 |
| §4 Caddy, TLS | ADR-0022 |
| §5 Docker, §6 Postgres, §7 n8n | ADR-0023 |
| §8 backups | ADR-0026 |
| §9 secrets | ADR-0027 |
Superseded in part¶
Accepted ADRs where a later ADR replaces one section and the rest stands.
| ADR | Section | Superseded by | What changed |
|---|---|---|---|
| ADR-0011 | Decision, in part | ADR-0037 | The Console shows and changes, and is its own application at its own hostname, not reached through the Internal Portal UI |
| ADR-0021 | §5 in part, §6 | ADR-0031 | Administrative access over Tailscale; the public SSH port is closed |
| ADR-0022 | §1 and §2, in part | ADR-0040 | The console route goes through a Cloudflare Tunnel, not Caddy |
| ADR-0027 | §3 and §5, in part | ADR-0039 | The Console runner holds vault passwords unattended on the control machine |
| ADR-0029 | §2, in part | ADR-0040 | The Console is reached through a Cloudflare Tunnel, not behind Caddy |
| ADR-0037 | §4, in part | ADR-0041 | The Console shows a masked line per correction behind a count (row number, sorted and corrected times, rule, from and to bucket), fetched live from the tenant's n8n and never stored. The email itself is still seen only in n8n |
| ADR-0006 | Tenant record creation, in part | ADR-0042 | The Console creates a tenant record when create tenant is approved; the playbook's pre-flight gate checks it |
| ADR-0024 | §4, in part | ADR-0042 | The static inventory lives in its own private repository, octopodia-abos-inventory, which the runner commits to |
| ADR-0027 | §11, in part | ADR-0042 | A new tenant's vault password is shown once to the approver after a passkey step-up, encrypted end to end, and stored by them in Bitwarden |
| ADR-0039 | §7, in part | ADR-0042 | The runner also checks out the inventory repository, at a recorded commit |