# malik-bilawal/campus-coin architecture

> Architecture diagram of the GitHub repository malik-bilawal/campus-coin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/malik-bilawal/campus-coin
- Repository: https://github.com/malik-bilawal/campus-coin

## Overview

Campus Coin is a student budgeting web app: users authenticate, record or import transactions, and review budgets, dashboards, reports, and spending guidance. Its Next.js client fronts an Express/Mongoose API; server controllers coordinate domain records and services. Major documented branches include AI insights/chat, voice, email-shared reports, notifications/realtime, bookmarks, tips, and administration. The graph reflects README capabilities and shown imports/calls; several client screens and server subsystems are unsampled, so their internal wiring is not asserted.

Main entry points: [`server/src/models`](https://github.com/malik-bilawal/campus-coin/tree/master/server/src/models) (Domain records), [`server/src/controllers/transaction.controller.js`](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/transaction.controller.js) (Transactions), [`server/src/services/notify.js`](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/notify.js) (Notifications), [`server/src/controllers/admin.controller.js`](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/admin.controller.js) (Admin tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Next.js app"]
  node_voice["Voice input"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API platform"]
  node_api_app["Express API<br/>[app.js]"]
  node_auth_flow["Authentication<br/>[auth.controller.js]"]
  node_auth_guard["Access control<br/>[auth.js]"]
  node_routes["API routes"]
end

subgraph group_finance["Budgeting domain"]
  node_transactions["Transactions"]
  node_budgets["Budgets"]
  node_categories["Categories"]
  node_dashboard["Dashboard"]
  node_reports["Reports"]
  node_records[("Domain records")]
end

subgraph group_assist["Guidance and voice"]
  node_ai_routes["AI endpoints<br/>[ai.routes.js]"]
  node_ai_services["AI services"]
  node_voice_service["Voice services<br/>[tts.service.js]"]
end

subgraph group_engagement["Engagement and admin"]
  node_notifications["Notifications<br/>[notify.js]"]
  node_realtime["Socket service<br/>[socket.js]"]
  node_admin["Admin tools"]
  node_mail["Email service<br/>[mail.service.js]"]
  node_tips["Daily tips<br/>[tipsEngine.js]"]
end

node_student(("Student"))

node_student -->|"uses"| node_web
node_web -.->|"requests data"| node_api_client
node_web -->|"offers voice input"| node_voice
node_api_client -->|"calls REST API"| node_api_app
node_api_app -->|"mounts routes"| node_routes
node_routes -->|"routes requests"| node_transactions
node_routes -->|"protects endpoints"| node_auth_guard
node_auth_flow -->|"reads and writes users"| node_records
node_auth_flow -->|"sends verification mail"| node_mail
node_transactions -->|"reads and writes transactions"| node_records
node_transactions -->|"suggests categories"| node_ai_services
node_transactions -->|"checks budget alerts"| node_budgets
node_transactions -->|"notifies user"| node_notifications
node_transactions -->|"emits transaction event"| node_realtime
node_budgets -.->|"uses budget records"| node_records
node_categories -.->|"uses category records"| node_records
node_dashboard -.->|"summarizes activity"| node_records
node_reports -->|"reads report data"| node_records
node_reports -->|"shares PDF by email"| node_mail
node_ai_routes -->|"dispatches AI requests"| node_ai_services
node_ai_routes -->|"loads categories"| node_records
node_voice_service -.->|"returns speech audio"| node_student
node_notifications -->|"stores notifications"| node_records
node_notifications -->|"emits updates"| node_realtime
node_admin -->|"manages platform data"| node_records
node_admin -->|"broadcasts announcements"| node_notifications
node_admin -->|"sends account notices"| node_mail
node_tips -->|"uses spending history"| node_records

click node_web "https://github.com/malik-bilawal/campus-coin/tree/master/client/src/app"
click node_voice "https://github.com/malik-bilawal/campus-coin/tree/master/client/src/lib/voice"
click node_api_client "https://github.com/malik-bilawal/campus-coin/blob/master/client/src/lib/api.js"
click node_api_app "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/app.js"
click node_auth_flow "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/auth.controller.js"
click node_auth_guard "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/middlewares/auth.js"
click node_routes "https://github.com/malik-bilawal/campus-coin/tree/master/server/src/routes"
click node_transactions "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/transaction.controller.js"
click node_budgets "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/budget.controller.js"
click node_categories "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/category.controller.js"
click node_dashboard "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/dashboard.controller.js"
click node_reports "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/report.controller.js"
click node_records "https://github.com/malik-bilawal/campus-coin/tree/master/server/src/models"
click node_ai_routes "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/routes/ai.routes.js"
click node_ai_services "https://github.com/malik-bilawal/campus-coin/tree/master/server/src/services/ai"
click node_voice_service "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/tts.service.js"
click node_notifications "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/notify.js"
click node_realtime "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/config/socket.js"
click node_admin "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/admin.controller.js"
click node_mail "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/mail.service.js"
click node_tips "https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/tipsEngine.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_web,node_voice,node_api_client toneBlue
class node_api_app,node_auth_flow,node_auth_guard,node_routes toneAmber
class node_transactions,node_budgets,node_categories,node_dashboard,node_reports,node_records toneMint
class node_ai_routes,node_ai_services,node_voice_service toneRose
class node_notifications,node_realtime,node_admin,node_mail,node_tips,node_student toneIndigo
```

## Components

### Web client

- [Next.js app](https://github.com/malik-bilawal/campus-coin/tree/master/client/src/app): `client/src/app`
- [Voice input](https://github.com/malik-bilawal/campus-coin/tree/master/client/src/lib/voice): `client/src/lib/voice`
- [API client](https://github.com/malik-bilawal/campus-coin/blob/master/client/src/lib/api.js): `client/src/lib/api.js`

### API platform

- [Express API](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/app.js): `server/src/app.js`
- [Authentication](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/auth.controller.js): `server/src/controllers/auth.controller.js`
- [Access control](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/middlewares/auth.js): `server/src/middlewares/auth.js`
- [API routes](https://github.com/malik-bilawal/campus-coin/tree/master/server/src/routes): `server/src/routes`

### Budgeting domain

- [Transactions](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/transaction.controller.js): `server/src/controllers/transaction.controller.js`
- [Budgets](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/budget.controller.js): `server/src/controllers/budget.controller.js`
- [Categories](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/category.controller.js): `server/src/controllers/category.controller.js`
- [Dashboard](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/dashboard.controller.js): `server/src/controllers/dashboard.controller.js`
- [Reports](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/report.controller.js): `server/src/controllers/report.controller.js`
- [Domain records](https://github.com/malik-bilawal/campus-coin/tree/master/server/src/models): `server/src/models`

### Guidance and voice

- [AI endpoints](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/routes/ai.routes.js): `server/src/routes/ai.routes.js`
- [AI services](https://github.com/malik-bilawal/campus-coin/tree/master/server/src/services/ai): `server/src/services/ai`
- [Voice services](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/tts.service.js): `server/src/services/tts.service.js`

### Engagement and admin

- [Notifications](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/notify.js): `server/src/services/notify.js`
- [Socket service](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/config/socket.js): `server/src/config/socket.js`
- [Admin tools](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/controllers/admin.controller.js): `server/src/controllers/admin.controller.js`
- [Email service](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/mail.service.js): `server/src/services/mail.service.js`
- [Daily tips](https://github.com/malik-bilawal/campus-coin/blob/master/server/src/services/tipsEngine.js): `server/src/services/tipsEngine.js`

### Other components

- **Student**

## Connections

- Student → Next.js app: uses
- Next.js app → API client: requests data
- Next.js app → Voice input: offers voice input
- API client → Express API: calls REST API
- Express API → API routes: mounts routes (evidence: `server/src/app.js`)
- API routes → Transactions: routes requests (evidence: `server/src/routes/transaction.routes.js`)
- API routes → Access control: protects endpoints (evidence: `server/src/routes/transaction.routes.js`)
- Authentication → Domain records: reads and writes users (evidence: `server/src/controllers/auth.controller.js`)
- Authentication → Email service: sends verification mail (evidence: `server/src/controllers/auth.controller.js`)
- Transactions → Domain records: reads and writes transactions (evidence: `server/src/controllers/transaction.controller.js`)
- Transactions → AI services: suggests categories (evidence: `server/src/controllers/transaction.controller.js`)
- Transactions → Budgets: checks budget alerts (evidence: `server/src/controllers/transaction.controller.js`)
- Transactions → Notifications: notifies user (evidence: `server/src/controllers/transaction.controller.js`)
- Transactions → Socket service: emits transaction event (evidence: `server/src/controllers/transaction.controller.js`)
- Budgets → Domain records: uses budget records
- Categories → Domain records: uses category records
- Dashboard → Domain records: summarizes activity
- Reports → Domain records: reads report data (evidence: `server/src/controllers/report.controller.js`)
- Reports → Email service: shares PDF by email (evidence: `server/src/controllers/report.controller.js`)
- AI endpoints → AI services: dispatches AI requests (evidence: `server/src/routes/ai.routes.js`)
- AI endpoints → Domain records: loads categories (evidence: `server/src/routes/ai.routes.js`)
- Voice services → Student: returns speech audio
- Notifications → Domain records: stores notifications (evidence: `server/src/services/notify.js`)
- Notifications → Socket service: emits updates (evidence: `server/src/services/notify.js`)
- Admin tools → Domain records: manages platform data (evidence: `server/src/controllers/admin.controller.js`)
- Admin tools → Notifications: broadcasts announcements (evidence: `server/src/controllers/admin.controller.js`)
- Admin tools → Email service: sends account notices (evidence: `server/src/controllers/admin.controller.js`)
- Daily tips → Domain records: uses spending history (evidence: `server/src/services/tipsEngine.js`)