How vyasylum/floodnet works
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)