# habiitg/iitghabapp architecture

> Architecture diagram of the GitHub repository habiitg/iitghabapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/habiitg/iitghabapp
- Repository: https://github.com/habiitg/iitghabapp

## Overview

##### Project type and purpose
- This is a full-stack, multi-client gateway system called “Hostel Affairs Board.”
- Mobile clients (Flutter), several web admin/client portals (React/Vite), all talking to a versioned Node.js/Express REST API, backed by MongoDB Atlas. External services: Azure AD for OAuth, Firebase Cloud Messaging, AWS EC2/S3, Outlook SMTP.

##### File structure
- Top-level “frontend2” directory: Flutter mobile app (iOS/Android/Linux/Windows/macOS).
- Multiple React-based web frontends (hab-frontend, hostel-frontend, login-frontend, smc-frontend), each under its own directory.
- “server” directory: Node.js/Express API with two versions (v1 & v2), each using modular MVC structure under modules/, plus config, middleware, utils, scripts.
- Deployment/config files: ecosystem.config.js, GitHub Workflows in Flutter, AWS/S3 references, .env variables for MongoDB, Azure AD, JWT, Outlook.

##### README insights
- Confirms tech stack: Node.js 18, Express.js, MongoDB Atlas, Flutter 3.x, React 19.x
- Features: Complaint management, role-based access, QR mess cards, JWT + Azure OAuth
- Infrastructure: AWS EC2/S3, CI/CD via GitHub Workflows

##### Main components & their interactions
a. Clients:
- Mobile App (Flutter): /frontend2 – authentication, complaint UI, QR scanning, push notifications
- Admin Web Portal (React): /hab-frontend – complaint approvals, mess management, user stats
- Additional Web Clients: /hostel-frontend, /login-frontend, /smc-frontend for role-specific tasks
b. API Layer:
- API Gateway/Express Servers (server/v1 & server/v2) – versioned REST endpoints
- Middleware: JWT authentication (authenticateJWT.js), Azure AD OAuth guard (requireMicrosoftAuth.js)
- Modules (MVC): auth, user, hostel, mess, mess_change, feedback, bug_report, notification, profile, qr
c. Data Storage:
- MongoDB Atlas – collections per module (e.g., users, feedbacks, messMenus, hostelAllocations)
- AWS S3 – static assets/uploads via Cloudinary or direct S3 integration
d. External Services:
- Azure AD – OAuth for Outlook login and JWT token issuance
- Firebase – FCMToken model + firebase.js for push notifications
- Outlook SMTP – sending emails for notifications
- AWS EC2 – hosts the Node server
- AWS S3 – asset storage

