# fable-for-four/chimera architecture

> Architecture diagram of the GitHub repository fable-for-four/chimera, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fable-for-four/chimera
- Repository: https://github.com/fable-for-four/chimera

## Overview

Chimera is a simulated-log investigation product: analysts start an investigation, inspect an explainable attack chain and cited evidence, review uncertainty and stress-test results, then approve recommended responses. The Python engine reconstructs the case; FastAPI serves case data and records approvals, while the Next.js client presents the investigation. The README documents the generator-to-engine and browser-to-API flows. Some subsystem links below rely on that documentation or the SOURCE INDEX; unsampled implementations are represented at their existing directory paths.

Main entry points: [`engine/run.py`](https://github.com/fable-for-four/chimera/blob/main/engine/run.py) (Investigation runner), [`web/lib/state.tsx`](https://github.com/fable-for-four/chimera/blob/main/web/lib/state.tsx) (Client state and API), [`api/main.py`](https://github.com/fable-for-four/chimera/blob/main/api/main.py) (FastAPI service), [`engine/sort.py`](https://github.com/fable-for-four/chimera/blob/main/engine/sort.py) (Time ordering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Scenario generation"]
  node_generator["Scenario generator<br/>[scenario.py]"]
  node_noise["Normal log noise<br/>[noise.py]"]
end

subgraph group_investigation["Investigation engine"]
  node_engine_run["Investigation runner<br/>[run.py]"]
  node_intake["Event intake<br/>[intake.py]"]
  node_sort["Time ordering<br/>[sort.py]"]
  node_profile["Behavior profiles<br/>[profile.py]"]
  node_score["Deviation scoring<br/>[score.py]"]
  node_link["Signal linking<br/>[link.py]"]
  node_challenge["Chain challenge<br/>[challenge.py]"]
  node_verdict["Verdict and impact<br/>[verdict.py]"]
  node_report["Cited report<br/>[report.py]"]
  node_stress["Stress testing<br/>[stress.py]"]
  node_truth["Truth evaluation<br/>[truth.py]"]
end

subgraph group_service["API and persistence"]
  node_parser["Log file parser<br/>[parse_logs.py]"]
  node_api["FastAPI service<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Accounts and approvals<br/>[db.py]")]
  node_casefiles["Generated case files<br/>[case_files.py]"]
  node_email["Verification email<br/>[email.py]"]
end

subgraph group_client["Investigation interface"]
  node_state["Client state and API<br/>[state.tsx]"]
  node_start["Start investigation<br/>[Start.tsx]"]
  node_overview["Case overview<br/>[Overview.tsx]"]
  node_attackgraph["Attack graph<br/>[AttackGraph.tsx]"]
  node_evidence["Evidence views<br/>[EvidenceDrawer.tsx]"]
  node_eventlog["Forensic event log<br/>[EvidenceLog.tsx]"]
  node_incidentreport["Incident report<br/>[IncidentReport.tsx]"]
  node_stresslab["Stress lab<br/>[StressLab.tsx]"]
  node_admin["User administration<br/>[page.tsx]"]
  node_login["Sign-in and signup<br/>[page.tsx]"]
  node_types["Data contracts<br/>[types.ts]"]
end

node_analyst(("Analyst"))
node_browser(("Browser"))

