Skip to content

Architecture

Formal architecture documents for Finnest (commercial: Hexis), generated via the BMAD /architecture workflow on 2026-04-16.

Status

Complete. Architecture document + 4 companion docs + 13 new ADRs.

Documents

Main

  • architecture.md — Primary architecture document (~74 KB, 12 parts covering drivers, high-level arch, architectural invariants, tech stack, components, data, API, NFRs, security, scalability, reliability, dev/deploy, traceability, trade-offs)

Companions (domain-specific deep dives)

  • agents.md — AI agent infrastructure: three-tier pattern (Conversational / Workflow / Autonomous), MCP server design, local-first routing, memory system (L1/L2/L3), budget management, tool definitions
  • irap.md — IRAP deployment: three-layer architecture (AWS + Go proxy + Elixir), feature matrix vs commercial, Go proxy responsibilities, access control, CI/CD separation, assessment strategy and timeline, cost model
  • data.md — Data model: 22 schemas / ~195 tables, event store with hash chain, agents schema, tenant enforcement via Finnest.Repo.prepare_query, PII encryption via Cloak, five canonical data flow paths, Strangler Fig migration mechanics
  • mobile.md — Flutter mobile: one app / four roles, BLoC architecture, SQLite offline event queue, conflict resolution rules, agent chat as home screen, IRAP flavor specifics

New ADRs (all in ../adrs/)

Formalise decisions already settled in brainstorms:

  • ADR-001-F — Elixir/Phoenix as primary stack
  • ADR-002-F — Supervised Modular Monolith (21 OTP apps)
  • ADR-003-F — Three-tier AI agent architecture
  • ADR-004-F — MCP at every domain boundary
  • ADR-005-F — Event-driven cross-domain communication
  • ADR-006-F — Hexagonal ports for external integrations
  • ADR-007-F — Three-layer IRAP architecture
  • ADR-008-F — Flutter mobile (one app, four roles)
  • ADR-009-F — KeyPay integration for award interpretation (phased)
  • 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 (42 Commandments)
  • ADR-014-F — Infrastructure reuse strategy — co-deploy Finnest on existing AgenticAI-app hosts

Inherited ADRs

Unchanged — applied as-is:

  • ADR-0004 — Maximum portability
  • ADR-0010 — AU data residency for AI providers
  • ADR-0011 — Elixir/Phoenix migration (the genesis ADR for Finnest)

Reading Order

New contributors, in order:

  1. architecture.md — Executive Summary, Architectural Drivers, System Overview, Architectural Invariants (first ~40% of the document)
  2. ../42-COMMANDMENTS.md — philosophical foundation (skim — you'll re-read frequently)
  3. ../10-GUARDRAILS.md — enforcement reference (skim — CI will enforce most of these for you)
  4. The inherited ADRs (ADR-0004, ADR-0010, ADR-0011)
  5. ADR-001-F through ADR-013-F — Finnest-specific decisions
  6. Companion docs in the domain you'll be working on:
  7. Building agent infrastructure → agents.md
  8. Building mobile → mobile.md
  9. Building IRAP features → irap.md
  10. Schema + migration work → data.md

Working on a specific feature:

  1. Skim architecture.md Part 4 (System Components) to find the OTP app that owns the feature
  2. Read the relevant brainstorm (brainstorms 01-12)
  3. Consult the relevant companion doc if the feature crosses agents / IRAP / data / mobile concerns

How to Amend

Architecture doc + companions are living documents. Guidelines:

  1. Small clarifications — edit directly, bump revision history in architecture.md
  2. New architectural pattern — requires a new ADR; reference it in architecture.md
  3. Contradicting an ADR — supersede it (new ADR with "Supersedes" field); update architecture.md
  4. New guardrail needed — amend 10-GUARDRAILS.md; add ADR if it represents an architectural choice
  5. Scope expansion — add to research/08-master-feature-inventory.md (NOT to architecture) and ensure the existing OTP app structure accommodates it

Validation Checklist

All complete:

  • Validated against every commandment it references (Parts 1-12 cite Commandments throughout)
  • Every architectural component has at least one enforcing guardrail (AR-* / CQ-* / SE-* / IR-* / AI-* / DA-*)
  • All 12 brainstorm decisions are honoured (explicitly cited, not re-opened)
  • IRAP constraints from brainstorm-06 are visible in the architecture (Part 8 + full irap.md)
  • Multi-industry design from brainstorm-05 is represented (Part 5 + data.md)
  • Agent design from brainstorm-03 is the central nervous system, not an add-on (Part 4 + full agents.md)
  • ADRs created for decisions not yet formalised (13 new ADRs)
  • Output explicitly states which architectural patterns are INHERITED from AgenticAI-app vs NEW to Finnest (Part 12 "Inherited vs New" table)

Workflow Status

  • Analysis phase: complete (12 brainstorms, 9 research docs, 365 features audited)
  • Planning phase: complete (architecture document delivered)
  • Solutioning phase: in progress (architecture is the solutioning output)
  • Next: /sprint-planning to break Phase 0–1 into stories for the 44-week roadmap

See ../_bmad-output/bmm-workflow-status.yaml for canonical workflow state.

Open Issues (from architecture.md Part 12)

# Item Phase Owner
OI-01 IRAP pre-assessment meeting 0 Gautham
OI-02 KeyPay API validation 0 Gautham
OI-03 External MySQL validation in Elixir production 0 wk 1 Gautham
OI-04 DVS gateway provider selection 2 TBD
OI-05 Runbooks (8 scenarios) written 3 Ops lead
OI-06 Capacity re-plan after first client 2 Gautham
OI-07 Voice provider sovereignty re-eval 2027 Product
OI-08 LiveView Native re-evaluation 2027 Mobile lead
OI-09 Native award engine scope 2 kickoff Payroll lead
OI-10 GraphQL for partners As-needed —
OI-11 LocalLLMProvider trigger eval 3 Ops + Product
OI-12 Prompt-cache hit rate dashboard 1 Infra