##### Architectural patterns & design principles
- Layered architecture: client → API layer → business logic → data layer
- Modular MVC/REST: each feature in its own module folder with controller, model, route
- Versioning: v1 and v2 subdirectories to support breaking changes without downtime
- Separation of concerns: distinct mobile vs multiple web frontends; all share same API
- Dependency injection via config files (config/default.js, .env)
- Asynchronous scheduling: autoFeedbackScheduler, autoMessChangeScheduler, autoGuestCleanupScheduler

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Client Tier"
        direction TB
        FlutterApp["Flutter Mobile App"]:::clientBlue
        HabWeb["Admin Web Portal"]:::webLightBlue
        HostelWeb["Hostel Web Client"]:::webLightBlue
        LoginWeb["Login Web Client"]:::webLightBlue
        SMCWeb["SMC Web Client"]:::webLightBlue
    end

    %% API Layer
    subgraph "API Tier"
        direction TB
        LoadBalancer["Load Balancer"]:::apiOrange

        subgraph "Express API v1" 
            direction TB
            APIv1["REST API v1 Gateway"]:::apiOrange
            subgraph "Config v1"
                direction TB
                V1Conf1["default.js"]:::config
                V1Conf2["appVersion.json"]:::config
                V1Conf3["onedrive.js"]:::config
            end
            subgraph "Middleware v1"
                direction TB
                JWTv1["JWT Authentication"]:::middleware
                AzureAuthV1["Azure AD OAuth Guard"]:::middleware
            end
        end

        subgraph "Express API v2"
            direction TB
            APIv2["REST API v2 Gateway"]:::apiOrange
            subgraph "Config v2"
                direction TB
                V2Conf1["default.js"]:::config
                V2Conf2["appVersion.json"]:::config
                V2Conf3["onedrive.js"]:::config
            end
            subgraph "Middleware v2"
                direction TB
                JWTv2["JWT Authentication (v2)"]:::middleware
                AzureAuthV2["Azure AD OAuth Guard (v2)"]:::middleware
            end
        end

        LoadBalancer -->|"forwards HTTPS"| APIv1
        LoadBalancer -->|"forwards HTTPS"| APIv2
    end

    %% Data & Services Layer
    subgraph "Data & Services Tier"
        direction TB
        MongoDB["MongoDB Atlas"]:::dbGreen
        S3["AWS S3 / Cloudinary"]:::storage
        AzureAD["Azure AD OAuth"]:::extPurple
        Firebase["Firebase Cloud Messaging"]:::extPurple
        Outlook["Outlook SMTP"]:::extPurple
    end

    %% Connections
    FlutterApp -->|"HTTPS REST / JWT"| LoadBalancer
    HabWeb -->|"HTTPS REST / JWT"| LoadBalancer
    HostelWeb -->|"HTTPS REST / JWT"| LoadBalancer
    LoginWeb -->|"HTTPS REST / JWT"| LoadBalancer
    SMCWeb -->|"HTTPS REST / JWT"| LoadBalancer

    APIv1 -->|"Mongoose CRUD"| MongoDB
    APIv2 -->|"Mongoose CRUD"| MongoDB

    APIv1 -->|"OAuth2"| AzureAD
    APIv2 -->|"OAuth2"| AzureAD

    APIv1 -->|"FCM Push"| Firebase
    APIv2 -->|"FCM Push"| Firebase

    APIv1 -->|"Email Notifications"| Outlook
    APIv2 -->|"Email Notifications"| Outlook

    APIv1 -->|"File Upload/Download"| S3
    APIv2 -->|"File Upload/Download"| S3

    %% Click Events for component mapping
    click FlutterApp "https://github.com/habiitg/iitghabapp/tree/dev/frontend2"
    click HabWeb "https://github.com/habiitg/iitghabapp/tree/dev/hab-frontend"
    click HostelWeb "https://github.com/habiitg/iitghabapp/tree/dev/hostel-frontend"
    click LoginWeb "https://github.com/habiitg/iitghabapp/tree/dev/login-frontend"
    click SMCWeb "https://github.com/habiitg/iitghabapp/tree/dev/smc-frontend"

    click APIv1 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/index.js"
    click APIv2 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/index.js"

    click V1Conf1 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/config/default.js"
    click V1Conf2 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/config/appVersion.json"
    click V1Conf3 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/config/onedrive.js"

    click V2Conf1 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/config/default.js"
    click V2Conf2 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/config/appVersion.json"
    click V2Conf3 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/config/onedrive.js"

    click JWTv1 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/middleware/authenticateJWT.js"
    click AzureAuthV1 "https://github.com/habiitg/iitghabapp/blob/dev/server/v1/middleware/requireMicrosoftAuth.js"

    click JWTv2 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/middleware/authenticateJWT.js"
    click AzureAuthV2 "https://github.com/habiitg/iitghabapp/blob/dev/server/v2/middleware/requireMicrosoftAuth.js"

    %% Styles
    classDef clientBlue fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef webLightBlue fill:#BFEFFF,stroke:#000,stroke-width:1px
    classDef apiOrange fill:#FFA500,stroke:#000,stroke-width:1px
    classDef dbGreen fill:#98FB98,stroke:#000,stroke-width:1px
    classDef storage fill:#DA70D6,stroke:#000,stroke-width:1px
    classDef extPurple fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef middleware fill:#FFD700,stroke:#000,stroke-width:1px
    classDef config fill:#FFE4B5,stroke:#000,stroke-width:1px
```
