← Internal hub
internal · decision log

Architecture Decision Records (ADR)

Why we made the big architectural choices. Source: docs/adr/. Update when a decision is reversed or superseded.
ADRs are immutable once accepted. To change direction, write a new ADR that supersedes the old one (don't edit the original). Status options: Proposed · Accepted · Superseded by ADR-NNNN · Deprecated.

Accepted decisions

Accepted ADR 0001 — Deployment tier model

2026-05-23 · sourced from docs/adr/0001-deployment-tier-model.md

Context: EU mid-market customers split sharply on data sovereignty preferences. Pure SaaS works for some; others require their identity + secret data to never leave their network.

Decision: Three tiers — pure SaaS (control plane in vendor cloud), tier-3 hybrid (agent in customer VPC + CP in vendor), full on-premise (everything in customer K8s). Default: tier-3.

Why not full SaaS only: lose ~40% of EU procurement TAM. Many CISOs reject any identity data in third-party SaaS.

Why not full on-premise only: ~3-month implementation cost is uneconomical for SMB. Lose < €1M ACV deals.

Tradeoff accepted: tier-3 doubles connector complexity (in_process + agent + tunnel modes per engine).

Accepted — Phase 1 done ADR 0002 — Connector protocol versioning

2026-05-23 · sourced from docs/adr/0002-connector-protocol-versioning.md

Context: Tier-3 agents run in customer infra at versions older than the control plane. Wire protocol between CP and agent must be stable across deploys.

Decision: Versioned Pydantic Request/Response envelopes (app/domain/connector_protocol/v1.py) with a ConnectorDispatcher wrapper. Don't break wire-shape without a version bump. Phase 1 = v1 schemas + dispatcher. Phase 2 (deferred) = explicit version negotiation on agent connect.

Why not gRPC + proto3: heavier client; harder for customer ops to debug. JSON over HTTPS wins on diagnosability.

Why version 1 first instead of running unversioned: agents in production now; breaking change later is hard.

Accepted — design only ADR 0003 — PII classification + tier-3 data-split roadmap

2026-05-23 · sourced from docs/adr/0003-pii-classification.md

Context: Under tier-3 + GDPR, the goal is for PII to remain in customer VPC. Today the CP holds full identity rows (full name, email, manager_email). A future evolution: CP holds only opaque IDs + non-PII attributes; agent dereferences PII on demand.

Decision: Classify every ORM column as PII / non-PII / pseudonym. Phase 1 (done): tagging. Phase 2 (deferred): tier-3 storage split. Phase 3 (future): customer-side encryption at rest for PII columns.

Why not implement Phase 2 now: would block IVIP-roadmap. Defer until first regulated customer demands it contractually.

Risk accepted: extra DPA work to defend the "PII in vendor CP" position. Counter-arg: ALL EU SaaS competitors store the same PII in their own SaaS (Saviynt EIC, SailPoint IdentityNow, etc.) — we're not worse.

Proposed / under discussion

No proposed ADRs at the moment. Open a new one in docs/adr/ via PR.

Writing a new ADR

Use the template (docs/adr/README.md has it). Key sections:

  1. Context — what's the problem? Why does it need a decision now?
  2. Decision — what did we pick?
  3. Alternatives considered — at least 2-3, with reasons rejected
  4. Tradeoff accepted — what are we giving up by choosing this?
  5. Consequences — how will the system look 6 months from now?

Number sequentially (0004-...), date in ISO format, status Accepted only after merge. Don't change accepted ADRs — write a superseding one.