Architecture

AFA separates governance, execution, and access control into three planes that never cross roles.

Tri-plane design

+---------------------------+      +---------------------------+
|       CONTROL PLANE       |      |        DATA PLANE         |
|                           |      |                           |
|  Gate engine (9 gates)    |      |  tree-sitter AST parsing  |
|  Anti-gaming controls     |      |  4 analysis agents        |
|  Supply chain sentinel    |      |  Chroma vector store      |
|  Parameter governance     |      |  Enhancement generator    |
|  KPI drift guard          |      |  Language specialists     |
|  SHA-256 audit chain      |      |                           |
+---------------------------+      +---------------------------+
         |                                    |
         |     Never generates code           |  Never makes governance
         |                                    |  decisions
         +----------------+-------------------+
                          |
                   Enhancement Loop
                          |
         +---------------------------+
         |        AUTH PLANE         |
         |                          |
         |  Unkey API key auth      |
         |  Per-tier rate limiting   |
         |  Feature gating           |
         |  Billing / Stripe        |
         |  Portal service auth     |
         +---------------------------+
              Never evaluates gates
              Never generates code

Control plane

The control plane runs the gate engine, anti-gaming controls, supply chain sentinel, and audit trail. It evaluates whether a proposed change is safe and worthwhile. It never generates code.

Key components:

• Gate engine (src/afa/gates/engine.py) -- evaluates all 9 quantitative gates
• Anti-gaming (src/afa/gates/anti_gaming.py) -- 4 detectors: dead code, edit locality, AST distance, generated code
• Audit trail (src/afa/store/audit.py) -- append-only PostgreSQL database with SHA-256 hash chain, verified on startup
• Parameter governance (src/afa/core/config.py) -- frozen/stable/canary governance bands enforced at load time
• Kill switch (src/afa/core/killswitch.py) -- SIGTERM/SIGINT triggers graceful shutdown

Data plane

The data plane runs code analysis, enhancement generation, and LLM interactions. It never makes governance decisions.

Key components:

• AST parsing -- tree-sitter for Python, TypeScript, Go, Java, Rust
• Analysis pipeline (src/afa/analysis/pipeline.py) -- orchestrates 4 agents (security, performance, maintainability, documentation)
• Enhancement generator (src/afa/enhancement/generator.py) -- LLM-powered candidate creation
• Input sanitizer (src/afa/analysis/sanitizer.py) -- all LLM inputs sanitized, injection blocked, secrets redacted

Provider chain

AFA is model-agnostic. Each provider has a primary model and a fallback chain:

Fallback behavior:

• Transient errors (network, rate limit 429, server 5xx) — retry with next model in chain, then cross-provider fallback
• Permanent errors (401 auth, 403 permission, 400 bad request, 422 unprocessable) — wrapped as PermanentProviderError and re-raised immediately, no cascade. See ADR-004.

Select a provider via CLI flag (--provider gemini) or in .afa.yaml:

model:
  provider: anthropic
  model: claude-sonnet-4-6
  fallback_chain:
    - openai/gpt-5.4
    - gemini/gemini-3-flash-preview

Enhancement loop

Per-function convergent loop:

Analyze --> Generate Candidates --> Gate Check (9 gates) --> Commit or Redesign

Termination conditions

Worktree isolation

Enhancements are applied on isolated branches via git worktree. Changes never touch your working tree or main branch directly.

main (your branch, untouched)
  |
  +-- afa/enhance-utils-process-data (worktree branch)
  +-- afa/enhance-auth-verify-token (worktree branch)

Distribution surfaces

Production infrastructure

Deployed on GCP Cloud Run (us-central1):

Cloud Run (project: undercurrent-production)
  ├── afa-core (port 8080, 512Mi, 0-4 instances)
  │     REST API, billing, enhancement engine
  ├── afa-github-app (port 3000, 512Mi, 0-2 instances)
  │     GitHub App webhook receiver
  └── Neon PostgreSQL (serverless, us-east-1)
        All 5 stores: audit, metering, customers, lifecycle, calibration

Optional integrations

AFA is a standalone product. These integrations are optional:

Dependency direction: AFA depends on AEGIS (never reverse).