# pranith2610/2047_image_judging_engine architecture

> Architecture diagram of the GitHub repository pranith2610/2047_image_judging_engine, 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/pranith2610/2047_image_judging_engine
- Repository: https://github.com/pranith2610/2047_image_judging_engine

## Overview

THE 2047 is a web-based image judging platform for memory-and-recreation competitions. Organizers submit a reference image and participant recreations; the API validates uploads and invokes the coordinator, which analyzes the reference once, evaluates participants, scores and explains comparisons, then ranks results. The product also documents calibration, session management, review flags, and result exports. The README documents the main judging stages; sampled source and the SOURCE INDEX support the component links shown. Some UI/API wiring and details of unsampled capabilities are not verified, so those connections are omitted.

Main entry points: [`app/core/coordinator.py`](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/coordinator.py) (Pipeline coordinator), [`app/api/routes.py`](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/api/routes.py) (Competition API), [`app/models/schemas.py`](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/models/schemas.py) (Profiles and results), [`app/core/analyzers/reference.py`](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/reference.py) (Reference analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_dashboard["Competition dashboard<br/>[index.html]"]
  node_browser_assets["Dashboard assets<br/>[app.js]"]
end

subgraph group_intake["API and intake"]
  node_application["FastAPI application<br/>[main.py]"]
  node_api["Competition API<br/>[routes.py]"]
  node_validator["Image validator<br/>[validator.py]"]
  node_image_store[("Image uploads")]
end

subgraph group_judging["Judging pipeline"]
  node_coordinator["Pipeline coordinator<br/>[coordinator.py]"]
  node_reference_analyzer["Reference analyzer<br/>[reference.py]"]
  node_participant_analyzer["Participant analyzer<br/>[participant.py]"]
  node_semantic_detector["Semantic detector"]
  node_comparator["Feature comparator<br/>[comparator.py]"]
  node_scorer["Weighted scoring<br/>[engine.py]"]
  node_explainer["Judging explanations<br/>[engine.py]"]
  node_ranker["Leaderboard ranking<br/>[engine.py]"]
  node_data_models["Profiles and results<br/>[schemas.py]"]
end

subgraph group_operations["Competition operations"]
  node_calibration["Calibration analysis<br/>[analyzer.py]"]
  node_session_store[("Session files")]
end

node_organizer(("Organizer"))
node_result_consumer(("Competition results"))

node_organizer -->|"uses"| node_dashboard
node_application -->|"mounts routes"| node_api
node_api -->|"validates images"| node_validator
node_api -->|"stores uploads"| node_image_store
node_api -->|"starts evaluation"| node_coordinator
node_api -->|"requests analysis"| node_calibration
node_coordinator -->|"analyzes reference"| node_reference_analyzer
node_coordinator -->|"analyzes recreations"| node_participant_analyzer
node_coordinator -->|"compares profiles"| node_comparator
node_coordinator -->|"calculates scores"| node_scorer
node_coordinator -->|"generates reports"| node_explainer
node_coordinator -->|"ranks evaluations"| node_ranker
node_coordinator -->|"runs calibration"| node_calibration
node_coordinator -->|"persists sessions"| node_session_store
node_reference_analyzer -->|"uses detection"| node_semantic_detector
node_participant_analyzer -->|"uses detection"| node_semantic_detector
node_reference_analyzer -->|"builds profiles"| node_data_models
node_participant_analyzer -->|"builds profiles"| node_data_models
node_comparator -->|"produces metrics"| node_data_models
node_scorer -->|"produces scores"| node_data_models
node_explainer -->|"produces reports"| node_data_models
node_ranker -->|"produces rankings"| node_data_models
node_api -->|"returns results"| node_result_consumer

click node_dashboard "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/templates/index.html"
click node_browser_assets "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/static/js/app.js"
click node_application "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/main.py"
click node_api "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/api/routes.py"
click node_validator "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/validator.py"
click node_image_store "https://github.com/pranith2610/2047_image_judging_engine/tree/main/uploads"
click node_coordinator "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/coordinator.py"
click node_reference_analyzer "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/reference.py"
click node_participant_analyzer "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/participant.py"
click node_semantic_detector "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/semantic_detector.py"
click node_comparator "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/comparators/comparator.py"
click node_scorer "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/scoring/engine.py"
click node_explainer "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/explanations/engine.py"
click node_ranker "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/ranking/engine.py"
click node_calibration "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/calibration/analyzer.py"
click node_session_store "https://github.com/pranith2610/2047_image_judging_engine/tree/main/sessions"
click node_data_models "https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/models/schemas.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_browser_assets toneBlue
class node_application,node_api,node_validator,node_image_store toneAmber
class node_coordinator,node_reference_analyzer,node_participant_analyzer,node_semantic_detector,node_comparator,node_scorer,node_explainer,node_ranker,node_data_models toneMint
class node_calibration,node_session_store toneRose
class node_organizer,node_result_consumer toneIndigo
```

## Components

### Web interface

- [Competition dashboard](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/templates/index.html): `app/templates/index.html`
- [Dashboard assets](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/static/js/app.js): `app/static/js/app.js`

### API and intake

- [FastAPI application](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/main.py): `app/main.py`
- [Competition API](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/api/routes.py): `app/api/routes.py`
- [Image validator](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/validator.py): `app/core/validator.py`
- [Image uploads](https://github.com/pranith2610/2047_image_judging_engine/tree/main/uploads): `uploads`

### Judging pipeline

- [Pipeline coordinator](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/coordinator.py): `app/core/coordinator.py`
- [Reference analyzer](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/reference.py): `app/core/analyzers/reference.py`
- [Participant analyzer](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/participant.py): `app/core/analyzers/participant.py`
- [Semantic detector](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/analyzers/semantic_detector.py): `app/core/analyzers/semantic_detector.py`
- [Feature comparator](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/comparators/comparator.py): `app/core/comparators/comparator.py`
- [Weighted scoring](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/scoring/engine.py): `app/core/scoring/engine.py`
- [Judging explanations](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/explanations/engine.py): `app/core/explanations/engine.py`
- [Leaderboard ranking](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/ranking/engine.py): `app/core/ranking/engine.py`
- [Profiles and results](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/models/schemas.py): `app/models/schemas.py`

### Competition operations

- [Calibration analysis](https://github.com/pranith2610/2047_image_judging_engine/blob/main/app/core/calibration/analyzer.py): `app/core/calibration/analyzer.py`
- [Session files](https://github.com/pranith2610/2047_image_judging_engine/tree/main/sessions): `sessions`

### Other components

- **Organizer**
- **Competition results**

## Connections

- Organizer → Competition dashboard: uses (evidence: `README.md`)
- FastAPI application → Competition API: mounts routes (evidence: `app/main.py`)
- Competition API → Image validator: validates images (evidence: `app/api/routes.py`)
- Competition API → Image uploads: stores uploads (evidence: `app/api/routes.py`)
- Competition API → Pipeline coordinator: starts evaluation (evidence: `app/api/routes.py`)
- Competition API → Calibration analysis: requests analysis (evidence: `app/api/routes.py`)
- Pipeline coordinator → Reference analyzer: analyzes reference (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Participant analyzer: analyzes recreations (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Feature comparator: compares profiles (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Weighted scoring: calculates scores (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Judging explanations: generates reports (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Leaderboard ranking: ranks evaluations (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Calibration analysis: runs calibration (evidence: `app/core/coordinator.py`)
- Pipeline coordinator → Session files: persists sessions (evidence: `app/core/coordinator.py`)
- Reference analyzer → Semantic detector: uses detection (evidence: `app/core/analyzers/reference.py`)
- Participant analyzer → Semantic detector: uses detection (evidence: `app/core/analyzers/participant.py`)
- Reference analyzer → Profiles and results: builds profiles (evidence: `app/core/analyzers/reference.py`)
- Participant analyzer → Profiles and results: builds profiles (evidence: `app/core/analyzers/participant.py`)
- Feature comparator → Profiles and results: produces metrics (evidence: `app/core/comparators/comparator.py`)
- Weighted scoring → Profiles and results: produces scores (evidence: `app/core/scoring/engine.py`)
- Judging explanations → Profiles and results: produces reports (evidence: `app/core/explanations/engine.py`)
- Leaderboard ranking → Profiles and results: produces rankings (evidence: `app/core/ranking/engine.py`)
- Competition API → Competition results: returns results (evidence: `README.md`)
