# sakshieng/georescue-disaster-relief architecture

> Architecture diagram of the GitHub repository sakshieng/georescue-disaster-relief, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sakshieng/georescue-disaster-relief
- Repository: https://github.com/sakshieng/georescue-disaster-relief

## Overview

##### Project Type and Purpose
- GeoRescue is a full-stack disaster management system. Its primary goal is to leverage AI/ML and real-time data (from satellite imagery, historical insights, and social media) to predict and respond to disasters such as floods, earthquakes, and tsunamis.
- The README highlights several key features: disaster assessment using imagery, resource allocation, real-time social media monitoring (Twitter feeds) and a collection of visual aids (graphs, maps, videos) to inform disaster response.

##### File Structure
- There are three main directories indicating clear modular separation:
- Frontend: Contains React-based UI components (using Vite), styles, and layouts for different disaster visualizations, such as earthquake activity graphs, deployment maps, and emergency components.
- Backend: Contains Python scripts, including the main application files (app.py, main.py) as well as modules for external APIs and scrapers. This part orchestrates the business logic, communicates with external data sources (Twitter, news, etc.), and likely provides REST endpoints.
- ML: Holds notebooks, a Streamlit app, a chatbot using Chainlit, configuration files, and CSV data files. This component deals with the machine learning models for disaster prediction, risk assessment, and resource allocation simulations.
- Configuration files (e.g., package.json, requirements.txt, vite.config.js) which signal the technologies used and help keep the separation of concerns clear.

##### Main Components
a. Frontend:
- UI/UX modules using React and Vite.
- Visual components like maps, charts, image carousels, and informative dashboards.
b. Backend:
- API server (likely FastAPI served via Uvicorn) with endpoints housed in files like main.py and app.py.
- External API integrations (Twitter API, news data) and web scrapers found in external_apis and scrapers directories.
- File handling for screenshots and possibly disaster assessment images.
c. ML Component:
- AI/ML pipelines including notebooks and models for earthquake and flood predictions.
- Interactive tools using Streamlit and Chainlit for deploying chatbots for resource allocation recommendations.
- Data files (CSV datasets) and configuration to manage ML experiments and production-ready predictions.

##### Relationships and Interactions
- Frontend interacts directly with the Backend through RESTful APIs (as implied by the uvicorn start command). The UI sends requests for disaster data, predictions, and resource recommendations.
- The Backend serves as the hub where data is aggregated from external sources and interacts with the ML services. It calls external API modules (for news, Twitter, etc.) to pull in real-time data.
- The ML modules work either as a separate service component or as an integrated part of the Backend. They can output predictions or risk assessments that are then fed to the UI or used in decision-making workflows.
- Data flow is directional:
- User actions on the Frontend trigger API calls to the Backend.
- The Backend makes calls to external data sources and, if needed, triggers ML predictions.
- ML outputs (predictions, charts, risk assessments) are returned through the Backend to the Frontend for visualization.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between UI (frontend), business logic/API (backend), and data analytics/ML (ml).
- Modular Architecture: Each subsystem (frontend, backend, ML) is developed and deployed relatively independently.
- Extensibility: The project design allows for additional external APIs or improvements to the ML models without significant changes to the overall architecture.
- Use of microservices (at least conceptually if not as isolated containers): The ML component and the backend can be decoupled to scale independently if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        FE_UI["UI Components"]:::frontend
        FE_MAP["Emergency Deployment Map"]:::frontend
        FE_GRAPH["Seismic Activity Graphs"]:::frontend
        FE_LAYOUT["Layout Modules (Earthquake, Floods, Tsunami)"]:::frontend
    end

    subgraph "Backend"
        BE_API["API Server (app.py, main.py)"]:::backend
        BE_EXT["External APIs (Twitter,News)"]:::backend
        BE_SCRAP["Scrapers"]:::backend
        BE_SHOTS["Screenshots Storage"]:::backend
    end

    subgraph "ML"
        ML_NOTE["Notebooks (earthquake.ipynb,flood-prediction-model.ipynb,prediction_of_earthquake_damage.ipynb)"]:::ml
        ML_STREAM["Streamlit App (streamlit_app.py)"]:::ml
        ML_CHAT["Chatbot (.chainlit)"]:::ml
    end

    %% Data Flow arrows
    FE_UI -->|"APIRequest"| BE_API
    BE_API -->|"FetchExternalData"| BE_EXT
    BE_API -->|"ScrapeData"| BE_SCRAP
    BE_API -->|"GetImages"| BE_SHOTS
    BE_API -->|"MLPredictionRequest"| ML_NOTE
    BE_API -->|"MLStreamlitCall"| ML_STREAM
    BE_API -->|"MLChatCall"| ML_CHAT
    ML_NOTE -->|"PredictionOutput"| BE_API
    ML_STREAM -->|"StreamOutput"| BE_API
    ML_CHAT -->|"ChatOutput"| BE_API
    BE_API -->|"APIResponse"| FE_UI

    %% Click Events for Frontend
    click FE_UI "https://github.com/sakshieng/georescue-disaster-relief/tree/main/frontend"
    click FE_MAP "https://github.com/sakshieng/georescue-disaster-relief/tree/main/frontend/src/components"
    click FE_LAYOUT "https://github.com/sakshieng/georescue-disaster-relief/tree/main/frontend/src/layout"

    %% Click Events for Backend
    click BE_API "https://github.com/sakshieng/georescue-disaster-relief/blob/main/backend/app.py"
    click BE_EXT "https://github.com/sakshieng/georescue-disaster-relief/tree/main/backend/external_apis"
    click BE_SCRAP "https://github.com/sakshieng/georescue-disaster-relief/tree/main/backend/scrapers"
    click BE_SHOTS "https://github.com/sakshieng/georescue-disaster-relief/tree/main/backend/screenshots"

    %% Click Events for ML
    click ML_NOTE "https://github.com/sakshieng/georescue-disaster-relief/blob/main/ml/earthquake.ipynb"
    click ML_STREAM "https://github.com/sakshieng/georescue-disaster-relief/blob/main/ml/streamlit_app.py"
    click ML_CHAT "https://github.com/sakshieng/georescue-disaster-relief/blob/main/ml/.chainlit"

    %% Styles
    classDef frontend fill:#85C1E9,stroke:#2E86C1,stroke-width:2px;
    classDef backend fill:#58D68D,stroke:#27AE60,stroke-width:2px;
    classDef ml fill:#F5B041,stroke:#D68910,stroke-width:2px;
```
