# gulatigarvit/firefly-backend-sih24 architecture

> Architecture diagram of the GitHub repository gulatigarvit/firefly-backend-sih24, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gulatigarvit/firefly-backend-sih24
- Repository: https://github.com/gulatigarvit/firefly-backend-sih24

## Overview

##### Project Type and Purpose
- Firefly-Backend is a Node.js (Express) API server for a dynamic fire evacuation system.
- It exposes REST endpoints to ingest real-time fire and BLE localization data, store and query information in MySQL (via Sequelize), notify external clients, and support path-planning and rescue operations.

##### File Structure
A. config/
- database.js – MySQL connection settings
- firebase.js – Firebase Cloud Messaging for push notifications
- http.js – global HTTP settings (ports, timeouts)
- enums.js – shared constants (status codes, roles)
B. models/
- building, city, fire_station, firefighter, incident, node (BLE beacon), user, incident_user
- index.js – sets up Sequelize models and relationships
C. controllers/ → HTTP layer
- building.js, fire_station.js, firefighter.js, incident.js, node.js, user.js
D. routes/ → Express.js routers wired to controllers
E. services/ → Business logic / data-access layer
- fire_station.js, incident.js, node.js, notification.js (wraps Firebase), user.js
F. middlewares/ → Cross-cutting concerns
- error handling, entity-exists checks
G. index.js → Bootstraps Express server, wires config, routes, error middleware

##### README for Additional Insights
- Tech Stack: Node.js/Express, MySQL + Sequelize
- Integrations:
- Mobile App (Flutter) for occupants
- Web Portal (React/TS) for fire stations/firefighters
- Arduino hardware (BLE sensors, fire detectors)
- Python Nav Engine (path planning & fire spread)

