Skip to content

Architecture Decision Records (ADRs)

Numbered, immutable records of significant architectural decisions.

Format

Each ADR is a markdown file: adr-NNN-short-title.md

# ADR-NNN: Short Title

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** YYYY-MM-DD
**Decision Makers:** [names]

## Context
What is the issue we're seeing that motivates this decision?

## Decision
What we decided to do.

## Consequences
What becomes easier? What becomes harder? What are the trade-offs?

## Alternatives Considered
What other options did we evaluate? Why were they rejected?

Inherited ADRs (from AgenticAI-app)

Three ADRs from the AgenticAI-app repository apply directly to Finnest and have been copied here. They represent decisions made during the lead-up to Finnest that continue to apply:

ADR Title Why It Applies to Finnest
ADR-0004 Maximum Portability No AWS/Cloudflare service lock-in. Applies identically to Finnest — Elixir/Phoenix deployed via standard Docker + Kamal, PostgreSQL not Aurora, S3-compatible not DynamoDB.
ADR-0010 Australian Data Residency for AI Providers Bedrock ap-southeast-2 / Vertex australia-southeast1 only. Foundation for Finnest IRAP strategy — Bedrock Sydney for AI.
ADR-0011 Elixir/Phoenix Migration This is the genesis decision for Finnest. Documents why AgenticAI-app will be superseded by an Elixir/Phoenix platform.

Finnest ADRs (all Accepted as of 2026-04-16)

Formal records of decisions made in the brainstorming sessions, generated as part of the /architecture workflow output:

  • ADR-001-F: Adopt Elixir/Phoenix on BEAM/OTP as primary stack (formalises inherited ADR-0011)
  • ADR-002-F: Supervised Modular Monolith pattern (21 OTP apps)
  • ADR-003-F: Three-tier AI agent architecture (Conversational/Workflow/Autonomous)
  • ADR-004-F: MCP at every domain boundary
  • ADR-005-F: Event-driven cross-domain communication
  • ADR-006-F: Hexagonal ports for all external integrations
  • ADR-007-F: Three-layer IRAP architecture (AWS + Go proxy + Elixir)
  • ADR-008-F: Flutter mobile (one app, four roles)
  • ADR-009-F: KeyPay integration for award interpretation (Phase 1) — Superseded by ADR-016-F
  • ADR-010-F: Strangler Fig migration from ASG Central v2
  • ADR-011-F: Compliance auto-blocking as architectural constraint
  • ADR-012-F: Adopt all 365 competitor features, prioritise by build order
  • ADR-013-F: Engineering philosophy — follow 42 Commandments for lean AI-assisted development
  • ADR-014-F: Infrastructure reuse — co-deploy Finnest on existing AgenticAI-app hosts; Postgres alongside MySQL; Finnest subdomains in agentic-ai.au zone
  • ADR-015-F: Git worktree development flow — sibling worktrees, FINNEST_PLANNING env var, sprint-status lives in planning repo
  • ADR-016-F: Award interpretation — Phase 1 ports 10–20 active v2 Modern Awards, Phase 2 builds native engine over Fair Work Commission MAPD API (supersedes ADR-009-F)

Numbering Convention

  • Inherited ADRs (from AgenticAI-app): Keep original numbering (adr-0004, adr-0010, adr-0011)
  • Finnest-specific ADRs: Use suffix -F to distinguish (adr-001-F, adr-002-F, etc.)

This prevents collisions if AgenticAI-app creates new ADRs independently, and makes the origin clear at a glance.

Relationship to Other Documents

  • 42-COMMANDMENTS.md — Philosophical foundation. Every ADR should be consistent with the Commandments.
  • 10-GUARDRAILS.md — Enforcement matrix. ADRs define decisions; guardrails enforce them.
  • brainstorms/ — Decision discussions. ADRs formalise what brainstorms decide.