# jharlan-hash/learngen architecture

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

- Interactive diagram: https://gitdiagram.com/jharlan-hash/learngen
- Repository: https://github.com/jharlan-hash/learngen

## Overview

This repository implements a radar-based warning-training and evaluation simulator: users select a scenario, inspect radar and reports, draw/edit warnings, advance simulation time, and review graded performance. Backend subsystems ingest radar and scenario data, model simulation/truth, serve session APIs, and grade or calibrate outcomes; the frontend provides the map, radar display, drawing tools, session controls, and debrief. The README is empty, so product scope is inferred from the source index and excerpts; arrows are limited to documented imports, calls, and API requests.

Main entry points: [`backend/src/serve/router.py`](https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/router.py) (Session and API router), [`frontend/src/app/main.ts`](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/app/main.ts) (Application wiring), [`backend/src/ingest/scenario.py`](https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/scenario.py) (Scenario assembly), [`frontend/src/data/apiClient.ts`](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/data/apiClient.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Training interface"]
  node_app["Application wiring<br/>[main.ts]"]
  node_api["API client<br/>[apiClient.ts]"]
  node_session["Session controls<br/>[controller.ts]"]
  node_warnings["Warning editor"]
  node_drawing["Track geometry<br/>[track.ts]"]
  node_radar["Radar rendering<br/>[polarSweepLayer.ts]"]
end

subgraph group_backend["Simulation service"]
  node_server["HTTP server<br/>[server.py]"]
  node_router["Session and API router<br/>[router.py]"]
  node_views["Response views<br/>[views.py]"]
end

subgraph group_ingest["Data preparation"]
  node_batch_ingest["Radar bundle ingest<br/>[batch.py]"]
  node_scenario_ingest["Scenario assembly<br/>[scenario.py]"]
  node_truth_ingest["Truth data ingest<br/>[truth.py]"]
end

subgraph group_evaluation["Scoring and calibration"]
  node_grader["Warning grading<br/>[grade.py]"]
  node_grade_params["Grading parameters<br/>[params.py]"]
  node_calibration["Parameter calibration<br/>[runner.py]"]
end

subgraph group_domain["Simulation domain"]
  node_domain_models["Scenario and warning models<br/>[warnings.py]"]
  node_sim_clock["Simulation clock<br/>[sim_clock.py]"]
end

node_user(("Forecaster"))

node_user -->|"uses"| node_app
node_app -->|"configures"| node_api
node_app -->|"configures"| node_session
node_app -->|"configures"| node_warnings
node_app -->|"sets up"| node_radar
node_warnings -->|"stages edits"| node_drawing
node_session -->|"advances ticks"| node_api
node_api -.->|"sends API requests"| node_server
node_server -->|"dispatches requests"| node_router
node_router -->|"builds responses"| node_views
node_router -->|"loads scenarios"| node_scenario_ingest
node_router -->|"uses truth data"| node_truth_ingest
node_router -->|"loads radar bundles"| node_batch_ingest
node_router -->|"grades warnings"| node_grader
node_router -->|"uses models"| node_domain_models
node_scenario_ingest -->|"loads truth"| node_truth_ingest
node_scenario_ingest -->|"uses grading"| node_grader
node_batch_ingest -->|"checks time"| node_sim_clock
node_grader -->|"uses parameters"| node_grade_params
node_calibration -->|"evaluates scenarios"| node_scenario_ingest
node_calibration -->|"overrides parameters"| node_grade_params

click node_app "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/app/main.ts"
click node_api "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/data/apiClient.ts"
click node_session "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/session/controller.ts"
click node_warnings "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/app/warningPopupWiring.ts"
click node_drawing "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/draw/track.ts"
click node_radar "https://github.com/jharlan-hash/learngen/blob/main/frontend/src/renderer/polarSweepLayer.ts"
click node_server "https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/server.py"
click node_router "https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/router.py"
click node_views "https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/views.py"
click node_domain_models "https://github.com/jharlan-hash/learngen/blob/main/backend/src/domain/warnings.py"
click node_sim_clock "https://github.com/jharlan-hash/learngen/blob/main/backend/src/domain/sim_clock.py"
click node_batch_ingest "https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/batch.py"
click node_scenario_ingest "https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/scenario.py"
click node_truth_ingest "https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/truth.py"
click node_grader "https://github.com/jharlan-hash/learngen/blob/main/backend/src/grading/grade.py"
click node_grade_params "https://github.com/jharlan-hash/learngen/blob/main/backend/src/grading/params.py"
click node_calibration "https://github.com/jharlan-hash/learngen/blob/main/backend/src/calibration/runner.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_app,node_api,node_session,node_warnings,node_drawing,node_radar toneBlue
class node_server,node_router,node_views toneAmber
class node_batch_ingest,node_scenario_ingest,node_truth_ingest toneMint
class node_grader,node_grade_params,node_calibration toneRose
class node_domain_models,node_sim_clock,node_user toneIndigo
```

## Components

### Training interface

- [Application wiring](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/app/main.ts): `frontend/src/app/main.ts`
- [API client](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/data/apiClient.ts): `frontend/src/data/apiClient.ts`
- [Session controls](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/session/controller.ts): `frontend/src/session/controller.ts`
- [Warning editor](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/app/warningPopupWiring.ts): `frontend/src/app/warningPopupWiring.ts`
- [Track geometry](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/draw/track.ts): `frontend/src/draw/track.ts`
- [Radar rendering](https://github.com/jharlan-hash/learngen/blob/main/frontend/src/renderer/polarSweepLayer.ts): `frontend/src/renderer/polarSweepLayer.ts`

### Simulation service

- [HTTP server](https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/server.py): `backend/src/serve/server.py`
- [Session and API router](https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/router.py): `backend/src/serve/router.py`
- [Response views](https://github.com/jharlan-hash/learngen/blob/main/backend/src/serve/views.py): `backend/src/serve/views.py`

### Data preparation

- [Radar bundle ingest](https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/batch.py): `backend/src/ingest/batch.py`
- [Scenario assembly](https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/scenario.py): `backend/src/ingest/scenario.py`
- [Truth data ingest](https://github.com/jharlan-hash/learngen/blob/main/backend/src/ingest/truth.py): `backend/src/ingest/truth.py`

### Scoring and calibration

- [Warning grading](https://github.com/jharlan-hash/learngen/blob/main/backend/src/grading/grade.py): `backend/src/grading/grade.py`
- [Grading parameters](https://github.com/jharlan-hash/learngen/blob/main/backend/src/grading/params.py): `backend/src/grading/params.py`
- [Parameter calibration](https://github.com/jharlan-hash/learngen/blob/main/backend/src/calibration/runner.py): `backend/src/calibration/runner.py`

### Simulation domain

- [Scenario and warning models](https://github.com/jharlan-hash/learngen/blob/main/backend/src/domain/warnings.py): `backend/src/domain/warnings.py`
- [Simulation clock](https://github.com/jharlan-hash/learngen/blob/main/backend/src/domain/sim_clock.py): `backend/src/domain/sim_clock.py`

### Other components

- **Forecaster**

## Connections

- Forecaster → Application wiring: uses (evidence: `frontend/src/app/main.ts`)
- Application wiring → API client: configures (evidence: `frontend/src/app/main.ts`)
- Application wiring → Session controls: configures (evidence: `frontend/src/app/main.ts`)
- Application wiring → Warning editor: configures (evidence: `frontend/src/app/main.ts`)
- Application wiring → Radar rendering: sets up (evidence: `frontend/src/app/main.ts`)
- Warning editor → Track geometry: stages edits (evidence: `frontend/src/app/warningPopupWiring.ts`)
- Session controls → API client: advances ticks (evidence: `frontend/src/session/controller.ts`)
- API client → HTTP server: sends API requests (evidence: `frontend/src/data/apiClient.ts`)
- HTTP server → Session and API router: dispatches requests (evidence: `backend/src/serve/server.py`)
- Session and API router → Response views: builds responses (evidence: `backend/src/serve/router.py`)
- Session and API router → Scenario assembly: loads scenarios (evidence: `backend/src/serve/router.py`)
- Session and API router → Truth data ingest: uses truth data (evidence: `backend/src/serve/router.py`)
- Session and API router → Radar bundle ingest: loads radar bundles (evidence: `backend/src/serve/router.py`)
- Session and API router → Warning grading: grades warnings (evidence: `backend/src/serve/router.py`)
- Session and API router → Scenario and warning models: uses models (evidence: `backend/src/serve/router.py`)
- Scenario assembly → Truth data ingest: loads truth (evidence: `backend/src/ingest/scenario.py`)
- Scenario assembly → Warning grading: uses grading (evidence: `backend/src/ingest/scenario.py`)
- Radar bundle ingest → Simulation clock: checks time (evidence: `backend/src/ingest/batch.py`)
- Warning grading → Grading parameters: uses parameters (evidence: `backend/src/grading/__init__.py`)
- Parameter calibration → Scenario assembly: evaluates scenarios (evidence: `backend/src/calibration/runner.py`)
- Parameter calibration → Grading parameters: overrides parameters
