# harilakshman25/kgp-mess-hub architecture

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

- Interactive diagram: https://gitdiagram.com/harilakshman25/kgp-mess-hub
- Repository: https://github.com/harilakshman25/kgp-mess-hub

## Overview

##### Project type and purpose
- This is a full-stack web application called “KGP MessHub” for managing hostel mess operations at IIT Kharagpur.
- Frontend: React (Vite), Tailwind CSS, React Router, React Query, Context API.
- Backend: Node.js + Express, MongoDB (Mongoose ORM), JWT auth, Multer file uploads, Nodemailer email workflows.
- Purpose: Provide role-based access for admins, mess managers, and students to manage menus, orders, complaints, analytics, and student data.

##### File structure
- Top-level dirs:
- client/ — React app with src/components, src/context, src/hooks, src/services (API wrappers), src/utils, src/pages
- server/ — Express app with config (DB, keys), controllers (business logic), routes (REST endpoints), models (MongoDB schemas), middleware (auth, validation, file uploads), utils (CSV parser, email, helpers)
- Supporting files: .gitignore, start.sh (launcher), assets/ for screenshots.
- Build/config scripts: client/vite.config.js, tailwind.config.js, server/server.js, npm scripts in package.json.

##### README for additional insights
- Multi-role authentication flow requiring admin approval for managers.
- Data flows: CSV uploads → student records; client API calls → controllers; controllers → models → MongoDB.
- External integrations: Nodemailer for emails, CSV parser for batch uploads, potential QR code library.
- Future features hint at QR code generation, real-time updates, analytics, inventory tracking.

a. Main components to include:
- Client (React SPA)
- Server (Express API)
- Database (MongoDB)
- File Storage (uploads folder for CSVs and images)
- External Services: Email service (SMTP via Nodemailer), CSV parsing utility
- Authentication (JWT token store)
b. Relationships & interactions:
1. User browsers → React SPA → React Router navigates pages.
2. SPA makes HTTP(S) calls (via axios/fetch in services) to Express REST API endpoints (/api/auth, /api/students, /api/orders, etc.).
3. Express middleware layer: JWT validation → dispatch to controllers.
4. Controllers invoke Mongoose models → read/write to MongoDB.
5. File-upload endpoints use Multer middleware → store CSVs in server/uploads → CSV parser utility populates Student model.
6. Nodemailer utility sends confirmation or approval emails.
7. React Context Providers (AuthContext, CartContext, ThemeContext) manage client-side state.
c. Architectural patterns & design principles:
- Layered architecture on the server:
– Routes → Middleware → Controllers → Models → Database
- Component-based design on the client with separation of presentational and container components.
- Context API for cross-cutting concerns (auth, theme, cart).
- Hooks for reusable logic (useApi, useAuth, useLocalStorage).
- Single Page Application communicating over RESTful API.
- Role-based access control enforced both client-side (ProtectedRoute) and server-side (auth middleware).
d. Key technologies/frameworks:
- Frontend: React, Vite, Tailwind CSS, React Query, React Hook Form, React Router
- Backend: Node.js, Express.js, Mongoose, Multer, JSON Web Tokens, Nodemailer
- Database: MongoDB
- Utilities: csv-parse, email service helper, custom helpers

