# prantascode/meal-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/prantascode/meal-management-system
- Repository: https://github.com/prantascode/meal-management-system

## Overview

1. **System shape**
   - This is a two-part full-stack application: a **Spring Boot backend** and a **React + TypeScript frontend**.
   - The backend exposes business APIs for meal/mess operations; the frontend is a Vite-based SPA that consumes those APIs through an Axios client.

2. **Core domain**
   - The business model is centered on a single mess or meal organization and its participants.
   - Main persisted entities are **Member, Mess, MealEntry, Deposit, Expense, MealRequest, MonthlyReport, RefreshToken**, plus OAuth-related state/token records.

3. **Backend layering**
   - The Java backend follows a standard layered structure:
     - **Controller**: HTTP endpoints and request/response handling.
     - **Service**: business rules and orchestration.
     - **Repository**: Spring Data JPA persistence.
     - **Entity**: database models.
     - **Dto**: API input/output contracts.
     - **Security/Config**: authentication and external auth setup.

4. **Authentication and authorization boundary**
   - Security is handled with **Spring Security + JWT**.
   - `JwtFilter` sits in the request pipeline to validate tokens before protected controllers execute.
   - `CustomUserDetailsService` and `MemberUserDetails` connect application users to Spring Security.
   - Refresh token support is explicit via `RefreshToken`, `RefreshTokenRepository`, and `RefreshTokenService`.

5. **User roles and access model**
   - The readme indicates role separation for **Admin, Manager, and Member**, and the controller set reflects that multi-role workflow.
   - Role-specific access likely determines who can create messes, manage members, record meals, enter deposits/expenses, and view reports.

6. **Operational workflow APIs**
   - Business controllers are organized by function:
     - **MealController** for meal entry management.
     - **DepositController** and **ExpenseController** for financial inputs.
     - **MemberController** for member lifecycle and profile data.
     - **MealRequestController** for member meal-add requests.
     - **ReportController** for monthly summaries and balances.
   - Each controller delegates to a service that persists through the corresponding repository.

7. **Financial and reporting flow**
   - The system aggregates **meals, deposits, and expenses** into monthly reporting.
   - `ReportService` and `MonthlyReport` indicate a derived-data layer rather than only raw transactions.
   - Meal rate, member-wise balance, and monthly calculations are central outputs consumed by both admin and member views.

8. **Member self-service flow**
   - Members can log in, inspect their meal/deposit/report data, submit meal requests, and update profile/password.
   - The frontend has dedicated pages for **UpdateProfile**, **UpdatePassword**, and dashboard-style read views, showing this is not purely admin-operated.

9. **External integrations**
   - **GmailSenderService** is used to send credentials or notifications by email.
   - **GoogleOAuthConfig**, `GoogleOAuthController`, and `GoogleOAuthCallbackController` show a separate Google OAuth login/integration path.
   - `AdminGoogleToken` and `GoogleOAuthState` suggest the app stores OAuth tokens/state server-side for secure callback handling.
   - `AiController` indicates AI-driven insights, and the README identifies **Gemini API** as the external AI service.

10. **Frontend architecture**
   - The UI is a React SPA with feature pages for **Dashboard, Login, Members, Meals, Deposits, Expenses, MealRequests, Reports, CreateMess**.
   - `Layout` and `Sidebar` provide the shared shell/navigation, while `AiInsights` is a reusable component for the AI feature.
   - `axiosInstance.ts` is the key integration boundary between UI and backend, likely attaching auth headers and centralizing API calls.

11. **Data exchange contract**
   - The backend uses **DTOs** for request/response shaping rather than exposing entities directly.
   - Examples include login/register DTOs, meal/deposit/expense DTOs, profile update DTOs, report DTOs, and meal request response DTOs.
   - This implies a clean API boundary between UI and persistence models.

12. **Persistence and runtime**
   - The app uses **MySQL** via **Spring Data JPA / Hibernate** on the backend.
   - Runtime/configuration is Maven-based (`pom.xml`, Maven wrapper) with environment values in `application.properties`.
   - The frontend is built with **Vite**, **Tailwind CSS**, and TypeScript.

13. **End-to-end request path**
   - Typical flow: browser action → React page/component → Axios call → Spring controller → service logic → repository/database → DTO response → UI update.
   - Authenticated calls pass through JWT validation first; sensitive features are gated by role and token checks.

14. **Repository maturity note**
   - The repository is clearly organized as a production-style monolith with a separate SPA frontend.
   - Test coverage appears minimal in the tree, with only the default Spring Boot application test present, so the architecture is driven primarily by the runtime layers above.

