# j33v4nz/ggl architecture

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

- Interactive diagram: https://gitdiagram.com/j33v4nz/ggl
- Repository: https://github.com/j33v4nz/ggl

## Overview

Chronos Coastal is a coastal-flood scenario workspace: users select a corridor and hazard inputs, run a simulation, inspect infrastructure and route impacts, and prepare or review advisories. The Python service coordinates hydrology, grid, logistics, agent analysis, and operations; a React dashboard presents the results. The hosted worker provides a browser-demo adapter for screening calculations. README-documented forecast, satellite, advisory-delivery, and evaluation capabilities are included. Some relationships rely on the README or SOURCE INDEX rather than complete source excerpts; uncertain implementation links are omitted.

Main entry points: [`backend/app/operations.py`](https://github.com/j33v4nz/ggl/blob/main/backend/app/operations.py) (Operations and advisories), [`backend/app/main.py`](https://github.com/j33v4nz/ggl/blob/main/backend/app/main.py) (Simulation API), [`frontend/src/App.jsx`](https://github.com/j33v4nz/ggl/blob/main/frontend/src/App.jsx) (Scenario dashboard), [`backend/app/swarm/bus.py`](https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/bus.py) (Tactical event bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User workspace"]
  node_dashboard["Scenario dashboard<br/>[App.jsx]"]
  node_operations_ui["Operations dashboard"]
  node_inspection_ui["Inspection and model checks"]
end

subgraph group_simulation["Scenario modeling"]
  node_scenario_data["Corridors and assets<br/>[dataset.py]"]
  node_simulation_api["Simulation API<br/>[main.py]"]
  node_hydro["Compound hydrology<br/>[hydro_engine.py]"]
  node_grid["Power cascade<br/>[grid_engine.py]"]
  node_logistics["Route clearance"]
  node_simulation_result["Scenario simulation<br/>[simulation.py]"]
end

subgraph group_analysis["Agents and analysis"]
  node_map["Composite map tiles<br/>[map_generator.py]"]
  node_vision["Site inspection<br/>[vision_agent.py]"]
  node_swarm_bus["Tactical event bus<br/>[bus.py]"]
  node_swarm_agents["Scenario agents<br/>[hydro_agent.py]"]
  node_incident_plan["Incident action plan<br/>[apex_agent.py]"]
  node_evals["Model diagnostics<br/>[runner.py]"]
  node_gemini["Gemini vision service"]
end

subgraph group_operations["Operations and records"]
  node_operations_api["Operations and advisories<br/>[operations.py]"]
  node_storage[("Snapshots and receipts<br/>[storage.py]")]
  node_weather["Open-Meteo forecasts"]
  node_earth_engine["Earth Engine observations"]
  node_test_inbox["In-app test inbox"]
  node_webhook["Advisory webhook"]
end

subgraph group_hosted["Hosted demo"]
  node_hosted_adapter["Hosted request adapter<br/>[index.mjs]"]
  node_hosted_engine["Hosted screening engine<br/>[engine.mjs]"]
  node_browser_store[("Session-scoped D1")]
end

node_user(("Workspace user"))

node_user -->|"sets scenario"| node_dashboard
node_dashboard -->|"requests simulation"| node_simulation_api
node_dashboard -->|"receives events"| node_swarm_bus
node_dashboard -->|"opens inspection"| node_inspection_ui
node_simulation_api -->|"runs scenario"| node_simulation_result
node_simulation_api -->|"streams events"| node_swarm_bus
node_simulation_api -->|"routes operations"| node_operations_api
node_simulation_api -->|"requests inspection"| node_vision
node_simulation_api -->|"runs diagnostics"| node_evals
node_simulation_result -->|"computes water levels"| node_hydro
node_simulation_result -->|"evaluates grid"| node_grid
node_simulation_result -->|"evaluates routes"| node_logistics
node_hydro -->|"reads corridor inputs"| node_scenario_data
node_grid -->|"reads corridor assets"| node_scenario_data
node_logistics -->|"uses hydrology"| node_hydro
node_logistics -->|"reads route data"| node_scenario_data
node_vision -->|"generates inspection tile"| node_map
node_vision -->|"requests analysis"| node_gemini
node_vision -->|"publishes findings"| node_swarm_bus
node_swarm_agents -.->|"publishes messages"| node_swarm_bus
node_incident_plan -->|"uses agent messages"| node_swarm_bus
node_operations_ui -.->|"uses operations service"| node_operations_api
node_operations_api -->|"runs scenario model"| node_hydro
node_operations_api -->|"runs grid model"| node_grid
node_operations_api -->|"runs route model"| node_logistics
node_operations_api -->|"persists records"| node_storage
node_operations_api -->|"loads forecasts"| node_weather
node_operations_api -->|"loads observations"| node_earth_engine
node_operations_api -->|"delivers reviewed draft"| node_test_inbox
node_operations_api -.->|"dispatches advisory"| node_webhook
node_inspection_ui -.->|"requests inspection and checks"| node_simulation_api
node_user -.->|"reviews operations"| node_operations_ui
node_hosted_adapter -->|"runs screening calculations"| node_hosted_engine
node_hosted_adapter -->|"persists session records"| node_browser_store
node_dashboard -.->|"uses hosted demo"| node_hosted_adapter

click node_dashboard "https://github.com/j33v4nz/ggl/blob/main/frontend/src/App.jsx"
click node_operations_ui "https://github.com/j33v4nz/ggl/blob/main/frontend/src/CoastalDashboard.jsx"
click node_inspection_ui "https://github.com/j33v4nz/ggl/blob/main/frontend/src/components/GeminiInspectorModal.jsx"
click node_scenario_data "https://github.com/j33v4nz/ggl/blob/main/backend/app/dataset.py"
click node_simulation_api "https://github.com/j33v4nz/ggl/blob/main/backend/app/main.py"
click node_hydro "https://github.com/j33v4nz/ggl/blob/main/backend/app/hydro_engine.py"
click node_grid "https://github.com/j33v4nz/ggl/blob/main/backend/app/grid_engine.py"
click node_logistics "https://github.com/j33v4nz/ggl/blob/main/backend/app/logistics_engine.py"
click node_simulation_result "https://github.com/j33v4nz/ggl/blob/main/backend/app/simulation.py"
click node_map "https://github.com/j33v4nz/ggl/blob/main/backend/app/map_generator.py"
click node_vision "https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/vision_agent.py"
click node_swarm_bus "https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/bus.py"
click node_swarm_agents "https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/hydro_agent.py"
click node_incident_plan "https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/apex_agent.py"
click node_evals "https://github.com/j33v4nz/ggl/blob/main/backend/app/evals/runner.py"
click node_operations_api "https://github.com/j33v4nz/ggl/blob/main/backend/app/operations.py"
click node_storage "https://github.com/j33v4nz/ggl/blob/main/backend/app/storage.py"
click node_hosted_adapter "https://github.com/j33v4nz/ggl/blob/main/worker/index.mjs"
click node_hosted_engine "https://github.com/j33v4nz/ggl/blob/main/worker/engine.mjs"

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_operations_ui,node_inspection_ui,node_user toneBlue
class node_scenario_data,node_simulation_api,node_hydro,node_grid,node_logistics,node_simulation_result toneAmber
class node_map,node_vision,node_swarm_bus,node_swarm_agents,node_incident_plan,node_evals,node_gemini toneMint
class node_operations_api,node_storage,node_weather,node_earth_engine,node_test_inbox,node_webhook toneRose
class node_hosted_adapter,node_hosted_engine,node_browser_store toneIndigo
```

## Components

### User workspace

- [Scenario dashboard](https://github.com/j33v4nz/ggl/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Operations dashboard](https://github.com/j33v4nz/ggl/blob/main/frontend/src/CoastalDashboard.jsx): `frontend/src/CoastalDashboard.jsx`
- [Inspection and model checks](https://github.com/j33v4nz/ggl/blob/main/frontend/src/components/GeminiInspectorModal.jsx): `frontend/src/components/GeminiInspectorModal.jsx`

### Scenario modeling

- [Corridors and assets](https://github.com/j33v4nz/ggl/blob/main/backend/app/dataset.py): `backend/app/dataset.py`
- [Simulation API](https://github.com/j33v4nz/ggl/blob/main/backend/app/main.py): `backend/app/main.py`
- [Compound hydrology](https://github.com/j33v4nz/ggl/blob/main/backend/app/hydro_engine.py): `backend/app/hydro_engine.py`
- [Power cascade](https://github.com/j33v4nz/ggl/blob/main/backend/app/grid_engine.py): `backend/app/grid_engine.py`
- [Route clearance](https://github.com/j33v4nz/ggl/blob/main/backend/app/logistics_engine.py): `backend/app/logistics_engine.py`
- [Scenario simulation](https://github.com/j33v4nz/ggl/blob/main/backend/app/simulation.py): `backend/app/simulation.py`

### Agents and analysis

- [Composite map tiles](https://github.com/j33v4nz/ggl/blob/main/backend/app/map_generator.py): `backend/app/map_generator.py`
- [Site inspection](https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/vision_agent.py): `backend/app/swarm/vision_agent.py`
- [Tactical event bus](https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/bus.py): `backend/app/swarm/bus.py`
- [Scenario agents](https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/hydro_agent.py): `backend/app/swarm/hydro_agent.py`
- [Incident action plan](https://github.com/j33v4nz/ggl/blob/main/backend/app/swarm/apex_agent.py): `backend/app/swarm/apex_agent.py`
- [Model diagnostics](https://github.com/j33v4nz/ggl/blob/main/backend/app/evals/runner.py): `backend/app/evals/runner.py`
- **Gemini vision service**

### Operations and records

- [Operations and advisories](https://github.com/j33v4nz/ggl/blob/main/backend/app/operations.py): `backend/app/operations.py`
- [Snapshots and receipts](https://github.com/j33v4nz/ggl/blob/main/backend/app/storage.py): `backend/app/storage.py`
- **Open-Meteo forecasts**
- **Earth Engine observations**
- **In-app test inbox**
- **Advisory webhook**

### Hosted demo

- [Hosted request adapter](https://github.com/j33v4nz/ggl/blob/main/worker/index.mjs): `worker/index.mjs`
- [Hosted screening engine](https://github.com/j33v4nz/ggl/blob/main/worker/engine.mjs): `worker/engine.mjs`
- **Session-scoped D1**

### Other components

- **Workspace user**

## Connections

- Workspace user → Scenario dashboard: sets scenario (evidence: `frontend/src/App.jsx`)
- Scenario dashboard → Simulation API: requests simulation (evidence: `frontend/src/App.jsx`)
- Scenario dashboard → Tactical event bus: receives events (evidence: `README.md`)
- Scenario dashboard → Inspection and model checks: opens inspection (evidence: `frontend/src/App.jsx`)
- Simulation API → Scenario simulation: runs scenario (evidence: `README.md`)
- Simulation API → Tactical event bus: streams events (evidence: `README.md`)
- Simulation API → Operations and advisories: routes operations (evidence: `README.md`)
- Simulation API → Site inspection: requests inspection (evidence: `backend/app/main.py`)
- Simulation API → Model diagnostics: runs diagnostics (evidence: `backend/app/main.py`)
- Scenario simulation → Compound hydrology: computes water levels (evidence: `backend/app/simulation.py`)
- Scenario simulation → Power cascade: evaluates grid (evidence: `backend/app/simulation.py`)
- Scenario simulation → Route clearance: evaluates routes (evidence: `backend/app/simulation.py`)
- Compound hydrology → Corridors and assets: reads corridor inputs (evidence: `backend/app/hydro_engine.py`)
- Power cascade → Corridors and assets: reads corridor assets (evidence: `backend/app/grid_engine.py`)
- Route clearance → Compound hydrology: uses hydrology (evidence: `backend/app/logistics_engine.py`)
- Route clearance → Corridors and assets: reads route data (evidence: `backend/app/logistics_engine.py`)
- Site inspection → Composite map tiles: generates inspection tile (evidence: `backend/app/swarm/vision_agent.py`)
- Site inspection → Gemini vision service: requests analysis (evidence: `backend/app/swarm/vision_agent.py`)
- Site inspection → Tactical event bus: publishes findings (evidence: `backend/app/swarm/vision_agent.py`)
- Scenario agents → Tactical event bus: publishes messages (evidence: `backend/app/swarm/hydro_agent.py`)
- Incident action plan → Tactical event bus: uses agent messages (evidence: `backend/app/swarm/apex_agent.py`)
- Operations dashboard → Operations and advisories: uses operations service
- Operations and advisories → Compound hydrology: runs scenario model (evidence: `backend/app/operations.py`)
- Operations and advisories → Power cascade: runs grid model (evidence: `backend/app/operations.py`)
- Operations and advisories → Route clearance: runs route model (evidence: `backend/app/operations.py`)
- Operations and advisories → Snapshots and receipts: persists records (evidence: `backend/app/operations.py`)
- Operations and advisories → Open-Meteo forecasts: loads forecasts (evidence: `README.md`)
- Operations and advisories → Earth Engine observations: loads observations (evidence: `README.md`)
- Operations and advisories → In-app test inbox: delivers reviewed draft (evidence: `README.md`)
- Operations and advisories → Advisory webhook: dispatches advisory (evidence: `README.md`)
- Inspection and model checks → Simulation API: requests inspection and checks
- Workspace user → Operations dashboard: reviews operations
- Hosted request adapter → Hosted screening engine: runs screening calculations (evidence: `worker/index.mjs`)
- Hosted request adapter → Session-scoped D1: persists session records (evidence: `README.md`)
- Scenario dashboard → Hosted request adapter: uses hosted demo (evidence: `README.md`)