# tsujit74/kharchamate architecture

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

- Interactive diagram: https://gitdiagram.com/tsujit74/kharchamate
- Repository: https://github.com/tsujit74/kharchamate

## Overview

KharchaMate lets people form shared-expense groups, record and split costs, inspect balances, and settle what they owe; admins also manage users, groups, announcements, and support. The main flow runs from the Next.js interface through API services and Express routes/controllers to MongoDB-backed models. Settlement validation and group PDF reporting are distinct backend stages. The README documents the core workflow; sampled source confirms representative API dispatch, data access, and settlement logic, but not every frontend-to-service connection.

Main entry points: [`backend/server.js`](https://github.com/tsujit74/kharchamate/blob/main/backend/server.js) (Express API), [`backend/controllers/adminController.js`](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/adminController.js) (Admin operations), [`backend/models/Group.js`](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Group.js) (Groups), [`frontend/app/services/api.ts`](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/services/api.ts) (API services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_group_ui["Groups and expenses<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard and insights<br/>[page.tsx]"]
  node_settlement_ui["Settlement requests<br/>[page.tsx]"]
  node_auth_ui["Authentication<br/>[page.tsx]"]
  node_api_services["API services<br/>[api.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
end

subgraph group_api["API and business logic"]
  node_server["Express API<br/>[server.js]"]
  node_group_routes["Group routes<br/>[groupRoutes.js]"]
  node_expense_routes["Expense routes<br/>[expenseRoutes.js]"]
  node_balance_routes["Balance routes<br/>[blanceRoutes.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_group_controller["Group operations<br/>[groupController.js]"]
  node_expense_controller["Expense operations"]
  node_settlement_controller["Settlement operations"]
  node_settlement_logic["Payment validation"]
  node_report_controller["Group PDF report"]
end

subgraph group_data["Persistent data"]
  node_group_model["Groups<br/>[Group.js]"]
  node_expense_model["Expenses<br/>[Expense.js]"]
  node_settlement_model["Settlements<br/>[Settlement.js]"]
  node_user_model["Users<br/>[User.js]"]
  node_announcement_model["Announcements<br/>[Announcement.js]"]
  node_ticket_model["Support tickets<br/>[Ticket.js]"]
end

subgraph group_admin["Administration"]
  node_admin_routes["Admin routes<br/>[adminRoutes.js]"]
  node_admin_controller["Admin operations<br/>[adminController.js]"]
end

node_person(("Group member"))
node_administrator(("Administrator"))
node_mongo[("MongoDB")]

node_person -->|"manages costs"| node_group_ui
node_person -->|"reviews balances"| node_dashboard_ui
node_person -->|"settles payments"| node_settlement_ui
node_person -->|"signs in"| node_auth_ui
node_group_ui -->|"requests group data"| node_api_services
node_dashboard_ui -->|"loads summaries"| node_api_services
node_settlement_ui -->|"requests payments"| node_api_services
node_auth_ui -->|"submits credentials"| node_auth_service
node_auth_service -->|"sends auth requests"| node_api_services
node_api_services -->|"calls API"| node_server
node_server -->|"dispatches groups"| node_group_routes
node_server -->|"dispatches expenses"| node_expense_routes
node_server -->|"dispatches balances"| node_balance_routes
node_server -->|"dispatches auth"| node_auth_routes
node_server -->|"dispatches admin"| node_admin_routes
node_group_routes -->|"invokes handlers"| node_group_controller
node_group_routes -->|"invokes report"| node_report_controller
node_expense_routes -->|"invokes handlers"| node_expense_controller
node_balance_routes -->|"invokes handlers"| node_settlement_controller
node_group_controller -->|"reads and writes"| node_group_model
node_expense_controller -->|"reads groups"| node_group_model
node_expense_controller -->|"reads and writes"| node_expense_model
node_settlement_controller -->|"validates payments"| node_settlement_logic
node_settlement_logic -->|"checks membership"| node_group_model
node_settlement_logic -->|"reads expenses"| node_expense_model
node_settlement_logic -->|"reads payments"| node_settlement_model
node_settlement_controller -->|"reads and writes"| node_settlement_model
node_report_controller -->|"loads group"| node_group_model
node_report_controller -->|"loads expenses"| node_expense_model
node_report_controller -->|"reads settlements"| node_settlement_model
node_administrator -->|"manages platform"| node_admin_routes
node_admin_routes -->|"invokes handlers"| node_admin_controller
node_admin_controller -->|"reads and writes"| node_user_model
node_admin_controller -->|"reads and writes"| node_group_model
node_admin_controller -->|"reads expenses"| node_expense_model
node_admin_controller -->|"manages announcements"| node_announcement_model
node_admin_controller -->|"manages tickets"| node_ticket_model
node_group_model -->|"persists records"| node_mongo
node_expense_model -->|"persists records"| node_mongo
node_settlement_model -->|"persists records"| node_mongo
node_user_model -->|"persists records"| node_mongo
node_announcement_model -->|"persists records"| node_mongo
node_ticket_model -->|"persists records"| node_mongo

click node_group_ui "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/groups/%5BgroupId%5D/page.tsx"
click node_dashboard_ui "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/dashboard/page.tsx"
click node_settlement_ui "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/settlement-requests/page.tsx"
click node_auth_ui "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/auth/page.tsx"
click node_api_services "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/services/api.ts"
click node_auth_service "https://github.com/tsujit74/kharchamate/blob/main/frontend/app/services/auth.service.ts"
click node_server "https://github.com/tsujit74/kharchamate/blob/main/backend/server.js"
click node_group_routes "https://github.com/tsujit74/kharchamate/blob/main/backend/routes/groupRoutes.js"
click node_expense_routes "https://github.com/tsujit74/kharchamate/blob/main/backend/routes/expenseRoutes.js"
click node_balance_routes "https://github.com/tsujit74/kharchamate/blob/main/backend/routes/blanceRoutes.js"
click node_auth_routes "https://github.com/tsujit74/kharchamate/blob/main/backend/routes/authRoutes.js"
click node_group_controller "https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/groupController.js"
click node_expense_controller "https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/expenseController.js"
click node_settlement_controller "https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/settlementController.js"
click node_settlement_logic "https://github.com/tsujit74/kharchamate/blob/main/backend/service/settlementService.js"
click node_report_controller "https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/groupReportController.js"
click node_admin_routes "https://github.com/tsujit74/kharchamate/blob/main/backend/routes/adminRoutes.js"
click node_admin_controller "https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/adminController.js"
click node_group_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/Group.js"
click node_expense_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/Expense.js"
click node_settlement_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/Settlement.js"
click node_user_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/User.js"
click node_announcement_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/Announcement.js"
click node_ticket_model "https://github.com/tsujit74/kharchamate/blob/main/backend/models/Ticket.js"

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_group_ui,node_dashboard_ui,node_settlement_ui,node_auth_ui,node_api_services,node_auth_service toneBlue
class node_server,node_group_routes,node_expense_routes,node_balance_routes,node_auth_routes,node_group_controller,node_expense_controller,node_settlement_controller,node_settlement_logic,node_report_controller,node_mongo toneAmber
class node_group_model,node_expense_model,node_settlement_model,node_user_model,node_announcement_model,node_ticket_model toneMint
class node_admin_routes,node_admin_controller toneRose
class node_person,node_administrator toneIndigo
```

## Components

### Web application

- [Groups and expenses](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/groups/%5BgroupId%5D/page.tsx): `frontend/app/groups/[groupId]/page.tsx`
- [Dashboard and insights](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Settlement requests](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/settlement-requests/page.tsx): `frontend/app/settlement-requests/page.tsx`
- [Authentication](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/auth/page.tsx): `frontend/app/auth/page.tsx`
- [API services](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/services/api.ts): `frontend/app/services/api.ts`
- [Auth service](https://github.com/tsujit74/kharchamate/blob/main/frontend/app/services/auth.service.ts): `frontend/app/services/auth.service.ts`

### API and business logic

- [Express API](https://github.com/tsujit74/kharchamate/blob/main/backend/server.js): `backend/server.js`
- [Group routes](https://github.com/tsujit74/kharchamate/blob/main/backend/routes/groupRoutes.js): `backend/routes/groupRoutes.js`
- [Expense routes](https://github.com/tsujit74/kharchamate/blob/main/backend/routes/expenseRoutes.js): `backend/routes/expenseRoutes.js`
- [Balance routes](https://github.com/tsujit74/kharchamate/blob/main/backend/routes/blanceRoutes.js): `backend/routes/blanceRoutes.js`
- [Auth routes](https://github.com/tsujit74/kharchamate/blob/main/backend/routes/authRoutes.js): `backend/routes/authRoutes.js`
- [Group operations](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/groupController.js): `backend/controllers/groupController.js`
- [Expense operations](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/expenseController.js): `backend/controllers/expenseController.js`
- [Settlement operations](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/settlementController.js): `backend/controllers/settlementController.js`
- [Payment validation](https://github.com/tsujit74/kharchamate/blob/main/backend/service/settlementService.js): `backend/service/settlementService.js`
- [Group PDF report](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/groupReportController.js): `backend/controllers/groupReportController.js`

### Persistent data

- [Groups](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Group.js): `backend/models/Group.js`
- [Expenses](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Expense.js): `backend/models/Expense.js`
- [Settlements](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Settlement.js): `backend/models/Settlement.js`
- [Users](https://github.com/tsujit74/kharchamate/blob/main/backend/models/User.js): `backend/models/User.js`
- [Announcements](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Announcement.js): `backend/models/Announcement.js`
- [Support tickets](https://github.com/tsujit74/kharchamate/blob/main/backend/models/Ticket.js): `backend/models/Ticket.js`

### Administration

- [Admin routes](https://github.com/tsujit74/kharchamate/blob/main/backend/routes/adminRoutes.js): `backend/routes/adminRoutes.js`
- [Admin operations](https://github.com/tsujit74/kharchamate/blob/main/backend/controllers/adminController.js): `backend/controllers/adminController.js`

### Other components

- **Group member**
- **Administrator**
- **MongoDB**

## Connections

- Group member → Groups and expenses: manages costs
- Group member → Dashboard and insights: reviews balances
- Group member → Settlement requests: settles payments
- Group member → Authentication: signs in
- Groups and expenses → API services: requests group data
- Dashboard and insights → API services: loads summaries
- Settlement requests → API services: requests payments
- Authentication → Auth service: submits credentials
- Auth service → API services: sends auth requests
- API services → Express API: calls API
- Express API → Group routes: dispatches groups
- Express API → Expense routes: dispatches expenses
- Express API → Balance routes: dispatches balances
- Express API → Auth routes: dispatches auth
- Express API → Admin routes: dispatches admin
- Group routes → Group operations: invokes handlers
- Group routes → Group PDF report: invokes report
- Expense routes → Expense operations: invokes handlers
- Balance routes → Settlement operations: invokes handlers
- Group operations → Groups: reads and writes
- Expense operations → Groups: reads groups
- Expense operations → Expenses: reads and writes
- Settlement operations → Payment validation: validates payments
- Payment validation → Groups: checks membership
- Payment validation → Expenses: reads expenses
- Payment validation → Settlements: reads payments
- Settlement operations → Settlements: reads and writes
- Group PDF report → Groups: loads group
- Group PDF report → Expenses: loads expenses
- Group PDF report → Settlements: reads settlements
- Administrator → Admin routes: manages platform
- Admin routes → Admin operations: invokes handlers
- Admin operations → Users: reads and writes
- Admin operations → Groups: reads and writes
- Admin operations → Expenses: reads expenses
- Admin operations → Announcements: manages announcements
- Admin operations → Support tickets: manages tickets
- Groups → MongoDB: persists records
- Expenses → MongoDB: persists records
- Settlements → MongoDB: persists records
- Users → MongoDB: persists records
- Announcements → MongoDB: persists records
- Support tickets → MongoDB: persists records