Architecture Decision Records
Overview
Section titled “Overview”This document records the major architecture decisions for the Functorium framework. Each decision follows the MADR v4.0 template, structuring the context, alternatives considered, rationale for the chosen option, and expected consequences.
Why ADR
Section titled “Why ADR”When architecture decisions are scattered across code and commit messages, it becomes increasingly difficult to trace “why was this done this way?” over time. ADRs preserve the context at the time of each decision, allowing new team members to quickly understand the rationale when joining or when revisiting existing decisions.
Status Legend
Section titled “Status Legend”| Status | Description |
|---|---|
accepted | Adopted and currently in effect |
proposed | Proposed but not yet agreed upon |
deprecated | No longer valid |
superseded | Replaced by a newer ADR |
ADR List
Section titled “ADR List”| Number | Title | Status |
|---|---|---|
| ADR-0001 | Foundation - Represent Failures with Fin Types Instead of Exceptions | accepted |
| ADR-0002 | Foundation - Adopt LanguageExt as the Functional Base Library | accepted |
| ADR-0003 | Domain - CQRS Read/Write Path Separation | accepted |
| ADR-0004 | Domain - Ulid-Based Entity ID | accepted |
| ADR-0005 | Domain - UnionValueObject State Machine | accepted |
| ADR-0006 | Domain - Specification + Expression Tree | accepted |
| ADR-0007 | Domain - ID-Only Cross-Aggregate References | accepted |
| ADR-0008 | Domain - Domain Service Pure vs Repository | accepted |
| ADR-0009 | Domain - Value Object Class/Record Dual Hierarchy | accepted |
| ADR-0010 | Domain - Error Code Sealed Record Hierarchy | accepted |
| ADR-0011 | Application - Pipeline Execution Order Design | accepted |
| ADR-0012 | Application - FinResponse Pipeline Type Constraints | accepted |
| ADR-0013 | Application - Validation Order: Normalize Then MaxLength | accepted |
| ADR-0014 | Application - Explicit Transaction Support | accepted |
| ADR-0015 | Adapter - Observable Port Source Generator | accepted |
| ADR-0016 | Adapter - Persistence Suffix Naming Pattern | accepted |
| ADR-0017 | Observability - ctx.* Pillar Targeting Defaults | accepted |
| ADR-0018 | Observability - Automatic 3-Type Error Classification | accepted |
| ADR-0019 | Observability - Field Naming: snake_case + dot | accepted |
| ADR-0020 | Event - DomainEvent Publisher Simplification | accepted |
| ADR-0021 | Event - DomainEvent Tracing Correlation IDs | accepted |
| ADR-0022 | Testing - Architecture Test Suite Framework | accepted |