# krishddd/floodops-multi-agent-system architecture

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

- Interactive diagram: https://gitdiagram.com/krishddd/floodops-multi-agent-system
- Repository: https://github.com/krishddd/floodops-multi-agent-system

## Overview

FloodOps is a flood monitoring, forecasting, and response platform: users choose an area, the backend gathers hazard data and advances a multi-agent response workflow, and a live map and panels display forecasts, risks, alerts, and phase changes. The backend’s seven-phase orchestrator coordinates specialist agents and connectors; ensemble, hydrology, and LLM reasoning support forecasts and decisions. The frontend also presents map layers, timeline playback, and compound threats. Some source excerpts are partial, so links between components are shown only where the README or sampled code supports them.

Main entry points: [`frontend/src/main.js`](https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/main.js) (App Bootstrap), [`backend/floodops/api/app.py`](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/app.py) (FastAPI App), [`backend/floodops/models/state.py`](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/models/state.py) (Flood State), [`backend/floodops/orchestrator/service.py`](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/orchestrator/service.py) (Phase Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_frontend["App Bootstrap<br/>[main.js]"]
  node_area["Area Search<br/>[area-search.js]"]
  node_map["Live Map<br/>[init.js]"]
  node_panels["Response Panels"]
  node_ensembleui["Ensemble Views"]
  node_timelineui["Timeline Playback"]
end

subgraph group_api["API Access"]
  node_apiapp["FastAPI App<br/>[app.py]"]
  node_floodroutes["Flood Routes<br/>[routes_flood.py]"]
  node_maproutes["Map Routes<br/>[routes_map.py]"]
  node_ensemble["Ensemble Routes<br/>[routes_ensemble.py]"]
  node_timeline["Timeline Routes<br/>[routes_timeline.py]"]
  node_v4routes["Hazard Routes<br/>[routes_v4.py]"]
  node_ws["WebSocket<br/>[websocket.py]"]
end

subgraph group_workflow["Response Workflow"]
  node_orchestrator["Phase Orchestrator<br/>[service.py]"]
  node_routing["Phase Routing<br/>[routing.py]"]
  node_agents["Specialist Agents"]
  node_eventbus["Event Bus<br/>[event_bus.py]"]
  node_state["Flood State<br/>[state.py]"]
end

subgraph group_data["Data and Reasoning"]
  node_connectors["Data Connectors"]
  node_hydrology["Hydrology Analysis"]
  node_llm["LLM Reasoning<br/>[client.py]"]
end

subgraph group_integrations["External Services"]
  node_externaldata(("Hazard Data Sources"))
  node_llmprovider(("LLM Providers"))
  node_geocoder(("Open-Meteo Geocoder"))
end

node_user(("Operator"))

node_user -->|"uses"| node_frontend
node_user -->|"searches area"| node_area
node_area -->|"geocodes place"| node_geocoder
node_area -->|"requests simulation"| node_apiapp
node_frontend -->|"initializes"| node_map
node_frontend -->|"updates"| node_panels
node_frontend -->|"renders"| node_ensembleui
node_frontend -->|"plays frames"| node_timelineui
node_frontend -->|"requests data"| node_apiapp
node_frontend -->|"receives updates"| node_ws
node_apiapp -->|"routes requests"| node_floodroutes
node_apiapp -->|"routes requests"| node_maproutes
node_apiapp -->|"routes requests"| node_ensemble
node_apiapp -->|"routes requests"| node_timeline
node_apiapp -->|"routes requests"| node_v4routes
node_floodroutes -->|"triggers workflow"| node_orchestrator
node_floodroutes -->|"reads state"| node_state
node_maproutes -->|"reads risk state"| node_state
node_ensemble -->|"reads forecasts"| node_state
node_timeline -->|"reads transitions"| node_state
node_v4routes -->|"queries sources"| node_connectors
node_orchestrator -->|"selects phase"| node_routing
node_orchestrator -->|"coordinates agents"| node_agents
node_orchestrator -->|"updates state"| node_state
node_orchestrator -->|"subscribes events"| node_eventbus
node_agents -->|"publish events"| node_eventbus
node_agents -->|"fetch inputs"| node_connectors
node_agents -->|"uses analysis"| node_hydrology
node_agents -->|"requests reasoning"| node_llm
node_connectors -->|"fetches observations"| node_externaldata
node_llm -.->|"generates responses"| node_llmprovider
node_ws -->|"streams state"| node_state

click node_frontend "https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/main.js"
click node_area "https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/panels/area-search.js"
click node_map "https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/map/init.js"
click node_panels "https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/panels"
click node_ensembleui "https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/ensemble"
click node_timelineui "https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/timeline"
click node_apiapp "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/app.py"
click node_floodroutes "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_flood.py"
click node_maproutes "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_map.py"
click node_ensemble "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_ensemble.py"
click node_timeline "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_timeline.py"
click node_v4routes "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_v4.py"
click node_ws "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/websocket.py"
click node_orchestrator "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/orchestrator/service.py"
click node_routing "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/orchestrator/routing.py"
click node_agents "https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/agents"
click node_eventbus "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/queue/event_bus.py"
click node_state "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/models/state.py"
click node_connectors "https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/connectors"
click node_hydrology "https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/hydrology"
click node_llm "https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/llm/client.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_frontend,node_area,node_map,node_panels,node_ensembleui,node_timelineui toneBlue
class node_apiapp,node_floodroutes,node_maproutes,node_ensemble,node_timeline,node_v4routes,node_ws toneAmber
class node_orchestrator,node_routing,node_agents,node_eventbus,node_state toneMint
class node_connectors,node_hydrology,node_llm toneRose
class node_externaldata,node_llmprovider,node_geocoder,node_user toneIndigo
```

## Components

### User Interface

- [App Bootstrap](https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/main.js): `frontend/src/main.js`
- [Area Search](https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/panels/area-search.js): `frontend/src/panels/area-search.js`
- [Live Map](https://github.com/krishddd/floodops-multi-agent-system/blob/main/frontend/src/map/init.js): `frontend/src/map/init.js`
- [Response Panels](https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/panels): `frontend/src/panels`
- [Ensemble Views](https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/ensemble): `frontend/src/ensemble`
- [Timeline Playback](https://github.com/krishddd/floodops-multi-agent-system/tree/main/frontend/src/timeline): `frontend/src/timeline`

### API Access

- [FastAPI App](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/app.py): `backend/floodops/api/app.py`
- [Flood Routes](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_flood.py): `backend/floodops/api/routes_flood.py`
- [Map Routes](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_map.py): `backend/floodops/api/routes_map.py`
- [Ensemble Routes](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_ensemble.py): `backend/floodops/api/routes_ensemble.py`
- [Timeline Routes](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_timeline.py): `backend/floodops/api/routes_timeline.py`
- [Hazard Routes](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/routes_v4.py): `backend/floodops/api/routes_v4.py`
- [WebSocket](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/api/websocket.py): `backend/floodops/api/websocket.py`

### Response Workflow

- [Phase Orchestrator](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/orchestrator/service.py): `backend/floodops/orchestrator/service.py`
- [Phase Routing](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/orchestrator/routing.py): `backend/floodops/orchestrator/routing.py`
- [Specialist Agents](https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/agents): `backend/floodops/agents`
- [Event Bus](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/queue/event_bus.py): `backend/floodops/queue/event_bus.py`
- [Flood State](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/models/state.py): `backend/floodops/models/state.py`

### Data and Reasoning

- [Data Connectors](https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/connectors): `backend/floodops/connectors`
- [Hydrology Analysis](https://github.com/krishddd/floodops-multi-agent-system/tree/main/backend/floodops/hydrology): `backend/floodops/hydrology`
- [LLM Reasoning](https://github.com/krishddd/floodops-multi-agent-system/blob/main/backend/floodops/llm/client.py): `backend/floodops/llm/client.py`

### External Services

- **Hazard Data Sources**
- **LLM Providers**
- **Open-Meteo Geocoder**

### Other components

- **Operator**

## Connections

- Operator → App Bootstrap: uses
- Operator → Area Search: searches area
- Area Search → Open-Meteo Geocoder: geocodes place
- Area Search → FastAPI App: requests simulation
- App Bootstrap → Live Map: initializes
- App Bootstrap → Response Panels: updates
- App Bootstrap → Ensemble Views: renders
- App Bootstrap → Timeline Playback: plays frames
- App Bootstrap → FastAPI App: requests data
- App Bootstrap → WebSocket: receives updates
- FastAPI App → Flood Routes: routes requests
- FastAPI App → Map Routes: routes requests
- FastAPI App → Ensemble Routes: routes requests
- FastAPI App → Timeline Routes: routes requests
- FastAPI App → Hazard Routes: routes requests
- Flood Routes → Phase Orchestrator: triggers workflow
- Flood Routes → Flood State: reads state
- Map Routes → Flood State: reads risk state
- Ensemble Routes → Flood State: reads forecasts
- Timeline Routes → Flood State: reads transitions
- Hazard Routes → Data Connectors: queries sources
- Phase Orchestrator → Phase Routing: selects phase
- Phase Orchestrator → Specialist Agents: coordinates agents
- Phase Orchestrator → Flood State: updates state
- Phase Orchestrator → Event Bus: subscribes events
- Specialist Agents → Event Bus: publish events
- Specialist Agents → Data Connectors: fetch inputs
- Specialist Agents → Hydrology Analysis: uses analysis
- Specialist Agents → LLM Reasoning: requests reasoning
- Data Connectors → Hazard Data Sources: fetches observations
- LLM Reasoning → LLM Providers: generates responses
- WebSocket → Flood State: streams state