# the-srirup/cauveris architecture

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

- Interactive diagram: https://gitdiagram.com/the-srirup/cauveris
- Repository: https://github.com/the-srirup/cauveris

## Overview

Cauveris investigates cyber-physical incidents from uploaded evidence through causal diagnosis, counterfactual simulation, repair verification, and reporting. The graph emphasizes the backend pipeline and its operator-facing web console, while retaining documented holographic reconstruction and deployable repair packaging. Pipeline-stage links are supported by the orchestrator excerpt; other links use the README or SOURCE INDEX references. Unsampled subsystems are shown only where the repository tree and documentation establish their role.

Main entry points: [`cauveris/api/main.py`](https://github.com/the-srirup/cauveris/blob/main/cauveris/api/main.py) (Backend API), [`cauveris/simulation/runner.py`](https://github.com/the-srirup/cauveris/blob/main/cauveris/simulation/runner.py) (Digital Twin), [`cauveris/ingestion/controller.py`](https://github.com/the-srirup/cauveris/blob/main/cauveris/ingestion/controller.py) (Bundle Intake), [`cauveris/hypothesis/generator.py`](https://github.com/the-srirup/cauveris/blob/main/cauveris/hypothesis/generator.py) (Hypothesis Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Incident Intake"]
  node_incident["Incident Record<br/>[incident.py]"]
  node_ingestion["Bundle Intake<br/>[controller.py]"]
  node_security["Intake Security<br/>[security.py]"]
  node_inventory["Artifact Inventory"]
end

subgraph group_analysis["Causal Investigation"]
  node_timeline["Evidence Timeline<br/>[builder.py]"]
  node_systemmodel["System Model<br/>[system_model.py]"]
  node_hypotheses["Hypothesis Generation<br/>[generator.py]"]
  node_modelgateway["Model Gateway<br/>[base.py]"]
  node_temporal["Temporal Analysis<br/>[integration.py]"]
  node_sandbox["Experiment Sandbox<br/>[controller.py]"]
  node_simulation["Digital Twin<br/>[runner.py]"]
end

subgraph group_repair["Repair and Verification"]
  node_patch["Patch Forge<br/>[generator.py]"]
  node_verifier["Patch Verification<br/>[engine.py]"]
  node_packaging["Repair Packaging<br/>[api_router.py]"]
  node_report["Investigation Report<br/>[generator.py]"]
end

subgraph group_platform["Operator Platform"]
  node_web["Web Console<br/>[page.tsx]"]
  node_api["Backend API<br/>[main.py]"]
  node_holographic["Holographic Views<br/>[page.tsx]"]
  node_persistence[("Pipeline Persistence<br/>[persistence.py]")]
end

node_operator(("Operator"))

node_operator -->|"investigates incidents"| node_web
node_web -.->|"requests investigation"| node_api
node_api -->|"accepts bundles"| node_ingestion
node_api -->|"creates records"| node_incident
node_ingestion -->|"validates input"| node_security
node_ingestion -->|"inventories artifacts"| node_inventory
node_api -->|"starts pipeline"| node_timeline
node_api -->|"starts pipeline"| node_hypotheses
node_api -->|"starts pipeline"| node_simulation
node_api -->|"starts pipeline"| node_patch
node_api -->|"starts pipeline"| node_sandbox
node_api -->|"starts pipeline"| node_verifier
node_api -->|"starts pipeline"| node_report
node_timeline -.->|"provides evidence"| node_systemmodel
node_hypotheses -->|"derives causes"| node_systemmodel
node_hypotheses -->|"requests reasoning"| node_modelgateway
node_api -->|"runs analysis"| node_temporal
node_sandbox -->|"tests interventions"| node_simulation
node_patch -->|"uses simulation mapping"| node_simulation
node_verifier -->|"checks outcomes"| node_simulation
node_api -->|"serves repair archives"| node_packaging
node_api -.->|"serves investigation views"| node_holographic
node_api -->|"persists pipeline state"| node_persistence
node_api -.->|"returns findings"| node_report

click node_web "https://github.com/the-srirup/cauveris/blob/main/apps/web/app/page.tsx"
click node_api "https://github.com/the-srirup/cauveris/blob/main/cauveris/api/main.py"
click node_incident "https://github.com/the-srirup/cauveris/blob/main/cauveris/schemas/incident.py"
click node_ingestion "https://github.com/the-srirup/cauveris/blob/main/cauveris/ingestion/controller.py"
click node_security "https://github.com/the-srirup/cauveris/blob/main/cauveris/security.py"
click node_inventory "https://github.com/the-srirup/cauveris/blob/main/cauveris/inventory/artifact_inventory.py"
click node_timeline "https://github.com/the-srirup/cauveris/blob/main/cauveris/timeline/builder.py"
click node_systemmodel "https://github.com/the-srirup/cauveris/blob/main/cauveris/analysis/system_model.py"
click node_hypotheses "https://github.com/the-srirup/cauveris/blob/main/cauveris/hypothesis/generator.py"
click node_modelgateway "https://github.com/the-srirup/cauveris/blob/main/cauveris/model_gateway/base.py"
click node_temporal "https://github.com/the-srirup/cauveris/blob/main/cauveris/temporal/integration.py"
click node_sandbox "https://github.com/the-srirup/cauveris/blob/main/cauveris/sandbox/controller.py"
click node_simulation "https://github.com/the-srirup/cauveris/blob/main/cauveris/simulation/runner.py"
click node_patch "https://github.com/the-srirup/cauveris/blob/main/cauveris/patch/generator.py"
click node_verifier "https://github.com/the-srirup/cauveris/blob/main/cauveris/verifier/engine.py"
click node_packaging "https://github.com/the-srirup/cauveris/blob/main/cauveris/packaging/api_router.py"
click node_report "https://github.com/the-srirup/cauveris/blob/main/cauveris/report/generator.py"
click node_holographic "https://github.com/the-srirup/cauveris/blob/main/apps/web/app/holographic-reconstruction/page.tsx"
click node_persistence "https://github.com/the-srirup/cauveris/blob/main/cauveris/state_machine/persistence.py"

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_incident,node_ingestion,node_security,node_inventory toneBlue
class node_timeline,node_systemmodel,node_hypotheses,node_modelgateway,node_temporal,node_sandbox,node_simulation toneAmber
class node_patch,node_verifier,node_packaging,node_report toneMint
class node_web,node_api,node_holographic,node_persistence toneRose
class node_operator toneIndigo
```

## Components

### Incident Intake

- [Incident Record](https://github.com/the-srirup/cauveris/blob/main/cauveris/schemas/incident.py): `cauveris/schemas/incident.py`
- [Bundle Intake](https://github.com/the-srirup/cauveris/blob/main/cauveris/ingestion/controller.py): `cauveris/ingestion/controller.py`
- [Intake Security](https://github.com/the-srirup/cauveris/blob/main/cauveris/security.py): `cauveris/security.py`
- [Artifact Inventory](https://github.com/the-srirup/cauveris/blob/main/cauveris/inventory/artifact_inventory.py): `cauveris/inventory/artifact_inventory.py`

### Causal Investigation

- [Evidence Timeline](https://github.com/the-srirup/cauveris/blob/main/cauveris/timeline/builder.py): `cauveris/timeline/builder.py`
- [System Model](https://github.com/the-srirup/cauveris/blob/main/cauveris/analysis/system_model.py): `cauveris/analysis/system_model.py`
- [Hypothesis Generation](https://github.com/the-srirup/cauveris/blob/main/cauveris/hypothesis/generator.py): `cauveris/hypothesis/generator.py`
- [Model Gateway](https://github.com/the-srirup/cauveris/blob/main/cauveris/model_gateway/base.py): `cauveris/model_gateway/base.py`
- [Temporal Analysis](https://github.com/the-srirup/cauveris/blob/main/cauveris/temporal/integration.py): `cauveris/temporal/integration.py`
- [Experiment Sandbox](https://github.com/the-srirup/cauveris/blob/main/cauveris/sandbox/controller.py): `cauveris/sandbox/controller.py`
- [Digital Twin](https://github.com/the-srirup/cauveris/blob/main/cauveris/simulation/runner.py): `cauveris/simulation/runner.py`

### Repair and Verification

- [Patch Forge](https://github.com/the-srirup/cauveris/blob/main/cauveris/patch/generator.py): `cauveris/patch/generator.py`
- [Patch Verification](https://github.com/the-srirup/cauveris/blob/main/cauveris/verifier/engine.py): `cauveris/verifier/engine.py`
- [Repair Packaging](https://github.com/the-srirup/cauveris/blob/main/cauveris/packaging/api_router.py): `cauveris/packaging/api_router.py`
- [Investigation Report](https://github.com/the-srirup/cauveris/blob/main/cauveris/report/generator.py): `cauveris/report/generator.py`

### Operator Platform

- [Web Console](https://github.com/the-srirup/cauveris/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Backend API](https://github.com/the-srirup/cauveris/blob/main/cauveris/api/main.py): `cauveris/api/main.py`
- [Holographic Views](https://github.com/the-srirup/cauveris/blob/main/apps/web/app/holographic-reconstruction/page.tsx): `apps/web/app/holographic-reconstruction/page.tsx`
- [Pipeline Persistence](https://github.com/the-srirup/cauveris/blob/main/cauveris/state_machine/persistence.py): `cauveris/state_machine/persistence.py`

### Other components

- **Operator**

## Connections

- Operator → Web Console: investigates incidents (evidence: `README.md`)
- Web Console → Backend API: requests investigation
- Backend API → Bundle Intake: accepts bundles (evidence: `cauveris/api/main.py`)
- Backend API → Incident Record: creates records (evidence: `cauveris/api/main.py`)
- Bundle Intake → Intake Security: validates input (evidence: `cauveris/ingestion/controller.py`)
- Bundle Intake → Artifact Inventory: inventories artifacts (evidence: `cauveris/ingestion/controller.py`)
- Backend API → Evidence Timeline: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Hypothesis Generation: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Digital Twin: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Patch Forge: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Experiment Sandbox: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Patch Verification: starts pipeline (evidence: `cauveris/api/main.py`)
- Backend API → Investigation Report: starts pipeline (evidence: `cauveris/api/main.py`)
- Evidence Timeline → System Model: provides evidence
- Hypothesis Generation → System Model: derives causes (evidence: `cauveris/hypothesis/generator.py`)
- Hypothesis Generation → Model Gateway: requests reasoning (evidence: `cauveris/hypothesis/generator.py`)
- Backend API → Temporal Analysis: runs analysis (evidence: `cauveris/api/main.py`)
- Experiment Sandbox → Digital Twin: tests interventions (evidence: `cauveris/sandbox/controller.py`)
- Patch Forge → Digital Twin: uses simulation mapping (evidence: `cauveris/patch/generator.py`)
- Patch Verification → Digital Twin: checks outcomes (evidence: `cauveris/verifier/engine.py`)
- Backend API → Repair Packaging: serves repair archives (evidence: `cauveris/packaging/api_router.py`)
- Backend API → Holographic Views: serves investigation views
- Backend API → Pipeline Persistence: persists pipeline state (evidence: `cauveris/api/main.py`)
- Backend API → Investigation Report: returns findings (evidence: `cauveris/api/main.py`)