9. Architecture Decisions
Every significant architectural choice is recorded as an
Architecture Decision Record (ADR) in the
adrs/ directory. This section is an index grouped
by theme; click through for the full decision + context + consequences.
Stack & runtime
| ADR |
Title |
| F-001 |
Elixir / Phoenix as primary stack |
| 0011 |
Migration from Laravel to Elixir / Phoenix (inherited) |
| F-002 |
Supervised modular monolith — 21 OTP apps, one release |
| 0004 |
Maximum portability — no AWS-compute lock-in (inherited) |
AI & agents
| ADR |
Title |
| F-003 |
Three-tier AI agent architecture (conversational / workflow / autonomous) |
| F-004 |
Model Context Protocol at every domain boundary |
| 0010 |
Australian data residency for AI providers (inherited) |
Domain architecture
| ADR |
Title |
| F-005 |
Events-only cross-domain communication |
| F-006 |
Hexagonal ports for every external integration |
| F-011 |
Compliance auto-blocking at write time |
| F-012 |
Adopt all competitor features (feature-parity strategy) |
Deployment & operations
| ADR |
Title |
| F-007 |
Three-layer IRAP architecture (app + proxy + host) |
| F-014 |
Reuse infrastructure patterns from existing AgenticAI-app |
| F-015 |
Git worktree-based development flow |
Data & migration
| ADR |
Title |
| F-010 |
Strangler-Fig migration from ASG Central v2 |
| F-009 |
KeyPay integration for award interpretation (superseded — see F-016) |
| F-016 |
Native award interpretation with FWC MAPD (supersedes F-009) |
Product surface
| ADR |
Title |
| F-008 |
Flutter mobile — one app, four roles |
| F-013 |
Engineering philosophy — the 42 Commandments |
How new ADRs get added
- Significant decision surfaces in code review or design discussion
- Author proposes an ADR in
adrs/adr-NNN-F-<slug>.md using the template
- Status:
proposed until peer review
- On merge: status flips to
accepted
- If a later ADR overrides an earlier one, the later one declares
supersedes and the earlier one declares superseded-by
See the ADR README for the template and process.