ADR index¶

Every load-bearing technical decision Ampora has made lives in an Architecture Decision Record. The ADRs themselves are in docs/adr/ in the repository in their original language; this page gives a one-paragraph English summary and a stable anchor per ADR that the rest of the docs can link to.

Phase 1–4 — MVP¶

ADR-001 — OpAMP in C¶

Implement the OpAMP protocol natively in C# rather than wrapping a Go reference implementation. Keeps the wire format under our control and avoids a polyglot runtime.

ADR-002 — PostgreSQL as primary persistence¶

Standardise on PostgreSQL 16+ for the prod store; SQLite for dev only. JSONB for semi-structured columns, GIN indexes for the high-cardinality ones.

ADR-003 — Blazor Server as the MVP UI¶

SignalR-driven UI, single binary, full-stack C#. Trades client-side ergonomics for one runtime, one repo, one deploy.

ADR-004 — Cytoscape.js for pipeline visualisation¶

The visualiser is read-first; Cytoscape.js gives us layout, edge routing, and SVG export with a small footprint.

Phase 5 — Governance foundations¶

ADR-005 — Package management & binary updates¶

Define the package model, content-addressable storage, and the OpAMP package transfer flow.

ADR-006 — Credential rotation¶

Scaffold for agent-side mTLS rotation via AcceptsConnectionSettings. Productionised in ADR-012.

ADR-007 — Policy-based governance¶

Built-in policies (default-deny exporter swap, default-deny TLS-insecure-non-localhost). Custom policies follow in ADR-033.

ADR-008 — Semantic config diff¶

Diff at the component-AST level rather than the textual level. Reviewers should see "added an exporter to the metrics pipeline", not line numbers.

ADR-009 — Percentage rollouts¶

Express batches as fractions of the target group. Composes with re-evaluation on dynamic groups.

ADR-010 — Dynamic agent groups¶

Label-selector groups defined via the same DSL as policies and lint rules. Reconciled by a leader-elected service.

Phase 6 — Production-ready fleet¶

ADR-011 — Canary rollout schedules (step-up)¶

Percentage rollouts with time-based dwell between steps. The default safe strategy.

ADR-012 — Automatic credential rotation flow¶

End-to-end automatic mTLS leaf rotation on agents that signal AcceptsConnectionSettings.

ADR-013 — Package signing & trust store¶

cosign-based signing and an explicit trust store for package delivery.

ADR-014 — OpAMP package transfer¶

Wire-level details of the package transfer extension to OpAMP frames.

ADR-015 — Multi-tenant hard isolation¶

The case for hard isolation as a first-class deployment mode (vs the soft scoping of the MVP). Implemented in ADR-036.

Phase 7 — Protocol conformance + scale-out foundation¶

ADR-016 — OpAMP WebSocket wire format¶

Adopt the 1-byte-header binary frame format from the OpAMP specification.

ADR-017 — Package rollouts¶

Same rollout state machine for binary packages as for configurations, with package-specific health gates.

ADR-018 — Multi-instance HA foundation¶

Postgres-backed leader election, session ownership, and the road to cross-instance dispatch.

Phase 8 — UX overhaul¶

ADR-019 — Design system¶

The design tokens, component library, and accessibility baseline that underpin the UI.

ADR-020 — Layout and component library¶

Top-level app shell, navigation pattern, drawer / modal conventions.

ADR-021 — Agent detail UX¶

The collapsible-panel layout of the Agent details page.

ADR-022 — Pipeline WYSIWYG editor (drawflow)¶

Choice of drawflow over React Flow / raw SVG for the visual editor.

ADR-023 — Multi-pipeline editor¶

Render multiple signal pipelines in one canvas with lane-coloured groups; connectors as inter-lane edges.

Phase 9 — Fleet UX¶

ADR-024 — Fleet UX epic 9¶

Auto-grouping, auto-apply, the flow view, and the redesigned rollouts/groups screens.

ADR-025 — Single-group invariant + UI polish¶

An agent belongs to exactly one group; the schema and UI both enforce this.

Phase 10 — Live experience¶

ADR-026 — Soft-delete groups¶

DeletedAtUtc on groups, restore action, partial-unique index for name reuse.

ADR-027 — Live update bus¶

