# rthx-m/m-roadgrid architecture

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

- Interactive diagram: https://gitdiagram.com/rthx-m/m-roadgrid
- Repository: https://github.com/rthx-m/m-roadgrid

## Overview

PWD Road Intelligence manages road projects and image-based inspections, then assigns urgency and rankings. Users create projects, upload inspection images, and review project history and results. Inspection creation stores images and delegates each image to the analysis orchestrator, which runs YOLO detection, Gemini assessment, and priority scoring; project operations also classify road context and maintain JSON-backed records. The README identifies the detection model and purpose. The graph follows shown calls and UI requests; database.py explicitly says the app uses JSON, and unsampled behavior is not inferred.

Main entry points: [`app/api/projects.py`](https://github.com/rthx-m/m-roadgrid/blob/main/app/api/projects.py) (Project API), [`frontend/js/app.js`](https://github.com/rthx-m/m-roadgrid/blob/main/frontend/js/app.js) (Road dashboard), [`app/api/inspections.py`](https://github.com/rthx-m/m-roadgrid/blob/main/app/api/inspections.py) (Inspection API), [`app/main.py`](https://github.com/rthx-m/m-roadgrid/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Road dashboard<br/>[app.js]"]
  node_server["FastAPI app<br/>[main.py]"]
end

subgraph group_projects["Project management"]
  node_project_api["Project API<br/>[projects.py]"]
  node_context["Road context AI<br/>[inspector.py]"]
  node_scoring["Priority scoring<br/>[scoring.py]"]
end

subgraph group_inspection["Inspection analysis"]
  node_inspection_api["Inspection API<br/>[inspections.py]"]
  node_analysis["Image analysis<br/>[analysis.py]"]
  node_yolo["YOLO detection<br/>[yolo.py]"]
  node_gemini["Visual assessment<br/>[inspector.py]"]
end

subgraph group_state["Persistence"]
  node_road_data[("Road records<br/>[road_data.json]")]
  node_uploads[("Inspection images")]
end

node_user(("PWD engineer"))
node_gemini_service["Google Gemini"]
node_yolo_model["RDD2022 model"]

node_user -->|"uses"| node_frontend
node_frontend -->|"requests API"| node_server
node_server -->|"mounts routes"| node_project_api
node_server -->|"mounts routes"| node_inspection_api
node_server -->|"serves app"| node_frontend
node_project_api -->|"reads and writes"| node_road_data
node_inspection_api -->|"reads and writes"| node_road_data
node_inspection_api -->|"stores images"| node_uploads
node_project_api -->|"removes project files"| node_uploads
node_project_api -->|"classifies context"| node_context
node_context -->|"requests generation"| node_gemini_service
node_inspection_api -->|"analyzes images"| node_analysis
node_analysis -->|"detects damage"| node_yolo
node_yolo -->|"runs inference"| node_yolo_model
node_analysis -->|"assesses image"| node_gemini
node_gemini -->|"requests generation"| node_gemini_service
node_analysis -->|"calculates priority"| node_scoring
node_project_api -->|"recalculates priority"| node_scoring
node_frontend -->|"requests projects"| node_project_api
node_frontend -->|"submits inspection"| node_inspection_api

click node_frontend "https://github.com/rthx-m/m-roadgrid/blob/main/frontend/js/app.js"
click node_server "https://github.com/rthx-m/m-roadgrid/blob/main/app/main.py"
click node_project_api "https://github.com/rthx-m/m-roadgrid/blob/main/app/api/projects.py"
click node_context "https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/inspector.py"
click node_inspection_api "https://github.com/rthx-m/m-roadgrid/blob/main/app/api/inspections.py"
click node_analysis "https://github.com/rthx-m/m-roadgrid/blob/main/app/api/analysis.py"
click node_yolo "https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/yolo.py"
click node_gemini "https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/inspector.py"
click node_scoring "https://github.com/rthx-m/m-roadgrid/blob/main/app/assessment/scoring.py"
click node_road_data "https://github.com/rthx-m/m-roadgrid/blob/main/data/road_data.json"
click node_uploads "https://github.com/rthx-m/m-roadgrid/tree/main/data"

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_frontend,node_server toneBlue
class node_project_api,node_context,node_scoring toneAmber
class node_inspection_api,node_analysis,node_yolo,node_gemini toneMint
class node_road_data,node_uploads toneRose
class node_user,node_gemini_service,node_yolo_model toneIndigo
```

## Components

### User experience

- [Road dashboard](https://github.com/rthx-m/m-roadgrid/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [FastAPI app](https://github.com/rthx-m/m-roadgrid/blob/main/app/main.py): `app/main.py`

### Project management

- [Project API](https://github.com/rthx-m/m-roadgrid/blob/main/app/api/projects.py): `app/api/projects.py`
- [Road context AI](https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/inspector.py): `app/ai/inspector.py`
- [Priority scoring](https://github.com/rthx-m/m-roadgrid/blob/main/app/assessment/scoring.py): `app/assessment/scoring.py`

### Inspection analysis

- [Inspection API](https://github.com/rthx-m/m-roadgrid/blob/main/app/api/inspections.py): `app/api/inspections.py`
- [Image analysis](https://github.com/rthx-m/m-roadgrid/blob/main/app/api/analysis.py): `app/api/analysis.py`
- [YOLO detection](https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/yolo.py): `app/ai/yolo.py`
- [Visual assessment](https://github.com/rthx-m/m-roadgrid/blob/main/app/ai/inspector.py): `app/ai/inspector.py`

### Persistence

- [Road records](https://github.com/rthx-m/m-roadgrid/blob/main/data/road_data.json): `data/road_data.json`
- [Inspection images](https://github.com/rthx-m/m-roadgrid/tree/main/data): `data`

### Other components

- **PWD engineer**
- **Google Gemini**
- **RDD2022 model**

## Connections

- PWD engineer → Road dashboard: uses (evidence: `frontend/js/app.js`)
- Road dashboard → FastAPI app: requests API (evidence: `frontend/js/app.js`)
- FastAPI app → Project API: mounts routes (evidence: `app/main.py`)
- FastAPI app → Inspection API: mounts routes (evidence: `app/main.py`)
- FastAPI app → Road dashboard: serves app (evidence: `app/main.py`)
- Project API → Road records: reads and writes (evidence: `app/api/projects.py`)
- Inspection API → Road records: reads and writes (evidence: `app/api/inspections.py`)
- Inspection API → Inspection images: stores images (evidence: `app/api/inspections.py`)
- Project API → Inspection images: removes project files (evidence: `app/api/projects.py`)
- Project API → Road context AI: classifies context (evidence: `app/api/projects.py`)
- Road context AI → Google Gemini: requests generation (evidence: `app/ai/inspector.py`)
- Inspection API → Image analysis: analyzes images (evidence: `app/api/inspections.py`)
- Image analysis → YOLO detection: detects damage (evidence: `app/api/analysis.py`)
- YOLO detection → RDD2022 model: runs inference (evidence: `app/ai/yolo.py`)
- Image analysis → Visual assessment: assesses image (evidence: `app/api/analysis.py`)
- Visual assessment → Google Gemini: requests generation (evidence: `app/ai/inspector.py`)
- Image analysis → Priority scoring: calculates priority (evidence: `app/api/analysis.py`)
- Project API → Priority scoring: recalculates priority (evidence: `app/api/projects.py`)
- Road dashboard → Project API: requests projects (evidence: `frontend/js/app.js`)
- Road dashboard → Inspection API: submits inspection (evidence: `frontend/js/app.js`)