a. Main Components
1. IoT Layer: BLE sensors & fire detectors → publish sensor data (MQTT/HTTP) to Backend
2. Firefly API Server (Node.js/Express)
- HTTP REST endpoints (controllers + routes)
- Business logic (services)
- Middlewares for auth & validation
- Notification module (Firebase FCM)
3. Database (MySQL + Sequelize ORM)
4. External Services
- Firebase Cloud Messaging
- Path-Planning Service (Python nav engine)
5. Clients
- Mobile App (Flutter)
- Web Portal (React/TS)
b. Relationships & Data Flows
- BLE sensor → POST /nodes → node controller → service → DB
- Fire detector → POST /incident → incident controller → service → DB
- API Server → publishes notifications via Firebase → Mobile & Portal subscribe
- Clients query GET /incidents, GET /nodes, GET /routes
- API Server ↔ Path-Planning Service over HTTP/gRPC for dynamic route computation
c. Architectural Patterns & Principles
- Layered architecture: controllers (API), services (business), models (data)
- MVC-inspired separation (routes → controllers → services → models)
- Cross-cutting via Express middlewares
- Event-driven notifications (Firebase)
d. Key Technologies
- Node.js / Express.js
- Sequelize ORM → MySQL
- Firebase Cloud Messaging
- External Python microservice for navigation
- BLE sensors, Arduino firmware

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% IoT Layer
    subgraph "IoT Devices" 
        direction TB
        BEACONS["BLE Beacons"]:::iot
        SENSORS["Fire Sensors"]:::iot
    end

    %% Backend Layer
    subgraph "Firefly Backend (Express API)" 
        direction TB
        %% Config & Middleware
        subgraph "Config & Middleware"
            direction TB
            DBConfig["database.js"]:::config
            FirebaseConfig["firebase.js"]:::config
            HTTPConfig["http.js"]:::config
            Enums["enums.js"]:::config
            Middlewares["middlewares"]:::middleware
        end

        %% Routes & Controllers
        subgraph "Routes & Controllers"
            direction TB
            RoutesIndex["routes/index.js"]:::routes
            BuildingRoute["routes/building.js"]:::routes
            StationRoute["routes/fire_station.js"]:::routes
            FighterRoute["routes/firefighter.js"]:::routes
            IncidentRoute["routes/incident.js"]:::routes
            NodeRoute["routes/node.js"]:::routes
            UserRoute["routes/user.js"]:::routes

            BuildingCtrl["controllers/building.js"]:::controller
            StationCtrl["controllers/fire_station.js"]:::controller
            FighterCtrl["controllers/firefighter.js"]:::controller
            IncidentCtrl["controllers/incident.js"]:::controller
            NodeCtrl["controllers/node.js"]:::controller
            UserCtrl["controllers/user.js"]:::controller
        end

        %% Services Layer
        subgraph "Services"
            direction TB
            StationSvc["services/fire_station.js"]:::service
            IncidentSvc["services/incident.js"]:::service
            NodeSvc["services/node.js"]:::service
            NotificationSvc["services/notification.js"]:::service
            UserSvc["services/user.js"]:::service
        end

        %% Models / ORM
        subgraph "Models / ORM (Sequelize)"
            direction TB
            ModelsIndex["models/index.js"]:::model
            BuildingModel["models/building.js"]:::model
            CityModel["models/city.js"]:::model
            StationModel["models/fire_station.js"]:::model
            FighterModel["models/firefighter.js"]:::model
            IncidentModel["models/incident.js"]:::model
            IncidentUserModel["models/incident_user.js"]:::model
            NodeModel["models/node.js"]:::model
            UserModel["models/user.js"]:::model
        end

        Entry["index.js"]:::entry
    end

    %% Database
    MySQL[(MySQL Database)]:::database

    %% External Services
    FirebaseCloud(("Firebase FCM")):::external
    NavService["Path-Planning Service"]:::external

    %% Clients
    subgraph "Clients"
        direction TB
        Mobile["Mobile App (Flutter)"]:::client
        WebPortal["Web Portal (React/TS)"]:::client
    end

    %% Data Flows
    BEACONS -->|HTTP POST /nodes| NodeRoute
    SENSORS -->|HTTP POST /incident| IncidentRoute

    %% Route to Controller
    BuildingRoute --> BuildingCtrl
    StationRoute --> StationCtrl
    FighterRoute --> FighterCtrl
    IncidentRoute --> IncidentCtrl
    NodeRoute --> NodeCtrl
    UserRoute --> UserCtrl

    %% Controller to Service
    BuildingCtrl -->|calls| StationSvc
    StationCtrl -->|calls| StationSvc
    FighterCtrl -->|calls| UserSvc
    IncidentCtrl -->|calls| IncidentSvc
    NodeCtrl -->|calls| NodeSvc
    UserCtrl -->|calls| UserSvc

    %% Service to DB via Models
    StationSvc -->|uses ORM| StationModel
    IncidentSvc -->|uses ORM| IncidentModel
    IncidentSvc -->|uses ORM| IncidentUserModel
    NodeSvc -->|uses ORM| NodeModel
    UserSvc -->|uses ORM| UserModel
    ServiceModels[models/index.js]:::model
    ServiceModels -->|sets relationships| BuildingModel
    ServiceModels --> CityModel

    %% Entry bootstrap
    Entry --> DBConfig
    Entry --> FirebaseConfig
    Entry --> HTTPConfig
    Entry --> Enums
    Entry --> RoutesIndex
    Entry --> Middlewares

    %% DB connection
    DBConfig --> MySQL
    StationModel --> MySQL
    IncidentModel --> MySQL
    NodeModel --> MySQL
    UserModel --> MySQL

    %% Notifications
    NotificationSvc --> FirebaseCloud
    FirebaseCloud -->|Push Notifications| Mobile
    FirebaseCloud -->|Push Notifications| WebPortal

    %% Path planning
    IncidentSvc -->|request routes| NavService
    NavService -->|computed paths| IncidentSvc
    Mobile -->|GET /routes| IncidentCtrl
    WebPortal -->|GET /incidents| IncidentCtrl
    Mobile -->|GET /nodes| NodeCtrl
    WebPortal -->|GET /nodes| NodeCtrl

    %% Clients to API
    Mobile -->|HTTP| Entry
    WebPortal -->|HTTP| Entry

    %% Click Events
    click Entry "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/index.js"
    click DBConfig "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/config/database.js"
    click FirebaseConfig "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/config/firebase.js"
    click HTTPConfig "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/config/http.js"
    click Enums "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/config/enums.js"
    click ServiceModels "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/index.js"
    click BuildingModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/building.js"
    click CityModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/city.js"
    click StationModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/fire_station.js"
    click FighterModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/firefighter.js"
    click IncidentModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/incident.js"
    click IncidentUserModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/incident_user.js"
    click NodeModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/node.js"
    click UserModel "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/models/user.js"
    click BuildingCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/building.js"
    click StationCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/fire_station.js"
    click FighterCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/firefighter.js"
    click IncidentCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/incident.js"
    click NodeCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/node.js"
    click UserCtrl "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/controllers/user.js"
    click RoutesIndex "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/index.js"
    click BuildingRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/building.js"
    click StationRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/fire_station.js"
    click FighterRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/firefighter.js"
    click IncidentRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/incident.js"
    click NodeRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/node.js"
    click UserRoute "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/routes/user.js"
    click StationSvc "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/services/fire_station.js"
    click IncidentSvc "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/services/incident.js"
    click NodeSvc "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/services/node.js"
    click NotificationSvc "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/services/notification.js"
    click UserSvc "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/services/user.js"
    click Middlewares "https://github.com/gulatigarvit/firefly-backend-sih24/blob/main/middlewares/index.js"

    %% Styles
    classDef iot fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef middleware fill:#90EE90,stroke:#333,stroke-width:1px
    classDef routes fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef controller fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef service fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef model fill:#B0C4DE,stroke:#333,stroke-width:1px
    classDef entry fill:#4682B4,stroke:#333,stroke-width:1px
    classDef database fill:#ADD8E6,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#98FB98,stroke:#333,stroke-width:1px
    classDef client fill:#DDA0DD,stroke:#333,stroke-width:1px
```
