How yameeshnayak04/mess-hub works
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: routes Routes · controllers Controllers · main.dart Flutter app · customer_shell.dart Customer shell
Components 22
Flutter app
Client-side customer and manager experiences.
- Flutter app · Cross-platform Flutter client for customers and managers.
frontend/lib/main.dart - Core services · Centralized API, routing, storage, location, theme, and shared UI.
frontend/lib/core - Auth flow · Login, registration, splash, and session orchestration.
frontend/lib/features/auth - Customer shell · Customer-facing navigation and feature grouping.
frontend/lib/features/customer/customer_shell.dart - Manager shell · Manager-facing navigation and feature grouping.
frontend/lib/features/manager/manager_shell.dart - Discovery · Nearby mess discovery and mess detail views.
frontend/lib/features/customer/discover - Membership · Attendance, leave, billing, and review workflows.
frontend/lib/features/customer/membership - Profile · Customer profile and account views.
frontend/lib/features/customer/profile - Dashboard · Manager summary and operational dashboard.
frontend/lib/features/manager/home - Manager tools · Member, menu, payment, profile, and kiosk management.
frontend/lib/features/manager
Express API
Server-side domain logic, persistence, and operational workflows.
- Express API · HTTP server bootstrap and API composition.
backend/server.js - Routes · Request boundary for auth, mess, membership, attendance, billing, leave, review, and user endpoints.
backend/routes - Controllers · Thin request handlers that coordinate domain operations.
backend/controllers - Middleware · Auth, validation, schema checks, and uploads.
backend/middleware - Domain models · Persistent entities for users, messes, memberships, attendance, leave, bills, menus, and reviews.
backend/models - Billing logic · Monthly bill calculation and bill-generation support.
backend/utils/billCalculation.js - Jobs · Automated absence handling and billing jobs.
backend/jobs - Scripts · Backfill, recalc, and monthly bill generation utilities.
backend/scripts - Uploads · Server-side asset storage for mess images and payment proofs.
backend/uploads
Operations
Scheduled jobs, scripts, testing, and deployment support.
- k6 tests · Performance and smoke flows for auth, discovery, attendance, billing, membership, and manager dashboard.
k6-tests - Cron config · Repository-level cron schedule wiring for background execution.
.github/workflows/cron.txt - Render config · Deployment/runtime configuration for hosting and scheduled execution.
render.yaml
Connections 26
- 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.