This directory contains Architecture Decision Records (ADRs) for Meridian.
Architecture Decision Records capture important architectural decisions made in the project, along with their context and consequences. They help:
- Document the reasoning behind architectural choices
- Prevent relitigating already-decided trade-offs
- Onboard new team members with historical context
- Guide AI assistants and tools with appropriate context
We use the adr-tools CLI for managing ADRs:
# Install adr-tools (if not already installed)
brew install adr-tools
# Create a new ADR
adr new "Title of Decision"
# Link ADRs (when one supersedes another)
adr link <source> "Supersedes" <target>For more complex ADRs, use the template.md file as a starting point, which follows the MADR (Markdown Architectural Decision Records) format.
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-0001 | Record Architecture Decisions | Accepted | 2025-10-24 |
| ADR-0002 | Microservices Architecture with One Service per BIAN Domain | Accepted | 2025-10-25 | | ADR-0003 | Database Schema Migrations with Atlas | Accepted | 2025-10-25 (Revised) | | ADR-0004 | Event Schema Evolution with Protobuf and Buf | Accepted | 2025-10-25 | | ADR-0005 | Adapter Pattern for Layer Translation | Accepted | 2025-10-25 | | ADR-0006 | Tilt for Local Kubernetes Development | Accepted | 2025-10-25 | | ADR-0007 | Raw YAML over Helm for Initial Development | Accepted | 2025-10-25 |
| ADR-0008 | Defensive Testing Standards | Accepted | 2025-10-25 | | ADR-0009 | Application-Level Audit Logging | Proposed | 2025-11-04 |
| ADR-0010 | gRPC Client-Side Load Balancing with Headless Services | Accepted | 2025-11-14 | | ADR-0011 | ISO 20022 Compliance via Adapter Layer | Accepted | 2025-11-14 | | ADR-0012 | Lien-Based Fund Reservation for Payment Order Saga | Accepted | 2025-11-25 | | ADR-0013 | Universal Quantity Type System | Proposed | 2025-12-03 | | ADR-0014 | Financial Instrument Reference Data | Proposed | 2025-12-04 | | ADR-0015 | Standard Service Directory Structure | Accepted | 2025-12-06 | | ADR-0016 | Tenant ID Naming Strategy | Accepted | 2025-12-13 |
| ADR-0017 | Temporal Quality Ledger (Data Physics) | Proposed | 2025-12-14 | | ADR-0018 | Settlement & Reconciliation (Lifecycle) | Proposed | 2025-12-14 | | ADR-0019 | Resilient Client Patterns | Accepted | 2025-12-18 | | ADR-0020 | Per-Service Audit Workers | Accepted | 2025-12-20 |
| ADR-0021 | KYC/AML Verification Provider Architecture | Proposed | 2025-12-22 | | ADR-0022 | Instrument Successor Lineage | Proposed | 2025-12-28 |
| ADR-0023 | Balance Delegation to Position Keeping | Accepted | 2026-01-08 | | ADR-0024 | Internal Account Service Domain | Accepted | 2026-01-15 |
| ADR-0025 | Clearing Purpose Specialization | Accepted | 2026-01-16 |
| ADR-0026 | Canonical Ingestion Contract | Accepted | 2026-01-17 |
| ADR-0027 | Market Information Management Service Architecture | Accepted | 2026-01-19 |
| ADR-0028 | Starlark Saga Orchestration with CEL Valuation | Accepted | 2025-01-20 |
| ADR-0031 | Retain Nil Guard on PositionKeepingClient in GetBalance | Accepted | 2026-02-13 |
| ADR-0032 | Vanguard HTTP/JSON Transcoding Gateway | Accepted | 2026-02-20 |
| ADR-0033 | Event-Triggered Sagas | Accepted | 2026-03-04 |
Key architectural decisions and their dependencies:
graph LR
ADR0001[ADR-0001<br/>Record Decisions] --> ADR0002[ADR-0002<br/>Microservices per BIAN]
ADR0002 --> ADR0003[ADR-0003<br/>Database Migrations]
ADR0002 --> ADR0015[ADR-0015<br/>Service Directory]
ADR0002 --> ADR0010[ADR-0010<br/>gRPC Load Balancing]
ADR0003 --> ADR0015
ADR0004[ADR-0004<br/>Event Schema Evolution] --> ADR0005[ADR-0005<br/>Adapter Pattern]
ADR0013[ADR-0013<br/>Quantity Types] --> ADR0014[ADR-0014<br/>Reference Data]
ADR0014 --> ADR0017[ADR-0017<br/>Temporal Quality Ladder]
ADR0016[ADR-0016<br/>Tenant ID Strategy] -.influences.-> ADR0003
style ADR0002 fill:#e1f5ff
style ADR0013 fill:#e1f5ff
style ADR0017 fill:#fff4e6
Legend:
- Solid lines: Direct dependencies
- Dashed lines: Influences or relates to
- Blue background: Foundational decisions
- Orange background: Proposed/experimental
- ADR-0001 - Record Architecture Decisions
- ADR-0002 - Microservices Architecture
- ADR-0015 - Standard Service Directory Structure
- ADR-0003 - Database Schema Migrations with Atlas
- ADR-0004 - Event Schema Evolution with Protobuf and Buf
- ADR-0005 - Adapter Pattern for Layer Translation
- ADR-0009 - Application-Level Audit Logging
- ADR-0012 - Lien-Based Fund Reservation for Payment Order Saga
- ADR-0013 - Universal Quantity Type System
- ADR-0014 - Financial Instrument Reference Data (BIAN)
- ADR-0017 - Temporal Quality Ledger (Data Physics)
- ADR-0018 - Settlement & Reconciliation (Lifecycle)
- ADR-0023 - Balance Delegation to Position Keeping
- ADR-0024 - Internal Account Service Domain
- ADR-0025 - Clearing Purpose Specialization
- ADR-0026 - Canonical Ingestion Contract
- ADR-0006 - Tilt for Local Kubernetes Development
- ADR-0007 - Raw YAML over Helm for Initial Development
- ADR-0010 - gRPC Client-Side Load Balancing with Headless Services
- ADR-0011 - ISO 20022 Compliance via Adapter Layer
- ADR-0008 - Defensive Testing Standards
- ADR-0032 - Vanguard HTTP/JSON Transcoding Gateway
- ADR-0033 - Event-Triggered Sagas
- ADR-0016 - Tenant ID Naming Strategy
2025-10-25 Revision: Moved from unified schema management to separated concerns:
- Previous approach: Go structs with tags as single source of truth for database, events, and APIs
- New approach: Separate domain models, persistence entities, and event schemas with explicit adapters
- Rationale: Real-world experience showed unified approach was too rigid. Separated concerns allow:
- Database audit fields without polluting domain
- Event metadata without cluttering business logic
- Independent versioning of database, events, and APIs
- Follows industry best practices (Google, LinkedIn, Netflix, AWS)
See ADR-0004 and ADR-0005 for details.
Based on the Meridian project requirements, these ADRs may be created as implementation progresses:
- Database Choice: CockroachDB vs YugabyteDB - Distributed SQL database selection
- Idempotency Implementation - Redis-based idempotency strategy
- Test Strategy for Financial Systems - TDD approach for zero-tolerance systems
- Service Mesh vs API Gateway - Cross-cutting concerns for microservices
- Event Versioning Strategy - How to handle breaking changes in Kafka events
- Documenting Architecture Decisions - Michael Nygard
- MADR - Markdown Architectural Decision Records
- adr-tools - Command-line tools for working with ADRs
- BIAN Standards - Banking Industry Architecture Network