Architecture Decision Records
Architecture Decision Records (ADRs) capture important design decisions with their context, rationale, and consequences. Each ADR follows a standard format: Status, Context, Decision, Consequences, Alternatives.
ADRs retain the context of each dated decision. Historical dependency versions, examples, and performance estimates are not current runtime guarantees. Follow the guides and runtime compatibility pages for current setup; measure performance with your service and workload.
Status is Proposed, Accepted -- YYYY-MM-DD, or Accepted -- YYYY-MM-DD; revised -- YYYY-MM-DD when a later dated decision in the same ADR supersedes part of the original. The amendment rules are in the documentation style guide.
Accepted ADRs
| # | Title | Date | Summary |
|---|---|---|---|
| 001 | Native TypeScript | 2026-02-16 | Native TypeScript development + compile-before-publish with tsup |
| 003 | Package Decomposition | 2025-12-22 | Modular packages in dependency layers |
| 005 | Input Validation | 2025-12-24 | Protovalidate as primary validation mechanism |
| 006 | Resilience Patterns | 2025-12-24; revised 2026-10-08 | Resilience interceptors with cockatiel library |
| 007 | Testing Strategy | 2025-12-24 | node:test runner, 90%+ coverage target |
| 008 | Performance Benchmarking | 2025-12-24 | k6 load testing, p95 < 100ms SLA |
| 009 | Buf CLI Migration | 2026-02-06 | Buf CLI v2 for proto generation + lint |
| 014 | Method Filter Interceptor | 2026-02-07; revised 2026-10-08 | Map-based routing for unary and streaming calls; nested interceptors own streaming policy |
| 020 | Reflection Proto Sync | 2026-02-07 | 4-phase reflection-based proto synchronization |
| 022 | Protocol Extraction | 2026-02-11 | Healthcheck/Reflection as separate packages |
| 023 | Uniform Registration API | 2026-02-11 | createDefaultInterceptors(), explicit interceptor control |
| 024 | Auth/Authz Strategy | 2026-02-15; revised 2026-10-08 | @connectum/auth package with JWT, RBAC, context propagation |
| 025 | Package Versioning Strategy | 2026-02-20; revised 2026-10-08 | Two-phase plan (Fixed for rc, Hybrid after 1.0.0); Phase 2 cancelled -- all packages share one version |
| 026 | EventBus Architecture | 2026-03-07 | Proto-first EventBus with pluggable broker adapters |
| 027 | External Contracts vs EventBus | 2026-06-12 | External contracts at adapter layer; EventBus stays protobuf-only; remove sync |
| 028 | Service Catalog | 2026-06-15; revised 2026-10-09 | Declarative ctx.call/ctx.stream, defineService, sync RemoteResolver, split error model, buf codegen |
| 029 | Internal Service-to-Service Auth | 2026-06-21 | First-class internal marker distinct from public; per-service trust-source interceptor (mesh identity / issuer-bound JWKS) for worker/out-of-process callers |
| 030 | OpenAPI generation with proto-authz overlay | 2026-06-23 | Generate OpenAPI v3.1 (buf remote plugin) + overlay reading the same resolveMethodAuth the runtime uses → contract reflects authz, no drift; reference pattern in car-sharing, framework CLI deferred |
Creating a New ADR
- Create
XXX-title.mdusing the template below - Status starts as Proposed
- After review and approval, change to Accepted
- Update this index
markdown
# ADR-XXX: Title
## Status
Proposed -- YYYY-MM-DD
## Context
Why is this decision needed?
## Decision
What did we decide?
## Consequences
### Positive
### Negative
## Alternatives Considered
## Changelog