# degenerateuser/mplads-review architecture

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

- Interactive diagram: https://gitdiagram.com/degenerateuser/mplads-review
- Repository: https://github.com/degenerateuser/mplads-review

## Overview

This is a local-first MPLADS anomaly-review decision-support prototype. Its main workflow is to load provenance-labeled works, detect review signals, decompose risk and evidence, present role-oriented queues and comparisons, then save a human review decision. The README documents the product capabilities and JSON-backed demo architecture; source-index references and excerpts support the shown internal links. Several detector and route implementations were not sampled, so their detailed call paths are omitted.

Main entry points: [`backend/analysis.py`](https://github.com/degenerateuser/mplads-review/blob/main/backend/analysis.py) (Analysis and evidence), [`backend/models.py`](https://github.com/degenerateuser/mplads-review/blob/main/backend/models.py) (Domain models), [`frontend/src/App.tsx`](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/App.tsx) (Dashboard and review), [`frontend/src/api.ts`](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Review experience"]
  node_dashboard["Dashboard and review<br/>[App.tsx]"]
  node_evidence_view["Evidence comparison<br/>[EvidencePanel.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_demo_view["Demo fallback data<br/>[demo.ts]"]
  node_auth_ui["Session context<br/>[AuthContext.tsx]"]
end

subgraph group_service["API and identity"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_identity["Authentication<br/>[auth.py]"]
end

subgraph group_analysis["Anomaly analysis"]
  node_analysis_engine["Analysis and evidence<br/>[analysis.py]"]
  node_duplicates["Duplicate detection<br/>[duplicate.py]"]
  node_costs["Unit-cost detection<br/>[cost.py]"]
  node_stalls["Stalled-work detection<br/>[stalls.py]"]
  node_photos["Photo review<br/>[photos.py]"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
end

subgraph group_data["Records and persistence"]
  node_models["Domain models<br/>[models.py]"]
  node_generator["Synthetic work generator<br/>[generator.py]"]
  node_repository[("JSON and review storage<br/>[repository.py]")]
end

node_reviewer(("Human reviewer"))

node_reviewer -->|"selects work"| node_dashboard
node_dashboard -->|"requests summary"| node_api_client
node_api_client -->|"calls API"| node_api
node_api_client -->|"uses fallback"| node_demo_view
node_dashboard -->|"shows evidence"| node_evidence_view
node_reviewer -->|"submits review"| node_dashboard
node_dashboard -->|"saves decision"| node_api_client
node_api -->|"serves analysis"| node_analysis_engine
node_api -->|"loads records"| node_repository
node_api -->|"authenticates users"| node_identity
node_auth_ui -->|"calls auth methods"| node_api_client
node_analysis_engine -->|"runs detector"| node_duplicates
node_analysis_engine -->|"runs detector"| node_costs
node_analysis_engine -->|"runs detector"| node_stalls
node_analysis_engine -->|"runs detector"| node_photos
node_analysis_engine -->|"computes scores"| node_scoring
node_analysis_engine -->|"uses domain types"| node_models
node_duplicates -->|"reads works"| node_models
node_costs -->|"reads works"| node_models
node_stalls -->|"reads works"| node_models
node_photos -->|"reads photo metadata"| node_models
node_scoring -->|"uses score types"| node_models
node_generator -->|"creates works"| node_models
node_repository -->|"loads and saves"| node_models

click node_dashboard "https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/App.tsx"
click node_evidence_view "https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/components/EvidencePanel.tsx"
click node_api_client "https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/api.ts"
click node_demo_view "https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/demo.ts"
click node_auth_ui "https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/context/AuthContext.tsx"
click node_api "https://github.com/degenerateuser/mplads-review/blob/main/backend/main.py"
click node_identity "https://github.com/degenerateuser/mplads-review/blob/main/backend/auth.py"
click node_analysis_engine "https://github.com/degenerateuser/mplads-review/blob/main/backend/analysis.py"
click node_duplicates "https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/duplicate.py"
click node_costs "https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/cost.py"
click node_stalls "https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/stalls.py"
click node_photos "https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/photos.py"
click node_scoring "https://github.com/degenerateuser/mplads-review/blob/main/backend/scoring.py"
click node_models "https://github.com/degenerateuser/mplads-review/blob/main/backend/models.py"
click node_generator "https://github.com/degenerateuser/mplads-review/blob/main/data/generator.py"
click node_repository "https://github.com/degenerateuser/mplads-review/blob/main/backend/repository.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_dashboard,node_evidence_view,node_api_client,node_demo_view,node_auth_ui,node_reviewer toneBlue
class node_api,node_identity toneAmber
class node_analysis_engine,node_duplicates,node_costs,node_stalls,node_photos,node_scoring toneMint
class node_models,node_generator,node_repository toneRose
```

## Components

### Review experience

- [Dashboard and review](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Evidence comparison](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/components/EvidencePanel.tsx): `frontend/src/components/EvidencePanel.tsx`
- [API client](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Demo fallback data](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/demo.ts): `frontend/src/demo.ts`
- [Session context](https://github.com/degenerateuser/mplads-review/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`

### API and identity

- [FastAPI routes](https://github.com/degenerateuser/mplads-review/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/degenerateuser/mplads-review/blob/main/backend/auth.py): `backend/auth.py`

### Anomaly analysis

- [Analysis and evidence](https://github.com/degenerateuser/mplads-review/blob/main/backend/analysis.py): `backend/analysis.py`
- [Duplicate detection](https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/duplicate.py): `backend/detectors/duplicate.py`
- [Unit-cost detection](https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/cost.py): `backend/detectors/cost.py`
- [Stalled-work detection](https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/stalls.py): `backend/detectors/stalls.py`
- [Photo review](https://github.com/degenerateuser/mplads-review/blob/main/backend/detectors/photos.py): `backend/detectors/photos.py`
- [Risk scoring](https://github.com/degenerateuser/mplads-review/blob/main/backend/scoring.py): `backend/scoring.py`

### Records and persistence

- [Domain models](https://github.com/degenerateuser/mplads-review/blob/main/backend/models.py): `backend/models.py`
- [Synthetic work generator](https://github.com/degenerateuser/mplads-review/blob/main/data/generator.py): `data/generator.py`
- [JSON and review storage](https://github.com/degenerateuser/mplads-review/blob/main/backend/repository.py): `backend/repository.py`

### Other components

- **Human reviewer**

## Connections

- Human reviewer → Dashboard and review: selects work (evidence: `README.md`)
- Dashboard and review → API client: requests summary (evidence: `frontend/src/App.tsx`)
- API client → FastAPI routes: calls API (evidence: `README.md`)
- API client → Demo fallback data: uses fallback (evidence: `frontend/src/api.ts`)
- Dashboard and review → Evidence comparison: shows evidence (evidence: `frontend/src/App.tsx`)
- Human reviewer → Dashboard and review: submits review (evidence: `frontend/src/App.tsx`)
- Dashboard and review → API client: saves decision (evidence: `frontend/src/App.tsx`)
- FastAPI routes → Analysis and evidence: serves analysis (evidence: `backend/main.py`)
- FastAPI routes → JSON and review storage: loads records (evidence: `backend/main.py`)
- FastAPI routes → Authentication: authenticates users (evidence: `backend/main.py`)
- Session context → API client: calls auth methods (evidence: `frontend/src/context/AuthContext.tsx`)
- Analysis and evidence → Duplicate detection: runs detector (evidence: `backend/analysis.py`)
- Analysis and evidence → Unit-cost detection: runs detector (evidence: `backend/analysis.py`)
- Analysis and evidence → Stalled-work detection: runs detector (evidence: `backend/analysis.py`)
- Analysis and evidence → Photo review: runs detector (evidence: `backend/analysis.py`)
- Analysis and evidence → Risk scoring: computes scores (evidence: `backend/analysis.py`)
- Analysis and evidence → Domain models: uses domain types (evidence: `backend/analysis.py`)
- Duplicate detection → Domain models: reads works (evidence: `backend/detectors/duplicate.py`)
- Unit-cost detection → Domain models: reads works (evidence: `backend/detectors/cost.py`)
- Stalled-work detection → Domain models: reads works (evidence: `backend/detectors/stalls.py`)
- Photo review → Domain models: reads photo metadata (evidence: `backend/detectors/photos.py`)
- Risk scoring → Domain models: uses score types (evidence: `backend/scoring.py`)
- Synthetic work generator → Domain models: creates works (evidence: `data/generator.py`)
- JSON and review storage → Domain models: loads and saves (evidence: `backend/repository.py`)
