0010: ADR Management and Numbering Strategy
Date: 2025-08-11
Status: Accepted
Context
As the project grows with multiple services, we need a clear and consistent strategy for managing Architectural Decision Records (ADRs). Decisions can be global (affecting the whole platform) or local (affecting a single service). The current numbering and location of ADRs is inconsistent, leading to potential confusion when referencing decisions.
Decision
We will adopt a two-level storage model with a single, global numbering sequence for all ADRs.
-
Two Locations for ADRs:
- Global ADRs: For decisions that cross service boundaries (e.g., technology choices, naming conventions, CI strategy). These will be stored in
/website/docs/03-architecture/adrs/. - Service-Specific ADRs: For decisions scoped to a single service (e.g., choice of database for
iam-service). These will be stored in/website/docs/04-services/<service-name>/adrs/.
- Global ADRs: For decisions that cross service boundaries (e.g., technology choices, naming conventions, CI strategy). These will be stored in
-
Global, Sequential Numbering:
- All ADRs, regardless of their location, will share a single, sequential, and monotonically increasing numbering system (e.g.,
0001,0002, ...0010,0011, ...). - There will be no gaps or resets in numbering. The next available number will be used for the next ADR created, whether it's global or service-specific.
- All ADRs, regardless of their location, will share a single, sequential, and monotonically increasing numbering system (e.g.,
Consequences
Positive
- Clarity and Simplicity: This system is simple to understand and follow. It provides an unambiguous way to reference any ADR across the entire project.
- Chronological Record: The global sequence creates a clear, chronological timeline of all architectural decisions.
- Clear Separation of Concerns: The two-location model makes it easy to distinguish between platform-wide and service-specific decisions.
Negative
- Non-Sequential Service ADRs: A specific service's ADRs will not be sequentially numbered within its own directory (e.g.,
iam-servicemight have ADRs0011and0013, but not0012). This is a minor trade-off for global clarity. - One-Time Refactoring: A one-time effort is required to move and renumber existing ADRs to align with this new standard.