# yameeshnayak04/mess-hub architecture

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

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

## Overview

1. **System shape**
   Mess Hub is a two-tier product: a **Flutter client app** and a **Node.js/Express API** backed by **MongoDB/Mongoose**. The backend owns business rules and persistence; the Flutter app owns role-specific UI and local state.

2. **Primary user surfaces**
   The frontend is split into two main experience shells: **customer** and **manager**. Customer screens cover discovery, membership, attendance, leave, billing, reviews, and profile. Manager screens cover dashboard, member management, menu editing, payments, mess profile, mess creation, and kiosk operations.

3. **Frontend architecture boundary**
   The Flutter app follows a **clean architecture** layout: shared cross-cutting code sits under `lib/core`, while each feature has its own `providers`, `repositories`, and `screens`. Riverpod is used for state and orchestration; repositories are the boundary to the backend API.

4. **Frontend API/data flow**
   Network access is centralized through **Dio** and an **auth interceptor** that attaches JWT credentials. Shared services include storage, routing, location, and theming. The UI does not talk to the backend directly; it goes through feature repositories and providers.

5. **Backend structure**
   The backend is organized in classic Express layers: **routes → controllers → models**, with separate middleware for auth, validation, schemas, and uploads. This keeps request handling thin while pushing domain logic into controllers, services, and utility modules.

6. **Core domain model**
   The main persistent entities are `User`, `Mess`, `Membership`, `Attendance`, `Leave`, `Bill`, `Menu`, and `Review`. These model the platform’s main workflows: discovering a mess, joining it, tracking meals, applying leave, generating monthly bills, and collecting feedback.

7. **Role and permission boundary**
   Authentication is JWT-based, with password login and distinct **customer vs manager** permissions. The backend enforces access control in `middleware/auth.js`, while the frontend uses shell/navigation separation to keep manager and customer experiences distinct.

8. **Operational workflows**
   Automated operations are a major part of the architecture. There are backend **jobs** for attendance/absence handling and billing, plus **scripts** for backfilling attendance and recalculating/generating bills. A `cronRoutes` module and `.github/workflows/cron.txt` indicate scheduled execution outside the normal request path.

9. **Billing and attendance pipeline**
   Attendance is captured through the kiosk/attendance endpoints, then fed into billing logic in `utils/billCalculation.js` and monthly generation scripts/jobs. Leave records influence rebate eligibility, so billing is derived from multiple domain sources rather than a single table.

10. **Discovery and geospatial behavior**
   Mess discovery is a dedicated subsystem. The readme calls out nearby-mess search and the backend claims MongoDB geospatial queries, so location is part of the search boundary. On the client, location services and map-based UI support this discovery flow.

11. **File upload and media handling**
   Uploaded assets are handled server-side with Multer and stored under `backend/uploads`, including `mess-images` and likely payment proof images. This means media is a separate persistence path from the MongoDB domain records.

12. **Supporting systems**
   There is a dedicated **k6 load-testing** suite with flows for auth, discovery, attendance, billing, membership, and manager dashboard. Deployment is also likely wired for Render via `render.yaml`, making runtime scheduling and environment setup part of the repo’s operational architecture.

13. **What to draw in a diagram**
   The clearest diagram is: **Flutter customer/manager apps → Dio/JWT → Express routes/controllers → Mongoose models/MongoDB**, with side lanes for **file uploads**, **scheduled jobs/scripts**, and **k6 tests**. The key boundary is that all business rules and state transitions live on the backend, while the Flutter app is a feature-sliced presentation and API client.

