# mrphilo420/burnwatch architecture

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

- Interactive diagram: https://gitdiagram.com/mrphilo420/burnwatch
- Repository: https://github.com/mrphilo420/burnwatch

## Overview

Burnwatch screens submitted text against human-calibrated conformal rules and returns an alert, non-alert, or referral for human review. The web path accepts text or uploaded documents, prepares text, obtains calibration/scoring results, and records privacy-preserving job summaries; the CLI exposes the same screening core. Separate from serving, the empirical study evaluates constructions across corpora. The graph also includes the legacy perturbation experiment pipeline. Some source excerpts are partial, so edges are limited to relationships shown in excerpts, the SOURCE INDEX, or README.

Main entry points: [`app.py`](https://github.com/mrphilo420/burnwatch/blob/main/app.py) (Flask interface), [`conformal.py`](https://github.com/mrphilo420/burnwatch/blob/main/conformal.py) (Conformal screening), [`data.py`](https://github.com/mrphilo420/burnwatch/blob/main/data.py) (Corpus access), [`study.py`](https://github.com/mrphilo420/burnwatch/blob/main/study.py) (Empirical study)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Flask interface<br/>[app.py]"]
  node_ui["Screening UI<br/>[index.html]"]
  node_extraction["File extraction<br/>[docutils.py]"]
  node_audit[("Decision audit<br/>[audit.py]")]
end

subgraph group_screen["Screening core"]
  node_screening["Conformal screening<br/>[conformal.py]"]
  node_calibration["Calibration bundles<br/>[conformal.py]"]
  node_markers["Style markers<br/>[slop.py]"]
end

subgraph group_evaluation["Data and evaluation"]
  node_corpora["Corpus access<br/>[data.py]"]
  node_customdata["Custom datasets<br/>[custom_datasets.py]"]
  node_study["Empirical study<br/>[study.py]"]
end

subgraph group_research["Research pipeline"]
  node_perturbation["Perturbation experiments<br/>[run.py]"]
end

node_user(("Reviewer"))
node_dataset_service["Dataset sources"]

node_user -->|"submits text"| node_ui
node_ui -->|"uses"| node_webapp
node_webapp -->|"extracts uploads"| node_extraction
node_webapp -->|"screens text"| node_screening
node_webapp -->|"loads bundle"| node_calibration
node_webapp -->|"records jobs"| node_audit
node_screening -->|"uses bundle"| node_calibration
node_screening -->|"uses detector"| node_markers
node_screening -->|"loads data"| node_corpora
node_study -->|"evaluates constructions"| node_screening
node_study -->|"loads records"| node_corpora
node_corpora -->|"fetches datasets"| node_dataset_service
node_perturbation -->|"loads datasets"| node_customdata

click node_webapp "https://github.com/mrphilo420/burnwatch/blob/main/app.py"
click node_ui "https://github.com/mrphilo420/burnwatch/blob/main/templates/index.html"
click node_extraction "https://github.com/mrphilo420/burnwatch/blob/main/docutils.py"
click node_audit "https://github.com/mrphilo420/burnwatch/blob/main/audit.py"
click node_screening "https://github.com/mrphilo420/burnwatch/blob/main/conformal.py"
click node_calibration "https://github.com/mrphilo420/burnwatch/blob/main/conformal.py"
click node_markers "https://github.com/mrphilo420/burnwatch/blob/main/slop.py"
click node_corpora "https://github.com/mrphilo420/burnwatch/blob/main/data.py"
click node_customdata "https://github.com/mrphilo420/burnwatch/blob/main/custom_datasets.py"
click node_study "https://github.com/mrphilo420/burnwatch/blob/main/study.py"
click node_perturbation "https://github.com/mrphilo420/burnwatch/blob/main/run.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_webapp,node_ui,node_extraction,node_audit,node_user toneBlue
class node_screening,node_calibration,node_markers toneAmber
class node_corpora,node_customdata,node_study toneMint
class node_perturbation toneRose
class node_dataset_service toneIndigo
```

## Components

### Web application

- [Flask interface](https://github.com/mrphilo420/burnwatch/blob/main/app.py): `app.py`
- [Screening UI](https://github.com/mrphilo420/burnwatch/blob/main/templates/index.html): `templates/index.html`
- [File extraction](https://github.com/mrphilo420/burnwatch/blob/main/docutils.py): `docutils.py`
- [Decision audit](https://github.com/mrphilo420/burnwatch/blob/main/audit.py): `audit.py`

### Screening core

- [Conformal screening](https://github.com/mrphilo420/burnwatch/blob/main/conformal.py): `conformal.py`
- [Calibration bundles](https://github.com/mrphilo420/burnwatch/blob/main/conformal.py): `conformal.py`
- [Style markers](https://github.com/mrphilo420/burnwatch/blob/main/slop.py): `slop.py`

### Data and evaluation

- [Corpus access](https://github.com/mrphilo420/burnwatch/blob/main/data.py): `data.py`
- [Custom datasets](https://github.com/mrphilo420/burnwatch/blob/main/custom_datasets.py): `custom_datasets.py`
- [Empirical study](https://github.com/mrphilo420/burnwatch/blob/main/study.py): `study.py`

### Research pipeline

- [Perturbation experiments](https://github.com/mrphilo420/burnwatch/blob/main/run.py): `run.py`

### Other components

- **Reviewer**
- **Dataset sources**

## Connections

- Reviewer → Screening UI: submits text (evidence: `README.md`)
- Screening UI → Flask interface: uses (evidence: `README.md`)
- Flask interface → File extraction: extracts uploads (evidence: `app.py`)
- Flask interface → Conformal screening: screens text (evidence: `app.py`)
- Flask interface → Calibration bundles: loads bundle (evidence: `app.py`)
- Flask interface → Decision audit: records jobs (evidence: `app.py`)
- Conformal screening → Calibration bundles: uses bundle (evidence: `conformal.py`)
- Conformal screening → Style markers: uses detector (evidence: `conformal.py`)
- Conformal screening → Corpus access: loads data (evidence: `conformal.py`)
- Empirical study → Conformal screening: evaluates constructions (evidence: `study.py`)
- Empirical study → Corpus access: loads records (evidence: `study.py`)
- Corpus access → Dataset sources: fetches datasets (evidence: `data.py`)
- Perturbation experiments → Custom datasets: loads datasets (evidence: `run.py`)
