# dommetipavan26-tech/chaoshire architecture

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

- Interactive diagram: https://gitdiagram.com/dommetipavan26-tech/chaoshire
- Repository: https://github.com/dommetipavan26-tech/chaoshire

## Overview

ChaosHire is a hiring-model fairness-auditing prototype. Its main workflow accepts a demo, uploaded, or adapter-backed decision set, evaluates group fairness and controlled counterfactual stress tests, then exposes evidence and reports for review. Separate branches support candidate explanations and appeals, mitigation simulations, model training/comparison, and aggregate audit history. The excerpts show selected implementation details, but not all route bodies or subsystem calls; dashed, unevidenced links mark relationships that are documented as capabilities or strongly implied rather than verified from the excerpts.

Main entry points: [`chaoshire/app.py`](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/app.py) (HTTP API), [`chaoshire/services.py`](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py) (Audit services), [`chaoshire/web/static/chaoshire.js`](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/web/static/chaoshire.js) (Dashboard), [`chaoshire/models.py`](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/models.py) (Scoring models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_browser["Dashboard<br/>[chaoshire.js]"]
  node_api["HTTP API<br/>[app.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_audit["Audit workflow"]
  node_audit_service["Audit services<br/>[services.py]"]
  node_adapters["Decision adapters<br/>[adapters.py]"]
  node_fairness["Fairness metrics<br/>[metrics.py]"]
  node_chaos["Chaos experiments<br/>[chaos.py]"]
  node_quality["Release comparison<br/>[quality.py]"]
end

subgraph group_review["Review and governance"]
  node_explanations["Candidate explanations<br/>[explain.py]"]
  node_mitigation["Mitigation simulations<br/>[services.py]"]
  node_appeals["Appeals workflow<br/>[services.py]"]
  node_evidence["Evidence bundles<br/>[evidence.py]"]
  node_reports["HTML and PDF reports<br/>[reporting.py]"]
end

subgraph group_models["Models and data"]
  node_scoring["Scoring models<br/>[models.py]"]
  node_training["Model training<br/>[training.py]"]
  node_demo_data["Synthetic candidates<br/>[data.py]"]
end

subgraph group_operations["Persistence and operations"]
  node_state["Application state<br/>[state.py]"]
  node_history[("Audit history<br/>[repository.py]")]
  node_postgres[("PostgreSQL adapter")]
  node_webhook["Event webhook<br/>[loghook.py]"]
end

node_operator(("Operator"))

node_operator -.->|"uses"| node_browser
node_operator -.->|"invokes"| node_cli
node_operator -.->|"submits requests"| node_api
node_browser -.->|"requests audits"| node_api
node_api -.->|"dispatches"| node_audit_service
node_audit_service -.->|"loads decisions"| node_adapters
node_audit_service -.->|"calculates metrics"| node_fairness
node_audit_service -.->|"runs tests"| node_chaos
node_audit_service -.->|"builds decisions"| node_scoring
node_audit_service -.->|"stores aggregates"| node_history
node_api -.->|"requests simulation"| node_mitigation
node_api -.->|"requests explanation"| node_explanations
node_api -.->|"records appeals"| node_appeals
node_api -.->|"serves verification"| node_evidence
node_api -.->|"serves reports"| node_reports
node_quality -.->|"compares audits"| node_fairness
node_training -.->|"fits on"| node_demo_data
node_scoring -->|"scores"| node_demo_data
node_history -->|"delegates optionally"| node_postgres
node_appeals -.->|"appends appeal"| node_state
node_appeals -->|"ships event"| node_webhook
node_api -.->|"serves interface assets"| node_browser

click node_browser "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/web/static/chaoshire.js"
click node_api "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/app.py"
click node_cli "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/cli.py"
click node_audit_service "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py"
click node_adapters "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/adapters.py"
click node_fairness "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/metrics.py"
click node_chaos "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/chaos.py"
click node_quality "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/quality.py"
click node_explanations "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/explain.py"
click node_mitigation "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py"
click node_appeals "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py"
click node_evidence "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/evidence.py"
click node_reports "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/reporting.py"
click node_scoring "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/models.py"
click node_training "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/training.py"
click node_demo_data "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/data.py"
click node_state "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/state.py"
click node_history "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/repository.py"
click node_postgres "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/repository_postgres.py"
click node_webhook "https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/loghook.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_browser,node_api,node_cli toneBlue
class node_audit_service,node_adapters,node_fairness,node_chaos,node_quality toneAmber
class node_explanations,node_mitigation,node_appeals,node_evidence,node_reports toneMint
class node_scoring,node_training,node_demo_data toneRose
class node_state,node_history,node_postgres,node_webhook,node_operator toneIndigo
```

## Components

### Interfaces

- [Dashboard](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/web/static/chaoshire.js): `chaoshire/web/static/chaoshire.js`
- [HTTP API](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/app.py): `chaoshire/app.py`
- [CLI](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/cli.py): `chaoshire/cli.py`

### Audit workflow

- [Audit services](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py): `chaoshire/services.py`
- [Decision adapters](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/adapters.py): `chaoshire/adapters.py`
- [Fairness metrics](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/metrics.py): `chaoshire/metrics.py`
- [Chaos experiments](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/chaos.py): `chaoshire/chaos.py`
- [Release comparison](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/quality.py): `chaoshire/quality.py`

### Review and governance

- [Candidate explanations](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/explain.py): `chaoshire/explain.py`
- [Mitigation simulations](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py): `chaoshire/services.py`
- [Appeals workflow](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/services.py): `chaoshire/services.py`
- [Evidence bundles](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/evidence.py): `chaoshire/evidence.py`
- [HTML and PDF reports](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/reporting.py): `chaoshire/reporting.py`

### Models and data

- [Scoring models](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/models.py): `chaoshire/models.py`
- [Model training](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/training.py): `chaoshire/training.py`
- [Synthetic candidates](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/data.py): `chaoshire/data.py`

### Persistence and operations

- [Application state](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/state.py): `chaoshire/state.py`
- [Audit history](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/repository.py): `chaoshire/repository.py`
- [PostgreSQL adapter](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/repository_postgres.py): `chaoshire/repository_postgres.py`
- [Event webhook](https://github.com/dommetipavan26-tech/chaoshire/blob/main/chaoshire/loghook.py): `chaoshire/loghook.py`

### Other components

- **Operator**

## Connections

- Operator → Dashboard: uses
- Operator → CLI: invokes
- Operator → HTTP API: submits requests
- Dashboard → HTTP API: requests audits
- HTTP API → Audit services: dispatches (evidence: `chaoshire/app.py`)
- Audit services → Decision adapters: loads decisions
- Audit services → Fairness metrics: calculates metrics (evidence: `chaoshire/services.py`)
- Audit services → Chaos experiments: runs tests
- Audit services → Scoring models: builds decisions (evidence: `chaoshire/services.py`)
- Audit services → Audit history: stores aggregates (evidence: `chaoshire/services.py`)
- HTTP API → Mitigation simulations: requests simulation (evidence: `chaoshire/app.py`)
- HTTP API → Candidate explanations: requests explanation (evidence: `chaoshire/app.py`)
- HTTP API → Appeals workflow: records appeals (evidence: `chaoshire/app.py`)
- HTTP API → Evidence bundles: serves verification (evidence: `chaoshire/app.py`)
- HTTP API → HTML and PDF reports: serves reports (evidence: `chaoshire/app.py`)
- Release comparison → Fairness metrics: compares audits (evidence: `chaoshire/quality.py`)
- Model training → Synthetic candidates: fits on (evidence: `chaoshire/training.py`)
- Scoring models → Synthetic candidates: scores (evidence: `chaoshire/models.py`)
- Audit history → PostgreSQL adapter: delegates optionally (evidence: `chaoshire/repository.py`)
- Appeals workflow → Application state: appends appeal (evidence: `chaoshire/services.py`)
- Appeals workflow → Event webhook: ships event (evidence: `chaoshire/services.py`)
- HTTP API → Dashboard: serves interface assets