# vyasylum/floodnet architecture

> Architecture diagram of the GitHub repository vyasylum/floodnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vyasylum/floodnet
- Repository: https://github.com/vyasylum/floodnet

## Overview

##### Project type and purpose
- Flood-Net is a full-stack, event-driven emergency-routing system.
- It ingests WhatsApp SOS messages via Twilio, parses them with LLMs (Langflow + Mistral), assigns rescue crews, stores incidents in a Postgres database, and presents live case status on a Streamlit/Folium map dashboard.

##### File structure
- Top-level scripts:
- server.py – FastAPI app, Twilio webhook handler, LLM‐based parsing, routing logic
- dashboard.py – Streamlit front end with interactive map
- Config files: example.env, requirements.txt.txt
- Logs: floodnet.log (replayable log for offline fallback)
- Implied directories (from README): .vscode, __pycache__, .env (gitignored), optional floodnet notes directory

##### Key insights from README
- Async FastAPI handles inbound HTTP callbacks from Twilio/WhatsApp.
- Uses Langflow + Mistral for NLP extraction of location, urgency, needs.
- Geocoding with OpenStreetMap Nominatim.
- Data persistence in Neon Postgres (hosted).
- Streamlit + Folium drives the frontend dashboard.
- Docker/Compose for containerization, resilient to network drops, supports offline log replay.

##### Main components and interactions
a. External Messaging Layer
– WhatsApp client → Twilio webhook
b. API & Processing Layer (server.py)
– FastAPI server receives webhook
– Invokes Langflow API / Mistral LLM for text parsing
– Calls Nominatim geocoding service to resolve extracted addresses
– Runs routing logic to pick nearest rescue crew
c. Data Layer
– Neon Postgres for incidents, crews, assignments
– floodnet.log as append-only fallback log
d. Frontend Layer (dashboard.py)
– Streamlit app renders Folium map
– Polls or subscribes to database updates (via REST or direct DB)
– Displays real-time case markers, crew locations, status controls
e. Infrastructure
– Docker containers for server + dashboard
– .env config for secrets and endpoints
– Docker Compose for multi-container orchestration

##### Architectural patterns and design principles
- Event-driven webhook ingestion
- Microservices-style separation: API/service layer vs. dashboard
- Async I/O in FastAPI for concurrent webhook handling
- Single source of truth in Postgres, with log for replayability
- External service integration via HTTP APIs (Twilio, Langflow, Nominatim)
- Container-first (12-factor app) config via environment variables

##### Final checklist
- All components drawn and labeled
- Notes on key protocols (HTTP/Twilio webhook, REST to LLM, SQL to DB)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        TW["WhatsApp/Twilio"]:::external
        LF["Langflow API + Mistral"]:::external
        GN["Nominatim Geocoder"]:::external
    end

    subgraph "Backend"
        FA["FastAPI Server\n(async Python)"]:::processing
        REQ["requirements.txt.txt"]:::infra
        ENV["example.env"]:::infra
    end

    subgraph "Data Storage"
        DB["Neon Postgres"]:::data
    end

    subgraph "Frontend"
        SD["Streamlit + Folium Dashboard"]:::frontend
    end

    subgraph "Logs/Offline"
        LOG["floodnet.log"]:::log
    end

    subgraph "Infrastructure (Docker Compose)"
        DC["Docker Compose"]:::infra
        RM["README.md"]:::infra
        LS["LICENSE.md"]:::infra
    end

    TW -->|"HTTP Webhook"| FA
    FA -->|"REST parse"| LF
    LF -->|"Parsed result"| FA
    FA -->|"HTTP Geocode"| GN
    GN -->|"Geo results"| FA
    FA -->|"SQL write/read"| DB
    FA -->|"Append events"| LOG
    SD -->|"SQL read/subscribe"| DB
    DC --> FA
    DC --> SD

    click FA "https://github.com/vyasylum/floodnet/blob/main/server.py"
    click SD "https://github.com/vyasylum/floodnet/blob/main/dashboard.py"
    click ENV "https://github.com/vyasylum/floodnet/blob/main/example.env"
    click REQ "https://github.com/vyasylum/floodnet/blob/main/requirements.txt.txt"
    click LOG "https://github.com/vyasylum/floodnet/blob/main/floodnet.log"
    click RM "https://github.com/vyasylum/floodnet/blob/main/README.md"
    click LS "https://github.com/vyasylum/floodnet/blob/main/LICENSE.md"

    classDef external fill:#ADD8E6,stroke:#000;
    classDef processing fill:#90EE90,stroke:#000;
    classDef data fill:#FFA500,stroke:#000;
    classDef frontend fill:#D8BFD8,stroke:#000;
    classDef log fill:#D3D3D3,stroke:#000;
    classDef infra fill:#F5DEB3,stroke:#000;
```
