System Architecture
The AFCS architecture enforces a strict separation between hidden canonical state and participant-visible projections, using deterministic state transitions driven by structured participant actions.
Component Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ Participant Layer │
│ │
│ ┌──────────────────────┐ ┌──────────────────────────┐ │
│ │ Web UI (Browser) │ │ AI Agent (API Client) │ │
│ │ React + TypeScript │ │ REST / JSON over HTTP │ │
│ └──────────┬───────────┘ └─────────────┬────────────┘ │
│ │ │ │
└─────────────┼───────────────────────────────────┼───────────────────┘
│ HTTP (TLS) │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ API Server (FastAPI) │
│ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Session │ │ Action │ │Stakeholder │ │ Evaluation │ │
│ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │
│ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │ │ │
└────────┼──────────────┼───────────────┼─────────────────┼──────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Domain Service Layer │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Simulation Engine│ │Stakeholder Engine│ │ Evaluation Engine│ │
│ │ • State Machine │ │ • Policy Layer │ │ • Validators │ │
│ │ • Action Registry│ │ • Language Render│ │ • Hard Constraint│ │
│ │ • Event Model │ │ • Fact Bounds │ │ • Scoring Engine │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ Model Gateway │ │ Case Repository │ │ │
│ │ • Provider-Agnos.│ │ • Case Schema │ │ │
│ │ • Mock Provider │ │ • Validation │ │ │
│ └──────────────────┘ └──────────────────┘ │ │
└────────────────────────┬───────────────────────────────┼───────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Data Layer │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL Database │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │
│ │ │ Cases │ │ Sessions │ │ Events │ │ Participants │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Evalua- │ │ Reports │ │ Stake- │ │ │
│ │ │ tions │ │ │ │ holders │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘Trust Boundaries
The system enforces five numbered trust boundaries that define data access constraints.
| # | Boundary | Mechanism | Risk |
|---|---|---|---|
| B1 | Participant ↔ Hidden State | CanonicalState → VisibleState projection. Only projected state reaches API. | Leaking hidden state keys in API response |
| B2 | Participant ↔ Stakeholder | Policy layer controls facts. Post-generation constraint validation. | LLM ignores policy constraints |
| B3 | Participant ↔ Evaluation | Score endpoint returns 403 until session is completed/evaluated. | In-progress score leakage biases behavior |
| B4 | Evaluator ↔ Participant Data | RBAC + session-level ACL. Audit logging of all evaluator access. | Cross-session or unauthorized PII access |
| B5 | Agent ↔ Environment | Bounded synthetic tools. No unrestricted shells, no arbitrary credentials. | Agent escaping simulation sandbox |
Stakeholder Engine
The hybrid architecture is the core innovation: deterministic policy controls facts, permissions, and approvals. The LLM only renders language.
Participant Action
│
▼
┌─────────────────────────────┐
│ Policy Engine │
│ (Deterministic - pure) │
│ │
│ • Rule matching │
│ • Fact availability check │
│ • Response classification │ ← LLM has NO control here
│ • Constraint generation │
└──────────┬──────────────────┘
│ ResponseDirective
▼
┌─────────────────────────────┐
│ Language Renderer │
│ (LLM - bounded) │
│ │
│ • System prompt + policy │
│ • Persona-aware tone │
│ • Response generation │
│ • Post-generation validate │ ← disclosed ⊆ allowed
└──────────┬──────────────────┘
│
▼
Stakeholder ResponseEvent Model
Every state change flows through the append-only simulation_events table. State is materialized separately for efficient reads. Replay is trivial: replay events in sequence order.
simulation_events (
id UUID PRIMARY KEY,
session_id UUID NOT NULL,
sequence_number BIGINT NOT NULL,
event_type TEXT NOT NULL,
actor_type TEXT NOT NULL, -- 'participant', 'system', 'stakeholder'
actor_id TEXT,
payload JSONB NOT NULL,
pre_state_hash TEXT NOT NULL, -- SHA-256 of state before action
post_state_hash TEXT NOT NULL, -- SHA-256 of state after action
created_at TIMESTAMPTZ NOT NULL,
UNIQUE(session_id, sequence_number)
)Evaluation Model
Six independent dimensions, each scored 0.0-1.0. No single number claims to represent complete FDE capability.
| Dimension | Weight | What it Measures |
|---|---|---|
| Discovery | 30% | Quality of information gathering, root cause identification |
| Technical Reasoning | 20% | Architecture choice, feasibility analysis, constraint awareness |
| Evaluation Quality | 10% | Self-evaluation, alternative consideration, risk identification |
| Delivery | 25% | Communication clarity, actionable recommendations |
| Governance | 10% | Security, compliance, regulatory awareness |
| Operational Sustainability | 5% | Maintainability, scalability, ownership, cost awareness |
Technology Stack
| Layer | Technology |
|---|---|
| Frontend | React + TypeScript + Vite + TanStack Query |
| Backend API | Python 3.12 + FastAPI + Pydantic v2 |
| Database | PostgreSQL + SQLAlchemy 2.0 + Alembic |
| Domain Logic | Pure Pydantic v2 models (zero framework deps) |
| Simulation Engine | Deterministic pure functions + append-only event stream |
| Stakeholder Engine | Hybrid: policy (deterministic) + LLM (language only) |
| Model Gateway | Provider-agnostic Protocol + mock provider for dev |
| CI/CD | GitHub Actions: ruff + pytest + Docker Compose |