# vucore/pbl5_flood_warning_system architecture

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

- Interactive diagram: https://gitdiagram.com/vucore/pbl5_flood_warning_system
- Repository: https://github.com/vucore/pbl5_flood_warning_system

## Overview

##### Project type and purpose
- This is a full-stack, real-time flood warning system combining sensor data ingestion, flood‐risk computation, and an AI‐driven chatbot.
- Backend: FastAPI micro-modules (WebSocket/data ingestion, flood-risk API, chatbot API).
- Frontend: Static HTML/CSS/JS dashboards and chat interface.
- External services: Firebase Realtime Database, Ollama LLM server, Chroma vector store.

##### File structure
- Top-level “be/” directory holds three FastAPI sub-modules under `app/`:
- `data_module`: WebSocket server, REST endpoints, Firebase integration.
- `floodrisk_module`: flood risk computation REST API.
- `chatbot_module`: RAG-based chatbot REST API.
- `main.py` can start all modules on one port.
- `fake_data.py`: simulates sensor feeds to the WebSocket.
- “fe/” directory holds the static front end (HTML assets, CSS styles, JS logic including WebSocket client, charting, chat UI).

##### README for additional insights
- Two modes: separate processes (port 8000 for data+flood, port 8001 for chatbot) or unified via `main.py`.
- Sensor data flows to Firebase and via WebSocket.
- Chatbot pipeline uses LangChain + Chroma + local Ollama LLaMA3.
- Flood risk module computes risk on demand.

a. Main components:
- Frontend browser (Dashboard & Chat UI)
- Backend modules:
- Data Ingestion & WebSocket Server (`data_module`)
- Flood Risk API (`floodrisk_module`)
- Chatbot API (`chatbot_module`)
- Orchestrator (`main.py`)
- Data stores:
- Firebase Realtime Database (sensor_data)
- Chroma vector store (embeddings)
- External AI service: Ollama LLM (LLaMA3)
- Fake Data Generator (`fake_data.py`)

b. Relationships & data flows:
1. Fake Data → WebSocket server → Broadcast to connected clients & push to Firebase.
2. Frontend subscribes via WebSocket → renders real-time charts.
3. Frontend calls Flood Risk API → returns computed risk metrics.
4. Frontend sends chat messages → Chatbot API → RAG pipeline:
- Preprocess → classify/tag → retrieve docs from Chroma → build prompt → send to Ollama → format response → return to UI.
5. Chatbot module populates/updates Chroma vector store at startup from local data files.

c. Architectural patterns & design principles:
- Layered modules: Routes → Services → Utils/ML/RAG.
- Microservice-style: each domain (data, flood risk, chatbot) can run independently.
- Event-driven real-time updates via WebSocket.
- RAG pattern for chatbot (Retrieval + Generation).
- Separation of concerns (database, business logic, API, UI).

