Architectural Decision Records (ADRs)
This directory contains the Architectural Decision Records for the Citadel project. ADRs are the primary mechanism for proposing, discussing, and recording significant architectural decisions.
ADR Process & Numbering
As defined in ADR-0014: ADR Management and Numbering Strategy, all ADRs in this project follow a global, sequential numbering system, regardless of whether they are platform-wide or service-specific.
Next ADR Number: 0055
Last ADR Number Used: 0054
To create a new ADR:
- Copy the
0000-template.mdto a new file. - Assign it the next available number (e.g.,
0052-my-new-decision.md). - Place it in the appropriate directory (
/website/docs/03-architecture/adrs/for global ADRs, or/website/docs/04-services/<service-name>/adrs/for service-specific ADRs). - Update the "Last ADR Number Used" and "Next ADR Number" in this file.
- Submit a Merge Request for review.
Master ADR Index
This table provides a complete, chronologically ordered list of all architectural decisions made for the project.
Global ADRs
These decisions affect the entire platform or establish cross-cutting conventions.
| Number | Title |
|---|---|
| 0001 | Standardized Service Layout |
| 0002 | Swappable Infrastructure via Adapters |
| 0003 | Standardized Frontend Layout |
| 0005 | Frontend Build and Configuration Strategy |
| 0012 | Third-Party Integration Strategy |
| 0013 | Project Rename to Citadel |
| 0014 | ADR Management and Numbering Strategy |
| 0015 | Contextual Shell Chrome Strategy |
| 0017 | Multiple Account Management Strategy |
| 0019 | API Gateway RBAC via External Authorization |
| 0021 | Contribution and Proposal Management Strategy |
| 0023 | IAM Service as a Policy and Authorization Claims Engine |
| 0024 | IAM Service as a Policy and Claims Enrichment Engine |
| 0052 | IAM Service Consolidation |
| 0054 | Service-Defined Role and Attribute Management |
Service-Specific ADRs
These decisions are scoped to a single service.
| Number | Title | Service |
|---|---|---|
| 0007 | IAM Service Persistence Strategy | iam-service |
| 0008 | IAM Service S2S Authentication | iam-service |
| 0009 | IAM Multi-Tenancy Mapping Strategy | iam-service |
| 0010 | API Gateway Technology and Configuration Strategy | api-gateway |
| 0011 | API Gateway Security Policy | api-gateway |
| 0025 | Tenant Switching Flow | iam-service |
| 0026 | Customization Definition Languages | customization-service |
| 0027 | Customization Service Scope and Boundaries | customization-service |
| 0028 | Schema Ownership and Scopes | customization-service |
| 0029 | Policy Service Architecture | policy-service |
| 0030 | Policy Scoping | policy-service |
| 0031 | Engine-Agnostic Policy Data Model | policy-service |
| 0032 | Data Propagation Strategy | policy-service |
| 0033 | Permission Naming Convention | policy-service |
| 0034 | ReBAC Engine Selection | permissions-service |
| 0035 | Permissions Schema vs Data Management | permissions-service |
| 0036 | Permissions Multi-Tenancy and Scoping Strategy | permissions-service |
| 0039 | Workflow Engine Selection | workflow-service |
| 0040 | Workflow Core Concepts and Patterns | workflow-service |
| 0041 | Workflow Security and Context Propagation | workflow-service |
| 0042 | Workflow Error Handling and Compensation Strategy | workflow-service |
| 0043 | Workflow Scheduled and Recurring Tasks | workflow-service |
| 0047 | Dynamic Workflow Execution via Interpreter | workflow-service |
| 0048 | Swappable Storage Adapters | book-keeper |
| 0049 | Event-Driven Integration Pattern | book-keeper |
| 0050 | Event Sourcing for Audit Trail | book-keeper |
| 0051 | Anti-Corruption Layer for External Events | book-keeper |
| 0053 | S2S-First IAM Architecture | iam-service |
Archived ADRs
These decisions have been superseded by newer ADRs or relate to archived services. Kept for historical context.
| Number | Title | Service/Context | Reason |
|---|---|---|---|
| 0004 | Angular Change Detection Strategy | Global | Superseded by framework evolution |
| 0006 | OAuth2 Client Strategy | iam-service | Superseded by ADR-0023, ADR-0024 |
| 0016 | User Impersonation Strategy | Global | Feature deferred |
| 0018 | API Gateway RBAC Strategy | api-gateway | Superseded by ADR-0019 |
| 0020 | IAM Service Facade Philosophy | iam-service | Superseded by ADR-0024 |
| 0022 | IAM Service OIDC State Storage Strategy | iam-service | No longer managing OIDC state |
| 0037 | Onboarding Adapter Architecture | onboarding-service | Service archived (replaced by workflow pattern) |
| 0038 | Onboarding Pipeline to Workflow Mapping | onboarding-service | Service archived (replaced by workflow pattern) |
| 0044 | Tenant State Machine | tenant-lifecycle-service | Service consolidated into iam-service (ADR-0052) |
| 0045 | Swappable Payment Providers | payment-gateway-service | Service removed (not core platform yet) |
| 0046 | Payment Gateway Secure Credential Management | payment-gateway-service | Service removed (not core platform yet) |
| 0026 | Customization Definition Languages | customization-service | Service consolidated into iam-service (ADR-0052) |
| 0027 | Customization Service Scope and Boundaries | customization-service | Service consolidated into iam-service (ADR-0052) |
| 0028 | Schema Ownership and Scopes | customization-service | Service consolidated into iam-service (ADR-0052) |
| 0029 | Policy Service Architecture | policy-service | Service consolidated into iam-service (ADR-0052) |
| 0030 | Policy Scoping | policy-service | Service consolidated into iam-service (ADR-0052) |
| 0031 | Engine-Agnostic Policy Data Model | policy-service | Service consolidated into iam-service (ADR-0052) |
| 0032 | Data Propagation Strategy | policy-service | Service consolidated into iam-service (ADR-0052) |
| 0033 | Permission Naming Convention | policy-service | Service consolidated into iam-service (ADR-0052) |