node_generator -->|"adds normal events"| node_noise
node_generator -->|"produces scenario data"| node_engine_run
node_engine_run -->|"runs stage"| node_intake
node_engine_run -->|"runs stage"| node_sort
node_engine_run -->|"runs stage"| node_profile
node_engine_run -->|"runs stage"| node_score
node_engine_run -->|"runs stage"| node_link
node_engine_run -->|"runs stage"| node_challenge
node_engine_run -->|"runs stage"| node_verdict
node_engine_run -->|"builds report"| node_report
node_engine_run -->|"runs stress tests"| node_stress
node_engine_run -->|"evaluates truth"| node_truth
node_link -->|"parses event times"| node_sort
node_score -->|"uses time parsing"| node_sort
node_stress -->|"uses time parsing"| node_sort
node_verdict -->|"uses linked chain"| node_link
node_verdict -->|"uses time parsing"| node_sort
node_report -->|"uses challenge results"| node_challenge
node_report -->|"uses linked chain"| node_link
node_engine_run -->|"writes case outputs"| node_casefiles
node_parser -.->|"normalizes log files"| node_intake
node_browser -->|"signs in"| node_login
node_login -->|"auth requests"| node_api
node_browser -->|"starts investigation"| node_start
node_start -->|"requests run"| node_state
node_state -->|"calls same-origin API"| node_api
node_api -->|"runs investigation"| node_engine_run
node_api -->|"reads case outputs"| node_casefiles
node_api -->|"checks identity"| node_auth
node_api -->|"stores approvals"| node_database
node_auth -->|"queries users"| node_database
node_api -->|"sends verification"| node_email
node_state -->|"supplies case state"| node_overview
node_state -->|"supplies case state"| node_attackgraph
node_state -->|"supplies evidence"| node_evidence
node_state -->|"supplies events"| node_eventlog
node_state -->|"supplies report"| node_incidentreport
node_state -->|"loads stress cases"| node_stresslab
node_overview -.->|"shows attack path"| node_attackgraph
node_overview -.->|"selects evidence"| node_evidence
node_overview -->|"approves response"| node_api
node_admin -->|"manages users"| node_api
node_state -->|"uses contracts"| node_types
node_browser -.->|"reviews report"| node_incidentreport