d. Key technologies & libraries:
- FastAPI, Uvicorn
- WebSocket (Starlette)
- Firebase Admin SDK
- LangChain, Chroma, HuggingFace Transformers
- Ollama local LLM server
- Vanilla JS, Chart.js for front end

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        F1["Dashboard & Chat UI"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        subgraph "Data Ingestion & WebSocket Server"
            WS_START["start_websocket.py"]:::backend
            WS_ROUTES["routes/websocket.py"]:::backend
            FUNC_ROUTES["routes/func_routes.py"]:::backend
            FB_SERV["services/firebase_services.py"]:::backend
            FUNC_SERV["services/func_services.py"]:::backend
            DATA_UTIL["Utils/data_processing.py"]:::backend
            STATE_UTIL["Utils/global_state.py"]:::backend
            SENSOR_MODEL["database/SensorData.py"]:::backend
            DB_MODEL["database/db.py"]:::backend
        end

        subgraph "Flood Risk Service"
            FR_ROUTES["routes/flood_risk_routes.py"]:::backend
            FR_SERV["service/flood_risk_service.py"]:::backend
        end

        subgraph "Chatbot Service"
            CB_START["start_chatbot.py"]:::backend
            CB_ROUTES["routes/chatbot_routes.py"]:::backend
            CB_SERV["services/chatbot_services.py"]:::backend
            CLASSIFIER["base/ML/classifier.py"]:::backend
            EMBEDDING["base/ML/embedding.py"]:::backend
            FILE_LOADER["base/RAG/file_loader.py"]:::backend
            RETRIEVER["base/RAG/setup_retriever.py"]:::backend
            RERANK["base/RAG/setup_rerank.py"]:::backend
            SPLITTER["base/RAG/setup_spilitter.py"]:::backend
            VECTORSTORE["base/RAG/vectorstore.py"]:::backend
            PREPROCESS["base/NLP/preprocess_text.py"]:::backend
            RESPONSE_GEN["base/response_generator.py"]:::backend
            MODEL_SETUP["base/model_setup.py"]:::backend
        end

        MAIN["main.py"]:::backend
        FAKE["fake_data.py"]:::backend
    end

    %% External Dependencies
    subgraph "External Dependencies"
        FB(("Firebase Realtime Database")):::database
        CHROMA(("Chroma Vector Store")):::database
        OLLAMA(("Ollama LLM Server")):::external
    end

    %% Data Flows
    FAKE -->|WS Feed| WS_START
    WS_START --> WS_ROUTES
    WS_ROUTES --> F1
    WS_START --> FB_SERV
    FB_SERV --> FB

    F1 -->|HTTP REST| FR_ROUTES
    FR_ROUTES --> FR_SERV

    F1 -->|HTTP REST| CB_ROUTES
    CB_ROUTES --> CB_SERV
    CB_SERV --> PREPROCESS --> CLASSIFIER
    CLASSIFIER --> RETRIEVER --> VECTORSTORE
    VECTORSTORE --> CHROMA
    VECTORSTORE --> RERANK --> OLLAMA
    VECTORSTORE --> SPLITTER --> OLLAMA
    RETRIEVER --> OLLAMA
    OLLAMA --> RESPONSE_GEN --> CB_SERV

    MAIN --> WS_START
    MAIN --> FR_ROUTES
    MAIN --> CB_START

    %% Click Events
    click WS_START "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/start_websocket.py"
    click WS_ROUTES "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/routes/websocket.py"
    click FUNC_ROUTES "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/routes/func_routes.py"
    click FB_SERV "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/services/firebase_services.py"
    click FUNC_SERV "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/services/func_services.py"
    click DATA_UTIL "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/Utils/data_processing.py"
    click STATE_UTIL "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/Utils/global_state.py"
    click SENSOR_MODEL "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/database/SensorData.py"
    click DB_MODEL "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/data_module/database/db.py"

    click FR_ROUTES "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/floodrisk_module/routes/flood_risk_routes.py"
    click FR_SERV "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/floodrisk_module/service/flood_risk_service.py"

    click CB_START "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/start_chatbot.py"
    click CB_ROUTES "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/routes/chatbot_routes.py"
    click CB_SERV "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/services/chatbot_services.py"
    click CLASSIFIER "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/ML/classifier.py"
    click EMBEDDING "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/ML/embedding.py"
    click FILE_LOADER "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/RAG/file_loader.py"
    click RETRIEVER "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/RAG/setup_retriever.py"
    click RERANK "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/RAG/setup_rerank.py"
    click SPLITTER "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/RAG/setup_spilitter.py"
    click VECTORSTORE "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/RAG/vectorstore.py"
    click PREPROCESS "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/NLP/preprocess_text.py"
    click RESPONSE_GEN "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/response_generator.py"
    click MODEL_SETUP "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/chatbot_module/base/model_setup.py"

    click MAIN "https://github.com/vucore/pbl5_flood_warning_system/blob/main/be/app/main.py"
    click FAKE "https://github.com/vucore/pbl5_flood_warning_system/blob/main/fake_data.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0288D1;
    classDef backend fill:#E8F5E9,stroke:#2E7D32;
    classDef external fill:#F5F5F5,stroke:#424242;
    classDef database fill:#F5F5F5,stroke:#424242;
    class F1 frontend;
    class WS_START,WS_ROUTES,FUNC_ROUTES,FB_SERV,FUNC_SERV,DATA_UTIL,STATE_UTIL,SENSOR_MODEL,DB_MODEL,FR_ROUTES,FR_SERV,CB_START,CB_ROUTES,CB_SERV,CLASSIFIER,EMBEDDING,FILE_LOADER,RETRIEVER,RERANK,SPLITTER,VECTORSTORE,PREPROCESS,RESPONSE_GEN,MODEL_SETUP,MAIN,FAKE backend;
    class FB,CHROMA database;
    class OLLAMA external
```
