# afshazareen/clarity_project architecture

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

- Interactive diagram: https://gitdiagram.com/afshazareen/clarity_project
- Repository: https://github.com/afshazareen/clarity_project

## Overview

CLARITY analyzes political question-and-answer pairs, returning a clarity class and a finer-grained evasion technique. Users submit pairs through the browser UI to a Flask API; the API validates requests and delegates inference to a predictor that uses trained models when available and heuristic fallbacks otherwise. A separate training workflow loads QEvasion data and produces the two model artifacts. The README documents the UI, API endpoints, batch analysis, examples, and training workflow; the frontend source was not sampled, so its internal behavior is not detailed.

Main entry points: [`backend/predict.py`](https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py) (Predictor), [`backend/train.py`](https://github.com/afshazareen/clarity_project/blob/main/backend/train.py) (Training Pipeline), [`frontend/index.html`](https://github.com/afshazareen/clarity_project/blob/main/frontend/index.html) (Browser UI), [`backend/app.py`](https://github.com/afshazareen/clarity_project/blob/main/backend/app.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_ui["Browser UI<br/>[index.html]"]
  node_api["Flask API<br/>[app.py]"]
end

subgraph group_inference["Inference"]
  node_predictor["Predictor<br/>[predict.py]"]
  node_clarity_stage["Clarity Classification<br/>[predict.py]"]
  node_evasion_stage["Evasion Classification<br/>[predict.py]"]
  node_heuristics["Heuristic Fallbacks<br/>[predict.py]"]
end

subgraph group_training["Model Training"]
  node_trainer["Training Pipeline<br/>[train.py]"]
  node_dataset[("QEvasion Dataset")]
end

subgraph group_artifacts["Model Artifacts"]
  node_clarity_model["Clarity Model<br/>[config.json]"]
  node_evasion_model["Evasion Model<br/>[config.json]"]
end

node_user(("Analyst"))

node_user -->|"submits pairs"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"requests predictions"| node_predictor
node_predictor -->|"classifies clarity"| node_clarity_stage
node_predictor -->|"classifies evasion"| node_evasion_stage
node_predictor -->|"uses when unavailable"| node_heuristics
node_clarity_stage -->|"loads model"| node_clarity_model
node_evasion_stage -->|"loads model"| node_evasion_model
node_trainer -->|"loads data"| node_dataset
node_trainer -->|"trains and saves"| node_clarity_model
node_trainer -->|"trains and saves"| node_evasion_model

click node_ui "https://github.com/afshazareen/clarity_project/blob/main/frontend/index.html"
click node_api "https://github.com/afshazareen/clarity_project/blob/main/backend/app.py"
click node_trainer "https://github.com/afshazareen/clarity_project/blob/main/backend/train.py"
click node_predictor "https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py"
click node_clarity_stage "https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py"
click node_evasion_stage "https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py"
click node_heuristics "https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py"
click node_clarity_model "https://github.com/afshazareen/clarity_project/blob/main/models/clarity_model/config.json"
click node_evasion_model "https://github.com/afshazareen/clarity_project/blob/main/models/evasion_model/config.json"

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_ui,node_api toneBlue
class node_predictor,node_clarity_stage,node_evasion_stage,node_heuristics toneAmber
class node_trainer,node_dataset toneMint
class node_clarity_model,node_evasion_model toneRose
class node_user toneIndigo
```

## Components

### User Interaction

- [Browser UI](https://github.com/afshazareen/clarity_project/blob/main/frontend/index.html): `frontend/index.html`
- [Flask API](https://github.com/afshazareen/clarity_project/blob/main/backend/app.py): `backend/app.py`

### Inference

- [Predictor](https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py): `backend/predict.py`
- [Clarity Classification](https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py): `backend/predict.py`
- [Evasion Classification](https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py): `backend/predict.py`
- [Heuristic Fallbacks](https://github.com/afshazareen/clarity_project/blob/main/backend/predict.py): `backend/predict.py`

### Model Training

- [Training Pipeline](https://github.com/afshazareen/clarity_project/blob/main/backend/train.py): `backend/train.py`
- **QEvasion Dataset**

### Model Artifacts

- [Clarity Model](https://github.com/afshazareen/clarity_project/blob/main/models/clarity_model/config.json): `models/clarity_model/config.json`
- [Evasion Model](https://github.com/afshazareen/clarity_project/blob/main/models/evasion_model/config.json): `models/evasion_model/config.json`

### Other components

- **Analyst**

## Connections

- Analyst → Browser UI: submits pairs (evidence: `README.md`)
- Browser UI → Flask API: sends requests (evidence: `README.md`)
- Flask API → Predictor: requests predictions (evidence: `backend/app.py`)
- Predictor → Clarity Classification: classifies clarity (evidence: `backend/predict.py`)
- Predictor → Evasion Classification: classifies evasion (evidence: `backend/predict.py`)
- Predictor → Heuristic Fallbacks: uses when unavailable (evidence: `backend/predict.py`)
- Clarity Classification → Clarity Model: loads model (evidence: `backend/predict.py`)
- Evasion Classification → Evasion Model: loads model (evidence: `backend/predict.py`)
- Training Pipeline → QEvasion Dataset: loads data (evidence: `backend/train.py`)
- Training Pipeline → Clarity Model: trains and saves (evidence: `backend/train.py`)
- Training Pipeline → Evasion Model: trains and saves (evidence: `backend/train.py`)