Main entry points: [`MealManagement/src/main/java/com/pranta/MealManagement/Controller`](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Controller) (API controllers), [`MealManagement/src/main/java/com/pranta/MealManagement/Repository`](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Repository) (Repositories), [`MealManagement/src/main/java/com/pranta/MealManagement/Security`](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Security) (Auth flow), [`meal-management-ui/src/api/axiosInstance.ts`](https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/api/axiosInstance.ts) (Axios client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Spring Boot backend"]
  node_web_api["API controllers<br/>spring mvc"]
  node_auth_flow["Auth flow<br/>security"]
  node_auth_cfg["Security config<br/>spring config"]
  node_auth_service["User details<br/>security service"]
  node_member_service["Member service<br/>domain service<br/>[MemberService.java]"]
  node_meal_service["Meal service<br/>domain service<br/>[MealService.java]"]
  node_finance_service["Finance services<br/>domain service"]
  node_request_service["Request service<br/>domain service"]
  node_report_service["Report service<br/>reporting<br/>[ReportService.java]"]
  node_external_integrations["External integrations<br/>integration layer"]
  node_domain_models[("Domain entities<br/>jpa entities")]
  node_repositories["Repositories<br/>spring data"]
  node_dtos["DTO contracts<br/>api contracts"]
  node_app_runtime(("App runtime<br/>spring boot app"))
end

subgraph group_frontend["React frontend"]
  node_ui_shell["UI shell<br/>react shell<br/>[Layout.tsx]"]
  node_ui_pages["Feature pages<br/>react views"]
  node_ui_ai["AI insights<br/>react component<br/>[AiInsights.tsx]"]
  node_ui_api["Axios client<br/>api client<br/>[axiosInstance.ts]"]
end

node_ui_shell -->|"navigates"| node_ui_pages
node_ui_pages -->|"calls"| node_ui_api
node_ui_ai -->|"calls"| node_ui_api
node_ui_api -->|"HTTP"| node_web_api
node_web_api -->|"protects"| node_auth_flow
node_auth_flow -->|"configured by"| node_auth_cfg
node_auth_flow -->|"loads users"| node_auth_service
node_web_api -->|"maps to"| node_dtos
node_web_api -->|"delegates"| node_member_service
node_web_api -->|"delegates"| node_meal_service
node_web_api -->|"delegates"| node_finance_service
node_web_api -->|"delegates"| node_request_service
node_web_api -->|"delegates"| node_report_service
node_web_api -->|"delegates"| node_external_integrations
node_member_service -->|"persists via"| node_repositories
node_meal_service -->|"persists via"| node_repositories
node_finance_service -->|"persists via"| node_repositories
node_request_service -->|"persists via"| node_repositories
node_report_service -->|"reads via"| node_repositories
node_repositories -->|"stores"| node_domain_models
node_external_integrations -->|"uses state"| node_domain_models
node_app_runtime -->|"boots"| node_web_api
node_app_runtime -->|"loads"| node_auth_flow

click node_ui_shell "https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/components/Layout.tsx"
click node_ui_pages "https://github.com/prantascode/meal-management-system/tree/main/meal-management-ui/src/pages"
click node_ui_ai "https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/components/AiInsights.tsx"
click node_ui_api "https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/api/axiosInstance.ts"
click node_web_api "https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Controller"
click node_auth_flow "https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Security"
click node_auth_cfg "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Config/SecurityConfig.java"
click node_auth_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Config/CustomUserDetailsService.java"
click node_member_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MemberService.java"
click node_meal_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MealService.java"
click node_finance_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/DepositService.java"
click node_request_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MealRequestService.java"
click node_report_service "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/ReportService.java"
click node_external_integrations "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/GmailSenderService.java"
click node_domain_models "https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Entity"
click node_repositories "https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Repository"
click node_dtos "https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Dtos"
click node_app_runtime "https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/MealManagementApplication.java"

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_web_api,node_auth_flow,node_auth_cfg,node_auth_service,node_member_service,node_meal_service,node_finance_service,node_request_service,node_report_service,node_external_integrations,node_domain_models,node_repositories,node_dtos,node_app_runtime toneBlue
class node_ui_shell,node_ui_pages,node_ui_ai,node_ui_api toneAmber
```

## Components

### Spring Boot backend

Java monolith exposing business APIs, security, persistence, and integrations.

- [API controllers](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Controller): spring mvc · HTTP boundary for auth, members, meals, finances, reports, AI, and Google OAuth callbacks. · `MealManagement/src/main/java/com/pranta/MealManagement/Controller`
- [Auth flow](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Security): security · JWT authentication, user-details mapping, refresh tokens, and security configuration. · `MealManagement/src/main/java/com/pranta/MealManagement/Security`
- [Security config](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Config/SecurityConfig.java): spring config · Spring Security and OAuth configuration for protected routes and external login. · `MealManagement/src/main/java/com/pranta/MealManagement/Config/SecurityConfig.java`
- [User details](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Config/CustomUserDetailsService.java): security service · Bridges application members to Spring Security principals. · `MealManagement/src/main/java/com/pranta/MealManagement/Config/CustomUserDetailsService.java`
- [Member service](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MemberService.java): domain service · Manages registration, profile updates, and member lifecycle. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/MemberService.java`
- [Meal service](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MealService.java): domain service · Handles meal entry operations and meal-related business rules. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/MealService.java`
- [Finance services](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/DepositService.java): domain service · Deposit and expense workflows that feed financial state and reports. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/DepositService.java`
- [Request service](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/MealRequestService.java): domain service · Processes member meal requests and approval state. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/MealRequestService.java`
- [Report service](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/ReportService.java): reporting · Builds monthly summaries, balances, and derived mess reporting data. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/ReportService.java`
- [External integrations](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/Service/GmailSenderService.java): integration layer · Gmail notifications, Google OAuth, and Gemini-backed AI features. · `MealManagement/src/main/java/com/pranta/MealManagement/Service/GmailSenderService.java`
- [Domain entities](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Entity): jpa entities · Persisted core records for members, messes, meals, deposits, expenses, requests, reports, and tokens. · `MealManagement/src/main/java/com/pranta/MealManagement/Entity`
- [Repositories](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Repository): spring data · Persistence boundary for querying and storing domain entities. · `MealManagement/src/main/java/com/pranta/MealManagement/Repository`
- [DTO contracts](https://github.com/prantascode/meal-management-system/tree/main/MealManagement/src/main/java/com/pranta/MealManagement/Dtos): api contracts · Request and response shapes for auth, profile, meals, finances, requests, and reports. · `MealManagement/src/main/java/com/pranta/MealManagement/Dtos`
- [App runtime](https://github.com/prantascode/meal-management-system/blob/main/MealManagement/src/main/java/com/pranta/MealManagement/MealManagementApplication.java): spring boot app · Main Spring Boot application entry point and runtime bootstrap. · `MealManagement/src/main/java/com/pranta/MealManagement/MealManagementApplication.java`

### React frontend

Vite-based SPA that consumes backend APIs through a shared Axios client.

- [UI shell](https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/components/Layout.tsx): react shell · Shared app layout and navigation for the SPA. · `meal-management-ui/src/components/Layout.tsx`
- [Feature pages](https://github.com/prantascode/meal-management-system/tree/main/meal-management-ui/src/pages): react views · Dashboard and workflow pages for login, members, meals, finances, requests, reports, profile updates, and mess creation. · `meal-management-ui/src/pages`
- [AI insights](https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/components/AiInsights.tsx): react component · Reusable UI for displaying AI-generated summaries or suggestions. · `meal-management-ui/src/components/AiInsights.tsx`
- [Axios client](https://github.com/prantascode/meal-management-system/blob/main/meal-management-ui/src/api/axiosInstance.ts): api client · Central HTTP client used by the SPA to call backend endpoints and attach auth context. · `meal-management-ui/src/api/axiosInstance.ts`

## Connections

- UI shell → Feature pages: navigates · Shell routes users to feature pages.
- Feature pages → Axios client: calls · Pages fetch and mutate data through the shared client.
- AI insights → Axios client: calls · AI UI requests backend insights through the API client.
- Axios client → API controllers: HTTP · SPA requests reach backend controllers.
- API controllers → Auth flow: protects · Controllers rely on JWT validation and security configuration.
- Auth flow → Security config: configured by · Security filter chain and OAuth wiring are defined here.
- Auth flow → User details: loads users · Spring Security resolves member principals through custom user details.
- API controllers → DTO contracts: maps to · Incoming and outgoing payloads are shaped with DTOs.
- API controllers → Member service: delegates · Member endpoints call the member service.
- API controllers → Meal service: delegates · Meal endpoints call the meal service.
- API controllers → Finance services: delegates · Deposit and expense endpoints call finance services.
- API controllers → Request service: delegates · Meal request endpoints call the request service.
- API controllers → Report service: delegates · Report endpoints call reporting logic.
- API controllers → External integrations: delegates · Auth, email, OAuth, and AI endpoints bridge to integrations.
- Member service → Repositories: persists via · Member changes are stored through repositories.
- Meal service → Repositories: persists via · Meal entries are stored through repositories.
- Finance services → Repositories: persists via · Deposits and expenses are stored through repositories.
- Request service → Repositories: persists via · Meal requests are stored through repositories.
- Report service → Repositories: reads via · Monthly reporting aggregates persisted transactions and reports.
- Repositories → Domain entities: stores · Repositories manage the JPA entities.
- External integrations → Domain entities: uses state · OAuth tokens and state records are persisted as entities.
- App runtime → API controllers: boots · Application startup activates controllers and supporting beans.
- App runtime → Auth flow: loads · Security components are wired at application startup.