# sanjayramkumarm-ai/voluntess architecture

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

- Interactive diagram: https://gitdiagram.com/sanjayramkumarm-ai/voluntess
- Repository: https://github.com/sanjayramkumarm-ai/voluntess

## Overview

Voluntess is a volunteer-management platform for volunteers, NGOs, and administrators. Its principal workflow is discovering an opportunity, applying, and having an NGO review the application; participation then supports attendance tracking, completion verification, and certificate issuance. The tree and route declarations show additional authentication, messaging, teams, quests, reviews, and NGO administration. The source excerpts establish several controller-to-model relationships, but client API wiring and unsampled controller internals are not shown, so those links are omitted or marked unverified.

Main entry points: [`server/src/routes/index.ts`](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/routes/index.ts) (API route dispatch), [`server/src/controllers/application.ts`](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/application.ts) (Applications and decisions), [`server/src/controllers/attendance.ts`](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/attendance.ts) (Attendance and check-in), [`server/src/controllers/certificates.ts`](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/certificates.ts) (Completions and certificates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_explore["Opportunity discovery<br/>[page.tsx]"]
  node_opportunity_view["Opportunity details<br/>[page.tsx]"]
  node_ngo_portal["NGO workspace<br/>[page.tsx]"]
  node_auth_ui["Sign-in and registration<br/>[page.tsx]"]
  node_participation_ui["Attendance and check-in<br/>[page.tsx]"]
  node_completion_ui["Completion review"]
  node_community_ui["Community features<br/>[page.tsx]"]
end

subgraph group_identity["Identity and discovery"]
  node_auth_routes["Authentication endpoints<br/>[authOtp.ts]"]
  node_opportunity_api["Opportunity management<br/>[opportunity.ts]"]
end

subgraph group_participation["Volunteer participation"]
  node_application_api["Applications and decisions<br/>[application.ts]"]
  node_attendance_api["Attendance and check-in<br/>[attendance.ts]"]
end

subgraph group_impact["Recognition and community"]
  node_completion_api["Completions and certificates<br/>[certificates.ts]"]
  node_pdf_service["Certificate PDF service<br/>[certificatePdf.ts]"]
  node_review_api["Reviews<br/>[review.ts]"]
  node_messages_api["Messaging<br/>[messages.ts]"]
  node_teams_api["Teams<br/>[team.ts]"]
  node_quest_api["Quests and rewards<br/>[quest.ts]"]
end

subgraph group_backend["API and persistence"]
  node_user_store[("User records<br/>[User.ts]")]
  node_opportunity_store[("Opportunity records<br/>[Opportunity.ts]")]
  node_application_store[("Application records<br/>[Application.ts]")]
  node_completion_store[("Completion records<br/>[Completion.ts]")]
  node_certificate_store[("Certificate records<br/>[Certificate.ts]")]
  node_review_store[("Review records<br/>[Review.ts]")]
  node_notification_store[("Notifications<br/>[Notification.ts]")]
  node_http_routes["API route dispatch<br/>[index.ts]"]
  node_api_server["HTTP server<br/>[server.ts]"]
end

node_user(("Platform users"))

node_user -->|"browses"| node_explore
node_user -->|"signs in"| node_auth_ui
node_api_server -->|"mounts API"| node_http_routes
node_http_routes -->|"routes auth"| node_auth_routes
node_http_routes -->|"routes opportunities"| node_opportunity_api
node_http_routes -->|"routes applications"| node_application_api
node_http_routes -->|"routes attendance"| node_attendance_api
node_http_routes -->|"routes certificates"| node_completion_api
node_http_routes -->|"routes reviews"| node_review_api
node_http_routes -->|"routes messages"| node_messages_api
node_http_routes -->|"routes teams"| node_teams_api
node_http_routes -->|"routes quests"| node_quest_api
node_auth_routes -->|"reads and writes"| node_user_store
node_auth_routes -->|"uses OTP service"| node_auth_routes
node_opportunity_api -.->|"manages"| node_opportunity_store
node_application_api -->|"reads and writes"| node_application_store
node_application_api -->|"checks capacity"| node_opportunity_store
node_application_api -->|"creates alerts"| node_notification_store
node_application_api -->|"records quest event"| node_quest_api
node_attendance_api -->|"checks participation"| node_application_store
node_attendance_api -->|"records completion"| node_completion_store
node_attendance_api -->|"uses certificates"| node_certificate_store
node_attendance_api -->|"creates alerts"| node_notification_store
node_completion_api -->|"manages completions"| node_completion_store
node_completion_api -->|"issues certificates"| node_certificate_store
node_completion_api -->|"generates PDF"| node_pdf_service
node_completion_api -->|"creates alerts"| node_notification_store
node_review_api -->|"creates and reads"| node_review_store
node_review_api -->|"checks eligibility"| node_application_store
node_review_api -->|"creates alerts"| node_notification_store
node_messages_api -->|"creates alerts"| node_notification_store
node_explore -.->|"loads listings"| node_opportunity_api
node_opportunity_view -.->|"submits application"| node_application_api
node_ngo_portal -.->|"reviews applications"| node_application_api
node_participation_ui -.->|"records attendance"| node_attendance_api
node_completion_ui -->|"reviews completion"| node_completion_api
node_community_ui -.->|"uses team features"| node_teams_api

click node_explore "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/explore/page.tsx"
click node_opportunity_view "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/opportunities/%5Bid%5D/page.tsx"
click node_ngo_portal "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/ngo/page.tsx"
click node_auth_ui "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/login/page.tsx"
click node_participation_ui "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/attendance/page.tsx"
click node_completion_ui "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/components/certificates/CompletionReviewTable.tsx"
click node_community_ui "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/teams/page.tsx"
click node_auth_routes "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/authOtp.ts"
click node_user_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/User.ts"
click node_opportunity_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/opportunity.ts"
click node_opportunity_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Opportunity.ts"
click node_application_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/application.ts"
click node_application_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Application.ts"
click node_attendance_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/attendance.ts"
click node_completion_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/certificates.ts"
click node_completion_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Completion.ts"
click node_certificate_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Certificate.ts"
click node_pdf_service "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/services/certificatePdf.ts"
click node_review_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/review.ts"
click node_review_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Review.ts"
click node_messages_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/messages.ts"
click node_teams_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/team.ts"
click node_quest_api "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/quest.ts"
click node_notification_store "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Notification.ts"
click node_http_routes "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/routes/index.ts"
click node_api_server "https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/server.ts"

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_explore,node_opportunity_view,node_ngo_portal,node_auth_ui,node_participation_ui,node_completion_ui,node_community_ui,node_user toneBlue
class node_auth_routes,node_opportunity_api toneAmber
class node_application_api,node_attendance_api toneMint
class node_completion_api,node_pdf_service,node_review_api,node_messages_api,node_teams_api,node_quest_api toneRose
class node_user_store,node_opportunity_store,node_application_store,node_completion_store,node_certificate_store,node_review_store,node_notification_store,node_http_routes,node_api_server toneIndigo
```

## Components

### Web experience

- [Opportunity discovery](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/explore/page.tsx): `client/src/app/explore/page.tsx`
- [Opportunity details](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/opportunities/%5Bid%5D/page.tsx): `client/src/app/opportunities/[id]/page.tsx`
- [NGO workspace](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/ngo/page.tsx): `client/src/app/ngo/page.tsx`
- [Sign-in and registration](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/login/page.tsx): `client/src/app/login/page.tsx`
- [Attendance and check-in](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/attendance/page.tsx): `client/src/app/attendance/page.tsx`
- [Completion review](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/components/certificates/CompletionReviewTable.tsx): `client/src/components/certificates/CompletionReviewTable.tsx`
- [Community features](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/client/src/app/teams/page.tsx): `client/src/app/teams/page.tsx`

### Identity and discovery

- [Authentication endpoints](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/authOtp.ts): `server/src/controllers/authOtp.ts`
- [Opportunity management](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/opportunity.ts): `server/src/controllers/opportunity.ts`

### Volunteer participation

- [Applications and decisions](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/application.ts): `server/src/controllers/application.ts`
- [Attendance and check-in](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/attendance.ts): `server/src/controllers/attendance.ts`

### Recognition and community

- [Completions and certificates](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/certificates.ts): `server/src/controllers/certificates.ts`
- [Certificate PDF service](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/services/certificatePdf.ts): `server/src/services/certificatePdf.ts`
- [Reviews](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/review.ts): `server/src/controllers/review.ts`
- [Messaging](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/messages.ts): `server/src/controllers/messages.ts`
- [Teams](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/team.ts): `server/src/controllers/team.ts`
- [Quests and rewards](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/controllers/quest.ts): `server/src/controllers/quest.ts`

### API and persistence

- [User records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/User.ts): `server/src/models/User.ts`
- [Opportunity records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Opportunity.ts): `server/src/models/Opportunity.ts`
- [Application records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Application.ts): `server/src/models/Application.ts`
- [Completion records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Completion.ts): `server/src/models/Completion.ts`
- [Certificate records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Certificate.ts): `server/src/models/Certificate.ts`
- [Review records](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Review.ts): `server/src/models/Review.ts`
- [Notifications](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/models/Notification.ts): `server/src/models/Notification.ts`
- [API route dispatch](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [HTTP server](https://github.com/sanjayramkumarm-ai/voluntess/blob/main/server/src/server.ts): `server/src/server.ts`

### Other components

- **Platform users**

## Connections

- Platform users → Opportunity discovery: browses
- Platform users → Sign-in and registration: signs in
- HTTP server → API route dispatch: mounts API (evidence: `server/src/server.ts`)
- API route dispatch → Authentication endpoints: routes auth (evidence: `server/src/routes/index.ts`)
- API route dispatch → Opportunity management: routes opportunities (evidence: `server/src/routes/index.ts`)
- API route dispatch → Applications and decisions: routes applications (evidence: `server/src/routes/index.ts`)
- API route dispatch → Attendance and check-in: routes attendance (evidence: `server/src/routes/index.ts`)
- API route dispatch → Completions and certificates: routes certificates (evidence: `server/src/routes/index.ts`)
- API route dispatch → Reviews: routes reviews (evidence: `server/src/routes/index.ts`)
- API route dispatch → Messaging: routes messages (evidence: `server/src/routes/index.ts`)
- API route dispatch → Teams: routes teams (evidence: `server/src/routes/index.ts`)
- API route dispatch → Quests and rewards: routes quests (evidence: `server/src/routes/index.ts`)
- Authentication endpoints → User records: reads and writes (evidence: `server/src/controllers/authOtp.ts`)
- Authentication endpoints → Authentication endpoints: uses OTP service (evidence: `server/src/controllers/authOtp.ts`)
- Opportunity management → Opportunity records: manages
- Applications and decisions → Application records: reads and writes (evidence: `server/src/controllers/application.ts`)
- Applications and decisions → Opportunity records: checks capacity (evidence: `server/src/controllers/application.ts`)
- Applications and decisions → Notifications: creates alerts (evidence: `server/src/controllers/application.ts`)
- Applications and decisions → Quests and rewards: records quest event (evidence: `server/src/controllers/application.ts`)
- Attendance and check-in → Application records: checks participation (evidence: `server/src/controllers/attendance.ts`)
- Attendance and check-in → Completion records: records completion (evidence: `server/src/controllers/attendance.ts`)
- Attendance and check-in → Certificate records: uses certificates (evidence: `server/src/controllers/attendance.ts`)
- Attendance and check-in → Notifications: creates alerts (evidence: `server/src/controllers/attendance.ts`)
- Completions and certificates → Completion records: manages completions (evidence: `server/src/controllers/certificates.ts`)
- Completions and certificates → Certificate records: issues certificates (evidence: `server/src/controllers/certificates.ts`)
- Completions and certificates → Certificate PDF service: generates PDF (evidence: `server/src/controllers/certificates.ts`)
- Completions and certificates → Notifications: creates alerts (evidence: `server/src/controllers/certificates.ts`)
- Reviews → Review records: creates and reads (evidence: `server/src/controllers/review.ts`)
- Reviews → Application records: checks eligibility (evidence: `server/src/controllers/review.ts`)
- Reviews → Notifications: creates alerts (evidence: `server/src/controllers/review.ts`)
- Messaging → Notifications: creates alerts (evidence: `server/src/controllers/messages.ts`)
- Opportunity discovery → Opportunity management: loads listings
- Opportunity details → Applications and decisions: submits application
- NGO workspace → Applications and decisions: reviews applications
- Attendance and check-in → Attendance and check-in: records attendance
- Completion review → Completions and certificates: reviews completion (evidence: `client/src/components/certificates/CompletionReviewTable.tsx`)
- Community features → Teams: uses team features