click node_generator "https://github.com/fable-for-four/chimera/blob/main/generator/scenario.py"
click node_noise "https://github.com/fable-for-four/chimera/blob/main/generator/noise.py"
click node_engine_run "https://github.com/fable-for-four/chimera/blob/main/engine/run.py"
click node_intake "https://github.com/fable-for-four/chimera/blob/main/engine/intake.py"
click node_sort "https://github.com/fable-for-four/chimera/blob/main/engine/sort.py"
click node_profile "https://github.com/fable-for-four/chimera/blob/main/engine/profile.py"
click node_score "https://github.com/fable-for-four/chimera/blob/main/engine/score.py"
click node_link "https://github.com/fable-for-four/chimera/blob/main/engine/link.py"
click node_challenge "https://github.com/fable-for-four/chimera/blob/main/engine/challenge.py"
click node_verdict "https://github.com/fable-for-four/chimera/blob/main/engine/verdict.py"
click node_report "https://github.com/fable-for-four/chimera/blob/main/engine/report.py"
click node_stress "https://github.com/fable-for-four/chimera/blob/main/engine/stress.py"
click node_truth "https://github.com/fable-for-four/chimera/blob/main/engine/truth.py"
click node_parser "https://github.com/fable-for-four/chimera/blob/main/api/parse_logs.py"
click node_api "https://github.com/fable-for-four/chimera/blob/main/api/main.py"
click node_auth "https://github.com/fable-for-four/chimera/blob/main/api/auth.py"
click node_database "https://github.com/fable-for-four/chimera/blob/main/api/db.py"
click node_casefiles "https://github.com/fable-for-four/chimera/blob/main/api/case_files.py"
click node_email "https://github.com/fable-for-four/chimera/blob/main/api/email.py"
click node_state "https://github.com/fable-for-four/chimera/blob/main/web/lib/state.tsx"
click node_start "https://github.com/fable-for-four/chimera/blob/main/web/components/Start.tsx"
click node_overview "https://github.com/fable-for-four/chimera/blob/main/web/components/Overview.tsx"
click node_attackgraph "https://github.com/fable-for-four/chimera/blob/main/web/components/AttackGraph.tsx"
click node_evidence "https://github.com/fable-for-four/chimera/blob/main/web/components/EvidenceDrawer.tsx"
click node_eventlog "https://github.com/fable-for-four/chimera/blob/main/web/components/EvidenceLog.tsx"
click node_incidentreport "https://github.com/fable-for-four/chimera/blob/main/web/components/IncidentReport.tsx"
click node_stresslab "https://github.com/fable-for-four/chimera/blob/main/web/components/StressLab.tsx"
click node_admin "https://github.com/fable-for-four/chimera/blob/main/web/app/admin/page.tsx"
click node_login "https://github.com/fable-for-four/chimera/blob/main/web/app/login/page.tsx"
click node_types "https://github.com/fable-for-four/chimera/blob/main/web/lib/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generator,node_noise,node_browser toneBlue
class node_engine_run,node_intake,node_sort,node_profile,node_score,node_link,node_challenge,node_verdict,node_report,node_stress,node_truth toneAmber
class node_parser,node_api,node_auth,node_database,node_casefiles,node_email toneMint
class node_state,node_start,node_overview,node_attackgraph,node_evidence,node_eventlog,node_incidentreport,node_stresslab,node_admin,node_login,node_types toneRose
class node_analyst toneIndigo
```

## Components

### Scenario generation

- [Scenario generator](https://github.com/fable-for-four/chimera/blob/main/generator/scenario.py): `generator/scenario.py`
- [Normal log noise](https://github.com/fable-for-four/chimera/blob/main/generator/noise.py): `generator/noise.py`

### Investigation engine

- [Investigation runner](https://github.com/fable-for-four/chimera/blob/main/engine/run.py): `engine/run.py`
- [Event intake](https://github.com/fable-for-four/chimera/blob/main/engine/intake.py): `engine/intake.py`
- [Time ordering](https://github.com/fable-for-four/chimera/blob/main/engine/sort.py): `engine/sort.py`
- [Behavior profiles](https://github.com/fable-for-four/chimera/blob/main/engine/profile.py): `engine/profile.py`
- [Deviation scoring](https://github.com/fable-for-four/chimera/blob/main/engine/score.py): `engine/score.py`
- [Signal linking](https://github.com/fable-for-four/chimera/blob/main/engine/link.py): `engine/link.py`
- [Chain challenge](https://github.com/fable-for-four/chimera/blob/main/engine/challenge.py): `engine/challenge.py`
- [Verdict and impact](https://github.com/fable-for-four/chimera/blob/main/engine/verdict.py): `engine/verdict.py`
- [Cited report](https://github.com/fable-for-four/chimera/blob/main/engine/report.py): `engine/report.py`
- [Stress testing](https://github.com/fable-for-four/chimera/blob/main/engine/stress.py): `engine/stress.py`
- [Truth evaluation](https://github.com/fable-for-four/chimera/blob/main/engine/truth.py): `engine/truth.py`

### API and persistence

- [Log file parser](https://github.com/fable-for-four/chimera/blob/main/api/parse_logs.py): `api/parse_logs.py`
- [FastAPI service](https://github.com/fable-for-four/chimera/blob/main/api/main.py): `api/main.py`
- [Authentication](https://github.com/fable-for-four/chimera/blob/main/api/auth.py): `api/auth.py`
- [Accounts and approvals](https://github.com/fable-for-four/chimera/blob/main/api/db.py): `api/db.py`
- [Generated case files](https://github.com/fable-for-four/chimera/blob/main/api/case_files.py): `api/case_files.py`
- [Verification email](https://github.com/fable-for-four/chimera/blob/main/api/email.py): `api/email.py`

### Investigation interface

- [Client state and API](https://github.com/fable-for-four/chimera/blob/main/web/lib/state.tsx): `web/lib/state.tsx`
- [Start investigation](https://github.com/fable-for-four/chimera/blob/main/web/components/Start.tsx): `web/components/Start.tsx`
- [Case overview](https://github.com/fable-for-four/chimera/blob/main/web/components/Overview.tsx): `web/components/Overview.tsx`
- [Attack graph](https://github.com/fable-for-four/chimera/blob/main/web/components/AttackGraph.tsx): `web/components/AttackGraph.tsx`
- [Evidence views](https://github.com/fable-for-four/chimera/blob/main/web/components/EvidenceDrawer.tsx): `web/components/EvidenceDrawer.tsx`
- [Forensic event log](https://github.com/fable-for-four/chimera/blob/main/web/components/EvidenceLog.tsx): `web/components/EvidenceLog.tsx`
- [Incident report](https://github.com/fable-for-four/chimera/blob/main/web/components/IncidentReport.tsx): `web/components/IncidentReport.tsx`
- [Stress lab](https://github.com/fable-for-four/chimera/blob/main/web/components/StressLab.tsx): `web/components/StressLab.tsx`
- [User administration](https://github.com/fable-for-four/chimera/blob/main/web/app/admin/page.tsx): `web/app/admin/page.tsx`
- [Sign-in and signup](https://github.com/fable-for-four/chimera/blob/main/web/app/login/page.tsx): `web/app/login/page.tsx`
- [Data contracts](https://github.com/fable-for-four/chimera/blob/main/web/lib/types.ts): `web/lib/types.ts`

### Other components

- **Analyst**
- **Browser**

## Connections

- Scenario generator → Normal log noise: adds normal events (evidence: `generator/noise.py`)
- Scenario generator → Investigation runner: produces scenario data (evidence: `README.md`)
- Investigation runner → Event intake: runs stage (evidence: `engine/run.py`)
- Investigation runner → Time ordering: runs stage (evidence: `engine/run.py`)
- Investigation runner → Behavior profiles: runs stage (evidence: `engine/run.py`)
- Investigation runner → Deviation scoring: runs stage (evidence: `engine/run.py`)
- Investigation runner → Signal linking: runs stage (evidence: `engine/run.py`)
- Investigation runner → Chain challenge: runs stage (evidence: `engine/run.py`)
- Investigation runner → Verdict and impact: runs stage (evidence: `engine/run.py`)
- Investigation runner → Cited report: builds report (evidence: `engine/run.py`)
- Investigation runner → Stress testing: runs stress tests (evidence: `engine/run.py`)
- Investigation runner → Truth evaluation: evaluates truth (evidence: `engine/run.py`)
- Signal linking → Time ordering: parses event times (evidence: `engine/link.py`)
- Deviation scoring → Time ordering: uses time parsing (evidence: `engine/score.py`)
- Stress testing → Time ordering: uses time parsing (evidence: `engine/stress.py`)
- Verdict and impact → Signal linking: uses linked chain (evidence: `engine/verdict.py`)
- Verdict and impact → Time ordering: uses time parsing (evidence: `engine/verdict.py`)
- Cited report → Chain challenge: uses challenge results (evidence: `engine/report.py`)
- Cited report → Signal linking: uses linked chain (evidence: `engine/report.py`)
- Investigation runner → Generated case files: writes case outputs (evidence: `README.md`)
- Log file parser → Event intake: normalizes log files
- Browser → Sign-in and signup: signs in (evidence: `web/app/login/page.tsx`)
- Sign-in and signup → FastAPI service: auth requests (evidence: `web/app/login/page.tsx`)
- Browser → Start investigation: starts investigation
- Start investigation → Client state and API: requests run (evidence: `web/lib/state.tsx`)
- Client state and API → FastAPI service: calls same-origin API
- FastAPI service → Investigation runner: runs investigation (evidence: `README.md`)
- FastAPI service → Generated case files: reads case outputs (evidence: `api/main.py`)
- FastAPI service → Authentication: checks identity (evidence: `api/main.py`)
- FastAPI service → Accounts and approvals: stores approvals (evidence: `api/main.py`)
- Authentication → Accounts and approvals: queries users (evidence: `api/auth.py`)
- FastAPI service → Verification email: sends verification (evidence: `api/main.py`)
- Client state and API → Case overview: supplies case state (evidence: `web/components/Overview.tsx`)
- Client state and API → Attack graph: supplies case state (evidence: `web/components/AttackGraph.tsx`)
- Client state and API → Evidence views: supplies evidence (evidence: `web/components/EvidenceDrawer.tsx`)
- Client state and API → Forensic event log: supplies events (evidence: `web/components/EvidenceLog.tsx`)
- Client state and API → Incident report: supplies report (evidence: `web/components/IncidentReport.tsx`)
- Client state and API → Stress lab: loads stress cases (evidence: `web/components/StressLab.tsx`)
- Case overview → Attack graph: shows attack path
- Case overview → Evidence views: selects evidence
- Case overview → FastAPI service: approves response
- User administration → FastAPI service: manages users (evidence: `api/main.py`)
- Client state and API → Data contracts: uses contracts (evidence: `web/lib/state.tsx`)
- Browser → Incident report: reviews report