Architecture decisions
This directory records the architecture decisions behind Package Broker 2.0. Each decision is an ADR (architecture decision record) with a status, a context, the decision and its consequences. The records are grouped by scope, one file per scope.
Index
| ADR | Title | Status | Date | Scope |
|---|---|---|---|---|
| ADR-001 | Package Broker 2.0 is a backwards-incompatible open-source rewrite, built rather than bought | Accepted | 2026-10-15 | licensing-and-contribution-terms |
| ADR-002 | One organization per deployment, with org_id kept as a constant column | Accepted | 2026-10-15 | identity-and-sessions |
| ADR-003 | Two runtimes, Cloudflare Workers and Docker on Node, behind ports and adapters | Accepted | 2026-10-15 | platform-ports-and-adapters |
| ADR-004 | Modular build composition at build time with deny-only hooks | Accepted | 2026-10-15 | plugin-api-and-composition |
| ADR-005 | Ecosystems are Composer and npm; Composer v2+ for clients and served endpoints, v1 provider protocol ingested from sources | Accepted | 2026-10-14 | registry-and-sources |
| ADR-006 | Private Packagist is not a backend; migration is a one-shot import CLI on the public API | Accepted | 2026-10-15 | registry-and-sources |
| ADR-007 | Sources at organization and project level with project precedence, digest dedup and live subscription | Accepted | 2026-10-15 | registry-and-sources |
| ADR-008 | Restricted public proxies, artifacts persisted by digest, upstream removals kept for one year | Accepted | 2026-10-15 | registry-and-sources |
| ADR-009 | Identity and access through OIDC single sign-on, grants to SSO groups or emails, configurable roles | Accepted | 2026-10-15 | identity-and-sessions |
| ADR-010 | Token kinds pat, svc and cst; PATs span projects, service tokens are CI-only and bound to one project | Accepted | 2026-10-15 | secrets-and-tokens |
| ADR-011 | Database sessions, bounded revocation, re-authentication before token creation | Accepted | 2026-10-15 | identity-and-sessions |
| ADR-012 | Secrets and cryptography with a deployment master key, HKDF, record-bound AAD and a versioned pepper | Accepted | 2026-10-15 | secrets-and-tokens |
| ADR-013 | Outbound fetch policy with denied private ranges and a Docker-only host allowlist | Accepted | 2026-10-15 | platform-ports-and-adapters |
| ADR-014 | Audit log in the application database with hash chaining; export in P1 | Accepted | 2026-10-15 | identity-and-sessions |
| ADR-015 | Every UI action in the public API; read-only MCP in the MVP; access as code through a Terraform provider | Accepted | 2026-10-15 | plugin-api-and-composition |
| ADR-016 | Project in the URL path, one Composer http-basic entry per host | Accepted | 2026-10-15 | identity-and-sessions |
| ADR-017 | GitHub integration through a GitHub App on selected repositories, webhooks, and Git smart HTTP | Accepted | 2026-10-15 | registry-and-sources |
| ADR-018 | Catalogue dates and licence-freeze foundations in the first schema | Accepted | 2026-10-15 | registry-and-sources |
| ADR-019 | Backup and recovery of application state and catalogue metadata | Accepted | 2026-10-15 | deployment-and-runtimes |
| ADR-020 | EU jurisdiction from the first deployment; residency controls in P1 | Accepted | 2026-10-14 | deployment-and-runtimes |
| ADR-022 | Rate limiting and abuse protection deferred to P1 with recorded starting values | Accepted | 2026-10-15 | deployment-and-runtimes |
| ADR-023 | Repository strategy, versioning and release process | Accepted | 2026-10-15 | release-and-versioning |
| ADR-024 | Observability through an OTLP-first port; vendors are plugins only where OTLP is not enough | Accepted | 2026-10-15 | platform-ports-and-adapters |
| ADR-025 | Plugins run in-process; an execution boundary for untrusted plugins is Nice to have | Accepted | 2026-10-15 | plugin-api-and-composition |
| ADR-026 | Contributor terms are the Developer Certificate of Origin, enforced in CI, in place of a CLA | Accepted (supersedes the ADR-001 CLA bullet) | 2026-10-16 | licensing-and-contribution-terms |
Proposing and superseding a decision
A decision is proposed in a pull request that adds a section ## ADR-0NN: <title> with the next free number to the scope file it belongs to, with Status: Proposed, <date>, and a row in the index above. Review happens in the pull request; on merge the status becomes Accepted. A decision is never rewritten after acceptance: a later record supersedes it, the superseded record gets a note naming its successor in its status line, and the successor states what it replaces.
Numbering
ADR numbers are never reused or renumbered, so the sequence has gaps.