FinOps AWS Architecture
Architecture reference for the
/finops:aws-monthlycommand andrunbooksPyPI package. Documents the 9-phase execution pipeline, component relationships, and cross-validation decision tree — drawn from live-validated results against a multi-account Landing Zone.
Diagram 1: End-to-End Phase Flow
Diagram 2: Component Architecture
Diagram 3: Cross-Validation Decision Tree
Live-Validated Results
Results from a multi-account Landing Zone (2026-03-24):
| Metric | Result | Notes |
|---|---|---|
| Accounts discovered | 67 | Organizations API discovered all active accounts |
| Execution time | 2.71s | ThreadPoolExecutor pipelined CE queries |
| Persona modes | 7 working | executive, architect, sre, cfo, cto, ceo, technical |
| CFO mode | Working | NZD output, spend vs budget, savings pipeline |
| CTO mode | Working | Service breakdown, architecture cost drivers |
| SRE mode | Working | Anomaly detection, cost spike alerts |
| Cross-validation | L1 vs L3: 5.9% raw, 0% adjusted | SPP discount explains 100% of variance (see G4 gate) |
| HITL gate | Active | Triggers when report total exceeds configured threshold |
| Evidence path | tmp/cloud-infrastructure/finops/aws/ | Ephemeral; git-tracked copy in projects/<project>/finops-reports/YYYY-MM/ |
Quality Gates (G0-G8)
| Gate | Name | Criteria | Action on Fail |
|---|---|---|---|
| G0 | Wheel smoke test | pip install dist/*.whl && runbooks --version exits 0 | Block publish |
| G1 | SSO authentication | aws sts get-caller-identity succeeds for all profiles | HALT, re-authenticate |
| G2 | CE permissions | ce:GetCostAndUsage returns data, not AccessDenied | HALT, check IAM policy |
| G3 | Account discovery | Organizations API returns at least one account | Fallback to single-account mode |
| G4 | L1 vs L3 variance | Variance under 5% | FAIL cross-validation, root-cause required |
| G5 | Persona output | All 3 deliverables written (HTML + MD + stakeholder-email.md) | Retry persona_formatter |
| G6 | Visual verification | Screenshot captured, file size over 10KB | Advisory — non-blocking |
| G7 | HITL gate | Report reviewed by human when total exceeds threshold | Block distribution |
| G8 | Evidence archive | Files written to projects/<project>/finops-reports/YYYY-MM/ | Block completion claim |
Agent Coordination
| Agent | Phase | Responsibility |
|---|---|---|
| product-owner | 0A-COORD | Requirements validation, INVEST story alignment, acceptance criteria |
| cloud-architect | 0A-COORD | Architecture review, multi-account design, SCP boundary identification |
| observability-engineer | 3-4 | Cross-validation execution, DORA metrics, evidence collection |
| qa-engineer | 9 | Test coverage gates, evidence completeness, quality scoring |
| product-owner | 9 | Business value alignment, savings sourcing (Advisor recommendation IDs required) |
| cloud-architect | 9 | Architecture compliance, security posture review |
Coordination logs required at:
tmp/<project>/coordination-logs/product-owner-YYYY-MM-DD.jsontmp/<project>/coordination-logs/cloud-architect-YYYY-MM-DD.json
Two commands to generate a multi-account AWS cost report:
pip install runbooks
runbooks finops dashboard --all-profile $AWS_BILLING_PROFILE --mode cfo --month 2026-02
For the full 9-phase pipeline with HITL gate and 3-agent scoring, use the ADLC command /finops:aws-monthly. See the quickstart guide for step-by-step instructions.
AWS test data profiles are configured for read operations only. Never pass a profile with write or modify permissions to finops dashboard. The command uses Cost Explorer and Organizations APIs (read-only operations). Verify with aws sts get-caller-identity --profile $BILLING_PROFILE before running.
Anti-Patterns
| Anti-Pattern | Description | Prevention |
|---|---|---|
FINOPS_API_SSOT_MISMATCH | Using profile-scoped API totals as authoritative without stating RBAC caveat | Always run Landing Zone scope; document missing accounts |
NARROW_SEARCH_SCOPE | Querying a subset of accounts manually | Use Organizations API for auto-enumeration |
NO_ESTIMATED_COUNTS | Claiming account counts without citing the source command | Cite Organizations API output |
NATO_VIOLATION | Claiming "report generated" without evidence in tmp/ | Require cross-validation.json before completion claim |
Architecture validated against CloudOps-S1 sprint, 2026-03-24. Component versions: runbooks v1.3.4, ADLC framework v3.7.2.