##### Detail without overthinking
- Server modules by domain: auth, student management, order processing, complaint handling, admin stats, item catalog.
- Client modules: Auth components, Dashboard components (Admin, Manager, Student), common UI elements, context providers, and hooks.
- Both synchronous (HTTP) and asynchronous (email, CSV processing) interactions.
- Notes for future extensions (QR code service, real-time updates) to indicate system extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client (React SPA)"
        direction TB
        User["User (Admin/Manager/Student)"]:::external
        SPA["React SPA"]:::frontend
        Main["Entry Point\nclient/src/main.jsx"]:::frontend
        AppShell["App Shell & Routing\nclient/src/App.jsx"]:::frontend
        Pages["React Router Pages\nclient/src/pages/*.jsx"]:::frontend
        Components["UI Components\nclient/src/components/"]:::frontend
        Contexts["Context Providers\nAuth, Cart, Theme"]:::frontend
        Hooks["Custom Hooks\nuseApi, useAuth, useLocalStorage"]:::frontend
        Services["API Wrappers\nclient/src/services/*.js"]:::frontend
        UtilsFE["Utils & Constants\nclient/src/utils/*.js"]:::frontend
        Styles["Styling Config\nTailwind & Vite & CSS"]:::frontend
    end

    %% Server Tier
    subgraph "Server (Express API)"
        direction TB
        ServerEntry["Server Entry\nserver/server.js"]:::backend
        Config["Configuration\nDB & Keys\nserver/config"]:::backend
        subgraph "Middleware"
            direction TB
            AuthMW["Auth Middleware\nserver/middleware/auth.js"]:::backend
            UploadMW["Upload Middleware\nserver/middleware/upload.js"]:::backend
            ValMW["Validation Middleware\nserver/middleware/validation.js"]:::backend
        end
        subgraph "Routes"
            direction TB
            AuthRoutes["Auth Routes\nserver/routes/auth.js"]:::backend
            AdminRoutes["Admin Routes\nserver/routes/admin.js"]:::backend
            StudentRoutes["Student Routes\nserver/routes/students.js"]:::backend
            ItemRoutes["Item Routes\nserver/routes/items.js"]:::backend
            OrderRoutes["Order Routes\nserver/routes/orders.js"]:::backend
            ComplaintRoutes["Complaint Routes\nserver/routes/complaints.js"]:::backend
            UserRoutes["User Routes\nserver/routes/users.js"]:::backend
        end
        subgraph "Controllers"
            direction TB
            AuthCtrl["Auth Controller\nserver/controllers/authController.js"]:::backend
            AdminCtrl["Admin Controller\nserver/controllers/adminController.js"]:::backend
            StudentCtrl["Student Controller\nserver/controllers/studentController.js"]:::backend
            ItemCtrl["Item Controller\nserver/controllers/itemController.js"]:::backend
            OrderCtrl["Order Controller\nserver/controllers/orderController.js"]:::backend
            ComplaintCtrl["Complaint Controller\nserver/controllers/complaintController.js"]:::backend
            UserCtrl["User Controller\nserver/controllers/userController.js"]:::backend
        end
        subgraph "Models"
            direction TB
            UserModel["User Model\nserver/models/User.js"]:::database
            StudentModel["Student Model\nserver/models/Student.js"]:::database
            HallModel["Hall Model\nserver/models/Hall.js"]:::database
            ItemModel["Item Model\nserver/models/Item.js"]:::database
            OrderModel["Order Model\nserver/models/Order.js"]:::database
            ComplaintModel["Complaint Model\nserver/models/Complaint.js"]:::database
        end
        subgraph "Utilities"
            direction TB
            CSVParser["CSV Parser\nserver/utils/csvParser.js"]:::backend
            EmailSvc["Email Service\nserver/utils/emailService.js"]:::backend
            HelpersBE["Helpers & Key Gen\nserver/utils/*.js"]:::backend
        end
        UploadDir["File Storage\nserver/uploads"]:::backend
    end

    %% Database and External
    MongoDB["MongoDB Database"]:::database
    EmailServer["SMTP Email Service"]:::external

    %% Client Flow
    User -->|uses| SPA
    SPA -->|renders| Main
    Main --> AppShell
    AppShell --> Pages
    Pages --> Components
    SPA --> Contexts
    SPA --> Hooks
    SPA --> Services
    SPA --> UtilsFE
    SPA --> Styles

    %% API Calls
    Services -->|HTTP API Calls| ServerEntry

    %% Server Flow
    ServerEntry --> Config
    ServerEntry --> AuthMW
    ServerEntry --> UploadMW
    ServerEntry --> ValMW
    AuthMW --> Routes
    UploadMW --> Routes
    ValMW --> Routes
    Routes --> Controllers
    Controllers --> Models
    Controllers --> CSVParser
    Controllers --> EmailSvc
    UploadMW --> UploadDir

    %% Data storage
    Models --> MongoDB
    CSVParser --> StudentModel
    EmailSvc --> EmailServer

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef database fill:#9370DB,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px

    %% Click Events
    click Main "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/main.jsx"
    click AppShell "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/App.jsx"
    click Pages "https://github.com/harilakshman25/kgp-mess-hub/tree/main/client/src/pages/"
    click Components "https://github.com/harilakshman25/kgp-mess-hub/tree/main/client/src/components/"
    click Contexts "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/context/AuthContext.jsx"
    click Contexts "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/context/CartContext.jsx"
    click Contexts "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/context/ThemeContext.jsx"
    click Hooks "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/hooks/useApi.js"
    click Hooks "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/hooks/useAuth.js"
    click Hooks "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/hooks/useLocalStorage.js"
    click Services "https://github.com/harilakshman25/kgp-mess-hub/tree/main/client/src/services/"
    click UtilsFE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/utils/api.js"
    click UtilsFE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/utils/constants.js"
    click UtilsFE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/utils/helpers.js"
    click UtilsFE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/utils/validation.js"
    click Styles "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/tailwind.config.js"
    click Styles "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/vite.config.js"
    click Styles "https://github.com/harilakshman25/kgp-mess-hub/blob/main/client/src/index.css"
    click Styles "https://github.com/harilakshman25/kgp-mess-hub/tree/main/client/src/styles/"

    click ServerEntry "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/server.js"
    click Config "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/config/db.js"
    click Config "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/config/keys.js"
    click AuthMW "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/middleware/auth.js"
    click UploadMW "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/middleware/upload.js"
    click ValMW "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/middleware/validation.js"
    click AuthRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/auth.js"
    click AdminRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/admin.js"
    click StudentRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/students.js"
    click ItemRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/items.js"
    click OrderRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/orders.js"
    click ComplaintRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/complaints.js"
    click UserRoutes "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/routes/users.js"
    click AuthCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/authController.js"
    click AdminCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/adminController.js"
    click StudentCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/studentController.js"
    click ItemCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/itemController.js"
    click OrderCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/orderController.js"
    click ComplaintCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/complaintController.js"
    click UserCtrl "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/controllers/userController.js"
    click UserModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/User.js"
    click StudentModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/Student.js"
    click HallModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/Hall.js"
    click ItemModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/Item.js"
    click OrderModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/Order.js"
    click ComplaintModel "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/models/Complaint.js"
    click CSVParser "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/utils/csvParser.js"
    click EmailSvc "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/utils/emailService.js"
    click HelpersBE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/utils/generateKeys.js"
    click HelpersBE "https://github.com/harilakshman25/kgp-mess-hub/blob/main/server/utils/helpers.js"
    click UploadDir "https://github.com/harilakshman25/kgp-mess-hub/tree/main/server/uploads"
```