Main entry points: [`backend/routes`](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/routes) (Routes), [`backend/controllers`](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/controllers) (Controllers), [`frontend/lib/main.dart`](https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/main.dart) (Flutter app), [`frontend/lib/features/customer/customer_shell.dart`](https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/features/customer/customer_shell.dart) (Customer shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Flutter app"]
  node_frontend_app["Flutter app<br/>mobile client<br/>[main.dart]"]
  node_frontend_core["Core services<br/>shared client core"]
  node_frontend_auth["Auth flow<br/>client auth"]
  node_frontend_customer_shell["Customer shell<br/>customer UX"]
  node_frontend_manager_shell["Manager shell<br/>manager UX<br/>[manager_shell.dart]"]
  node_frontend_discover["Discovery<br/>customer feature"]
  node_frontend_membership["Membership<br/>customer feature"]
  node_frontend_profile["Profile<br/>customer feature"]
  node_frontend_manager_home["Dashboard<br/>manager feature"]
  node_frontend_manager_ops["Manager tools<br/>manager feature"]
end

subgraph group_backend["Express API"]
  node_backend_api["Express API<br/>server entry<br/>[server.js]"]
  node_backend_routes["Routes"]
  node_backend_controllers["Controllers<br/>request handlers"]
  node_backend_middleware["Middleware<br/>cross-cutting server"]
  node_backend_models["Domain models<br/>mongoose models"]
  node_backend_billing["Billing logic<br/>domain service<br/>[billCalculation.js]"]
  node_backend_jobs["Jobs"]
  node_backend_scripts["Scripts"]
  node_backend_uploads[("Uploads<br/>media storage")]
end

subgraph group_ops["Operations"]
  node_ops_k6["k6 tests<br/>load testing"]
  node_ops_cron["Cron config<br/>scheduled ops<br/>[cron.txt]"]
  node_ops_render["Render config<br/>deployment<br/>[render.yaml]"]
end

node_frontend_app -->|"uses"| node_frontend_core
node_frontend_app -->|"starts with"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_customer_shell
node_frontend_app -->|"routes to"| node_frontend_manager_shell
node_frontend_customer_shell -->|"hosts"| node_frontend_discover
node_frontend_customer_shell -->|"hosts"| node_frontend_membership
node_frontend_customer_shell -->|"hosts"| node_frontend_profile
node_frontend_manager_shell -->|"hosts"| node_frontend_manager_home
node_frontend_manager_shell -->|"hosts"| node_frontend_manager_ops
node_frontend_discover -->|"calls API"| node_backend_routes
node_frontend_membership -->|"calls API"| node_backend_routes
node_frontend_manager_ops -->|"calls API"| node_backend_routes
node_backend_api -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_controllers
node_backend_controllers -->|"uses"| node_backend_middleware
node_backend_controllers -->|"persists via"| node_backend_models
node_backend_controllers -->|"uses"| node_backend_billing
node_backend_jobs -->|"updates"| node_backend_models
node_backend_scripts -.->|"mirrors"| node_backend_jobs
node_backend_scripts -->|"uses"| node_backend_billing
node_backend_middleware -->|"stores files"| node_backend_uploads
node_ops_k6 -.->|"exercises"| node_backend_routes
node_ops_cron -.->|"schedules"| node_backend_jobs
node_ops_render -.->|"deploys"| node_backend_api
node_backend_controllers -.->|"triggers"| node_backend_jobs
node_backend_routes -->|"guards"| node_backend_middleware

click node_frontend_app "https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/main.dart"
click node_frontend_core "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/core"
click node_frontend_auth "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/auth"
click node_frontend_customer_shell "https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/features/customer/customer_shell.dart"
click node_frontend_manager_shell "https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/features/manager/manager_shell.dart"
click node_frontend_discover "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/discover"
click node_frontend_membership "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/membership"
click node_frontend_profile "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/profile"
click node_frontend_manager_home "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/manager/home"
click node_frontend_manager_ops "https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/manager"
click node_backend_api "https://github.com/yameeshnayak04/mess-hub/blob/main/backend/server.js"
click node_backend_routes "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/routes"
click node_backend_controllers "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/controllers"
click node_backend_middleware "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/middleware"
click node_backend_models "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/models"
click node_backend_billing "https://github.com/yameeshnayak04/mess-hub/blob/main/backend/utils/billCalculation.js"
click node_backend_jobs "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/jobs"
click node_backend_scripts "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/scripts"
click node_backend_uploads "https://github.com/yameeshnayak04/mess-hub/tree/main/backend/uploads"
click node_ops_k6 "https://github.com/yameeshnayak04/mess-hub/tree/main/k6-tests"
click node_ops_cron "https://github.com/yameeshnayak04/mess-hub/blob/main/.github/workflows/cron.txt"
click node_ops_render "https://github.com/yameeshnayak04/mess-hub/blob/main/render.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_core,node_frontend_auth,node_frontend_customer_shell,node_frontend_manager_shell,node_frontend_discover,node_frontend_membership,node_frontend_profile,node_frontend_manager_home,node_frontend_manager_ops toneBlue
class node_backend_api,node_backend_routes,node_backend_controllers,node_backend_middleware,node_backend_models,node_backend_billing,node_backend_jobs,node_backend_scripts,node_backend_uploads toneAmber
class node_ops_k6,node_ops_cron,node_ops_render toneMint
```

## Components

### Flutter app

Client-side customer and manager experiences.

- [Flutter app](https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/main.dart): mobile client · Cross-platform Flutter client for customers and managers. · `frontend/lib/main.dart`
- [Core services](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/core): shared client core · Centralized API, routing, storage, location, theme, and shared UI. · `frontend/lib/core`
- [Auth flow](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/auth): client auth · Login, registration, splash, and session orchestration. · `frontend/lib/features/auth`
- [Customer shell](https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/features/customer/customer_shell.dart): customer UX · Customer-facing navigation and feature grouping. · `frontend/lib/features/customer/customer_shell.dart`
- [Manager shell](https://github.com/yameeshnayak04/mess-hub/blob/main/frontend/lib/features/manager/manager_shell.dart): manager UX · Manager-facing navigation and feature grouping. · `frontend/lib/features/manager/manager_shell.dart`
- [Discovery](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/discover): customer feature · Nearby mess discovery and mess detail views. · `frontend/lib/features/customer/discover`
- [Membership](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/membership): customer feature · Attendance, leave, billing, and review workflows. · `frontend/lib/features/customer/membership`
- [Profile](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/customer/profile): customer feature · Customer profile and account views. · `frontend/lib/features/customer/profile`
- [Dashboard](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/manager/home): manager feature · Manager summary and operational dashboard. · `frontend/lib/features/manager/home`
- [Manager tools](https://github.com/yameeshnayak04/mess-hub/tree/main/frontend/lib/features/manager): manager feature · Member, menu, payment, profile, and kiosk management. · `frontend/lib/features/manager`

### Express API

Server-side domain logic, persistence, and operational workflows.

- [Express API](https://github.com/yameeshnayak04/mess-hub/blob/main/backend/server.js): server entry · HTTP server bootstrap and API composition. · `backend/server.js`
- [Routes](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/routes): api routes · Request boundary for auth, mess, membership, attendance, billing, leave, review, and user endpoints. · `backend/routes`
- [Controllers](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/controllers): request handlers · Thin request handlers that coordinate domain operations. · `backend/controllers`
- [Middleware](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/middleware): cross-cutting server · Auth, validation, schema checks, and uploads. · `backend/middleware`
- [Domain models](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/models): mongoose models · Persistent entities for users, messes, memberships, attendance, leave, bills, menus, and reviews. · `backend/models`
- [Billing logic](https://github.com/yameeshnayak04/mess-hub/blob/main/backend/utils/billCalculation.js): domain service · Monthly bill calculation and bill-generation support. · `backend/utils/billCalculation.js`
- [Jobs](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/jobs): background jobs · Automated absence handling and billing jobs. · `backend/jobs`
- [Scripts](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/scripts): ops scripts · Backfill, recalc, and monthly bill generation utilities. · `backend/scripts`
- [Uploads](https://github.com/yameeshnayak04/mess-hub/tree/main/backend/uploads): media storage · Server-side asset storage for mess images and payment proofs. · `backend/uploads`

### Operations

Scheduled jobs, scripts, testing, and deployment support.

- [k6 tests](https://github.com/yameeshnayak04/mess-hub/tree/main/k6-tests): load testing · Performance and smoke flows for auth, discovery, attendance, billing, membership, and manager dashboard. · `k6-tests`
- [Cron config](https://github.com/yameeshnayak04/mess-hub/blob/main/.github/workflows/cron.txt): scheduled ops · Repository-level cron schedule wiring for background execution. · `.github/workflows/cron.txt`
- [Render config](https://github.com/yameeshnayak04/mess-hub/blob/main/render.yaml): deployment · Deployment/runtime configuration for hosting and scheduled execution. · `render.yaml`

## Connections

- Flutter app → Core services: uses · UI depends on shared API, routing, storage, location, and theme services.
- Flutter app → Auth flow: starts with · Authentication gates the client session.
- Flutter app → Customer shell: routes to · Customer role enters the customer shell.
- Flutter app → Manager shell: routes to · Manager role enters the manager shell.
- Customer shell → Discovery: hosts · Customer shell exposes discovery.
- Customer shell → Membership: hosts · Customer shell exposes membership workflows.
- Customer shell → Profile: hosts · Customer shell exposes profile management.
- Manager shell → Dashboard: hosts · Manager shell exposes dashboard.
- Manager shell → Manager tools: hosts · Manager shell exposes operational tools.
- Discovery → Routes: calls API · Discovery repositories talk to backend endpoints.
- Membership → Routes: calls API · Attendance, leave, billing, and review repositories talk to backend endpoints.
- Manager tools → Routes: calls API · Manager tools use backend endpoints for member, menu, payment, and kiosk actions.
- Express API → Routes: mounts · Server composes route modules.
- Routes → Controllers: delegates · Routes delegate request handling to controllers.
- Controllers → Middleware: uses · Controllers rely on auth, validation, schemas, and upload handling.
- Controllers → Domain models: persists via · Controllers read and write domain entities through Mongoose models.
- Controllers → Billing logic: uses · Billing controller and jobs rely on bill calculation utilities.
- Jobs → Domain models: updates · Background jobs operate on attendance and billing state.
- Scripts → Jobs: mirrors · Scripts implement operational maintenance flows similar to scheduled jobs.
- Scripts → Billing logic: uses · Bill generation and recalculation scripts reuse billing logic.
- Middleware → Uploads: stores files · Upload middleware writes media assets to the uploads path.
- k6 tests → Routes: exercises · Load tests target the API surface.
- Cron config → Jobs: schedules · Cron configuration drives background execution.
- Render config → Express API: deploys · Deployment config supports the runtime entrypoint.
- Controllers → Jobs: triggers · Operational flows can hand off to scheduled processing.
- Routes → Middleware: guards · Route layer is protected by auth and validation middleware.
