# gudekarn/thousand-cuts architecture

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

- Interactive diagram: https://gitdiagram.com/gudekarn/thousand-cuts
- Repository: https://github.com/gudekarn/thousand-cuts

## Overview

Death by a Thousand Cuts is a reproducible ML robustness experiment engine with a read-only FastAPI results API and React dashboard. Its core workflow applies frozen single or compound training-noise configurations to datasets, evaluates classical models across severity levels, derives robustness and breaking-point metrics, and exposes results for exploration. The README documents the experiment methodology and major analysis capabilities; sampled code confirms frontend routing, visualization data hooks, and config metadata assembly. Most engine, results-route, and storage internals were not sampled, so uncertain runtime links are omitted or marked unverified.

Main entry points: [`backend/app/engine/runner.py`](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/runner.py) (Experiment Runner), [`frontend/src/App.tsx`](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/App.tsx) (Routed Dashboard), [`backend/app/api/config_routes.py`](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/api/config_routes.py) (Config Endpoint), [`frontend/src/pages/Visualizations.tsx`](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/Visualizations.tsx) (Visualizations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment Engine"]
  node_datasets["Datasets and Splits<br/>[data.py]"]
  node_noise["Noise Injection<br/>[noise.py]"]
  node_pipelines["Model Pipelines<br/>[pipelines.py]"]
  node_runner["Experiment Runner<br/>[runner.py]"]
  node_levels["Frozen Levels<br/>[levels.py]"]
  node_config["Experiment Config<br/>[config.py]"]
end

subgraph group_backend["API and Results"]
  node_result_store[("Official Results<br/>[csv_store.py]")]
  node_manifest["Run Manifest<br/>[manifest.py]"]
  node_paths["Result Paths<br/>[paths.py]"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_config_api["Config Endpoint<br/>[config_routes.py]"]
  node_results_api["Results Endpoints<br/>[results_routes.py]"]
  node_schemas["API Schemas<br/>[config.py]"]
end

subgraph group_frontend["Dashboard"]
  node_app["Routed Dashboard<br/>[App.tsx]"]
  node_setup_page["Experiment Setup"]
  node_results_page["Results Dashboard"]
  node_comparison_page["Model Comparison"]
  node_overview_page["Overview<br/>[Overview.tsx]"]
  node_details_page["Experiment Details"]
  node_visualizations["Visualizations<br/>[Visualizations.tsx]"]
  node_hooks["Data Hooks<br/>[useApi.ts]"]
  node_client["API Client<br/>[client.ts]"]
  node_charts["Chart Components"]
end

subgraph group_analysis["Robustness Analysis"]
  node_metrics["Evaluation Metrics<br/>[metrics.py]"]
  node_analysis["Robustness Analysis<br/>[analysis.py]"]
  node_figures["Figure Data<br/>[figures.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"explores results"| node_app
node_datasets -.->|"supplies splits"| node_runner
node_noise -.->|"perturbs training data"| node_runner
node_levels -.->|"sets severity"| node_runner
node_config -.->|"configures runs"| node_runner
node_runner -.->|"evaluates models"| node_pipelines
node_runner -.->|"records scores"| node_metrics
node_runner -.->|"writes results"| node_result_store
node_runner -->|"records provenance"| node_manifest
node_metrics -.->|"derives robustness"| node_analysis
node_analysis -.->|"prepares analysis views"| node_figures
node_api_app -.->|"serves routes"| node_config_api
node_config_api -->|"reads metadata"| node_config
node_config_api -->|"loads levels"| node_levels
node_config_api -->|"returns response"| node_schemas
node_config_api -->|"checks stages"| node_paths
node_results_api -.->|"reads results"| node_result_store
node_app -->|"routes to"| node_overview_page
node_app -->|"routes to"| node_setup_page
node_app -->|"routes to"| node_results_page
node_app -->|"routes to"| node_comparison_page
node_app -->|"routes to"| node_details_page
node_app -->|"routes to"| node_visualizations
node_visualizations -->|"requests summaries"| node_hooks
node_hooks -->|"calls API"| node_client
node_client -.->|"requests results"| node_results_api
node_client -.->|"requests config"| node_config_api
node_visualizations -->|"renders charts"| node_charts

click node_datasets "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/data.py"
click node_noise "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/noise.py"
click node_pipelines "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/pipelines.py"
click node_runner "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/runner.py"
click node_levels "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/core/levels.py"
click node_config "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/core/config.py"
click node_metrics "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/metrics.py"
click node_analysis "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/analysis.py"
click node_figures "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/figures.py"
click node_result_store "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/csv_store.py"
click node_manifest "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/manifest.py"
click node_paths "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/paths.py"
click node_api_app "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/main.py"
click node_config_api "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/api/config_routes.py"
click node_results_api "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/api/results_routes.py"
click node_schemas "https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/schemas/config.py"
click node_app "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/App.tsx"
click node_setup_page "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ExperimentSetup.tsx"
click node_results_page "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ResultsDashboard.tsx"
click node_comparison_page "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ModelComparison.tsx"
click node_overview_page "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/Overview.tsx"
click node_details_page "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ExperimentDetails.tsx"
click node_visualizations "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/Visualizations.tsx"
click node_hooks "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/hooks/useApi.ts"
click node_client "https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/api/client.ts"
click node_charts "https://github.com/gudekarn/thousand-cuts/tree/main/frontend/src/components/charts"

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_datasets,node_noise,node_pipelines,node_runner,node_levels,node_config toneBlue
class node_result_store,node_manifest,node_paths,node_api_app,node_config_api,node_results_api,node_schemas toneAmber
class node_app,node_setup_page,node_results_page,node_comparison_page,node_overview_page,node_details_page,node_visualizations,node_hooks,node_client,node_charts toneMint
class node_metrics,node_analysis,node_figures toneRose
class node_researcher toneIndigo
```

## Components

### Experiment Engine

- [Datasets and Splits](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/data.py): `backend/app/engine/data.py`
- [Noise Injection](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/noise.py): `backend/app/engine/noise.py`
- [Model Pipelines](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/pipelines.py): `backend/app/engine/pipelines.py`
- [Experiment Runner](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/runner.py): `backend/app/engine/runner.py`
- [Frozen Levels](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/core/levels.py): `backend/app/core/levels.py`
- [Experiment Config](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### API and Results

- [Official Results](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/csv_store.py): `backend/app/storage/csv_store.py`
- [Run Manifest](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/manifest.py): `backend/app/storage/manifest.py`
- [Result Paths](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/storage/paths.py): `backend/app/storage/paths.py`
- [FastAPI App](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/main.py): `backend/app/main.py`
- [Config Endpoint](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/api/config_routes.py): `backend/app/api/config_routes.py`
- [Results Endpoints](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/api/results_routes.py): `backend/app/api/results_routes.py`
- [API Schemas](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/schemas/config.py): `backend/app/schemas/config.py`

### Dashboard

- [Routed Dashboard](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Experiment Setup](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ExperimentSetup.tsx): `frontend/src/pages/ExperimentSetup.tsx`
- [Results Dashboard](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ResultsDashboard.tsx): `frontend/src/pages/ResultsDashboard.tsx`
- [Model Comparison](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ModelComparison.tsx): `frontend/src/pages/ModelComparison.tsx`
- [Overview](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/Overview.tsx): `frontend/src/pages/Overview.tsx`
- [Experiment Details](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/ExperimentDetails.tsx): `frontend/src/pages/ExperimentDetails.tsx`
- [Visualizations](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/pages/Visualizations.tsx): `frontend/src/pages/Visualizations.tsx`
- [Data Hooks](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/hooks/useApi.ts): `frontend/src/hooks/useApi.ts`
- [API Client](https://github.com/gudekarn/thousand-cuts/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Chart Components](https://github.com/gudekarn/thousand-cuts/tree/main/frontend/src/components/charts): `frontend/src/components/charts`

### Robustness Analysis

- [Evaluation Metrics](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/metrics.py): `backend/app/engine/metrics.py`
- [Robustness Analysis](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/analysis.py): `backend/app/engine/analysis.py`
- [Figure Data](https://github.com/gudekarn/thousand-cuts/blob/main/backend/app/engine/figures.py): `backend/app/engine/figures.py`

### Other components

- **Researcher**

## Connections

- Researcher → Routed Dashboard: explores results (evidence: `README.md`)
- Datasets and Splits → Experiment Runner: supplies splits
- Noise Injection → Experiment Runner: perturbs training data
- Frozen Levels → Experiment Runner: sets severity
- Experiment Config → Experiment Runner: configures runs
- Experiment Runner → Model Pipelines: evaluates models
- Experiment Runner → Evaluation Metrics: records scores
- Experiment Runner → Official Results: writes results
- Experiment Runner → Run Manifest: records provenance (evidence: `README.md`)
- Evaluation Metrics → Robustness Analysis: derives robustness
- Robustness Analysis → Figure Data: prepares analysis views
- FastAPI App → Config Endpoint: serves routes
- Config Endpoint → Experiment Config: reads metadata (evidence: `backend/app/api/config_routes.py`)
- Config Endpoint → Frozen Levels: loads levels (evidence: `backend/app/api/config_routes.py`)
- Config Endpoint → API Schemas: returns response (evidence: `backend/app/api/config_routes.py`)
- Config Endpoint → Result Paths: checks stages (evidence: `backend/app/api/config_routes.py`)
- Results Endpoints → Official Results: reads results
- Routed Dashboard → Overview: routes to (evidence: `frontend/src/App.tsx`)
- Routed Dashboard → Experiment Setup: routes to (evidence: `frontend/src/App.tsx`)
- Routed Dashboard → Results Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Routed Dashboard → Model Comparison: routes to (evidence: `frontend/src/App.tsx`)
- Routed Dashboard → Experiment Details: routes to (evidence: `frontend/src/App.tsx`)
- Routed Dashboard → Visualizations: routes to (evidence: `frontend/src/App.tsx`)
- Visualizations → Data Hooks: requests summaries (evidence: `frontend/src/pages/Visualizations.tsx`)
- Data Hooks → API Client: calls API (evidence: `frontend/src/hooks/useApi.ts`)
- API Client → Results Endpoints: requests results
- API Client → Config Endpoint: requests config
- Visualizations → Chart Components: renders charts (evidence: `frontend/src/pages/Visualizations.tsx`)