In-process ILiveUpdateBus that powers all live-list updates in the UI.

Phase 11 — HA & scale-out¶

ADR-028 — Agent dispatch bus¶

IAgentDispatchBus abstraction with InProcess / Postgres / Redis adapters. Backbone of cross-instance dispatch.

ADR-029 — SignalR scale-out and sticky sessions¶

Sticky-session requirement per reverse proxy + the live-update backplane shape.

Phase 12 — PKI & package delivery¶

ADR-030 — CRL / OCSP¶

CRL publisher, OCSP responder, and the CDP / AIA extensions on every issued cert.

ADR-031 — Signing-key rotation¶

The Draft → Active → Trusted → Retired lifecycle of CA signing keys.

ADR-032 — HSM / KMS integration¶

ICryptoProvider abstraction; AWS KMS, Azure Key Vault, GCP KMS, PKCS#11, Vault Transit adapters.

Phase 13 — Governance depth & self-observability¶

ADR-033 — Policy expression DSL¶

Recursive-descent parser, fail-closed on a 50 ms wall-clock budget, expression cache.

ADR-034 — Audit retention¶

Hot / archive / purged tiers with leader-elected sweeper.

ADR-035 — Self-observability¶

OTel-instrumented server with the ampora_* metric namespace and W3C trace context across the dispatch backplane.

Phase 14 — Editor maturity & multi-tenant depth¶

ADR-036 — PostgreSQL Row-Level Security¶

Hard isolation at the database layer; per-tenant connection roles; SET LOCAL app.tenant_id per request.

ADR-037 — Tenant theming¶

Per-tenant brand, palette, and login wall stored in the database and rendered via TenantThemeStyle.

ADR-038 — SQL Server provider evaluation¶

Decision not to ship a SQL Server provider in the foreseeable future. PostgreSQL stays the production target.

Phase 15 — Operations feedback loop¶

ADR-039 — Drift detection¶

Drift dashboard, per-agent drift state machine, alerting hooks.

ADR-040 — Bootstrap token pools¶

Pool admin endpoints for bulk-onboarding flows; pool secret rotation; audit semantics.

Phase 16 — Authoring maturity¶

ADR-041 — Lint rule engine¶

Tenant-scoped lint rules in the same DSL as policies; severity per rule; auto-fix surface.

ADR-042 — Soft-delete extension¶

Apply soft-delete to additional entities (configurations, agent identities) for audit-trail consistency.

Phase 17 — Enterprise crypto hardening¶

ADR-043 — OCSP responder¶

Production-grade OCSP responder with stapling and per-active-key signer cert.

ADR-044 — KMS / HSM adapter matrix¶

Concrete adapters: AWS KMS, Azure Key Vault, GCP KMS, PKCS#11, HashiCorp Vault Transit.

ADR-045 — mTLS revocation enforcement¶

Real-time CRL/OCSP checks at the OpAMP listener.

ADR-046 — RFC 3161 timestamping¶

Optional cryptographic timestamping of audit events for regulated deployments.

Phase 18 — Dogfooding & distributed observability¶

ADR-047 — Ampora self-agent¶

In-process OpAMP agent that connects Ampora to its own OpAMP endpoint, useful as a smoke-test and as a fleet-UI self-view.

ADR-048 — Trace propagation across dispatch backplane¶

W3C trace context flows through dispatch envelopes and live-update events.

Phase 19 — GitOps & federation¶

ADR-049 — GitOps config sync¶

Git-source registration, polling sweep, source-aware configurations. Webhooks land in Tranche 2.

ADR-050 — Federation protocol (read-only aggregation)¶

mTLS + shared secret, manual bilateral trust, read-only aggregator surface.

ADR-051 — Cross-cluster agent handover¶

Signed handover token; identity continuity from peer to peer.

Phase 21 — Service settings & live metrics¶

ADR-054 — Service settings schema¶

Schema-validated tenant defaults and the typed settings UI.

ADR-055 — Collector own-metrics ingestion¶

POST /v1/metrics endpoint receiving the agents' own metrics for the Live metrics view.

ADR-056 — Flow live-metrics aggregation¶

Aggregation pipeline behind the Fleet flow view overlay; 30-second cache, signal-typed bucketing.