# mahakagarwal7/volunteer_ai architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/volunteer_ai
- Repository: https://github.com/mahakagarwal7/volunteer_ai

## Overview

#### Purpose and Entry Points
GenZenith is an AI-assisted volunteer coordination MVP: intake needs, enrich/classify them, find suitable volunteers, notify them, and track responses/status. The user-facing application is a Next.js frontend rooted at `ai-volunteer-mvp/frontend/app/page.tsx`; operational entry points include need submission, volunteer views, and admin ingestion. Production backend execution is Supabase Edge Functions, while legacy/supporting Node services remain under `functions`.

#### Frontend Application
Next.js App Router provides public, volunteer, admin, diagnostic, and monitoring surfaces:
- Need intake/status: `ai-volunteer-mvp/frontend/app/submit/page.tsx`, `ai-volunteer-mvp/frontend/app/status/[need_id]/page.tsx`
- Volunteer discovery/detail: `ai-volunteer-mvp/frontend/app/volunteers/page.tsx`, `ai-volunteer-mvp/frontend/app/volunteer/[id]/page.tsx`
- Operations/admin: `ai-volunteer-mvp/frontend/app/admin/ingest/page.tsx`, `ai-volunteer-mvp/frontend/app/monitor/page.tsx`

Feature components own primary UI workflows, while API and Supabase clients establish the browser-to-backend boundary: `ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx`, `ai-volunteer-mvp/frontend/lib/api/client.ts`, `ai-volunteer-mvp/frontend/lib/supabase/client.ts`.

#### Supabase Data and Authorization Layer
Supabase is the system of record for needs, volunteers, predictions, matching, and response state. Migrations encode matching database logic, RLS, tenancy, reputation, and schema evolution:
- `ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql`
- `ai-volunteer-mvp/supabase/migrations/20260423000005_match_volunteers_rpc.sql`
- `ai-volunteer-mvp/supabase/migrations/20260501000000_multitenancy_rls.sql`

Authentication callback handling is in `ai-volunteer-mvp/frontend/app/auth/callback/route.ts`. RLS and database RPCs are the critical trust boundary; edge functions use shared Supabase access code in `ai-volunteer-mvp/supabase/functions/_shared/supabase.ts`.

#### Event-Driven Intake and Matching
Supabase Edge Functions are the primary deployed backend, in Deno. Incoming WhatsApp traffic is accepted by `ai-volunteer-mvp/supabase/functions/whatsapp-webhook/index.ts`; volunteer acceptance/decline events flow through `ai-volunteer-mvp/supabase/functions/volunteer-response/index.ts`. Creation of a need invokes the orchestration path in `ai-volunteer-mvp/supabase/functions/need-created/index.ts`.

The need-created stage is the main control boundary: it can validate/enrich an intake, invoke AI support, persist results, call database matching logic, and initiate outreach. Shared HTTP, AI, Google auth, and image validation utilities sit behind these handlers in `ai-volunteer-mvp/supabase/functions/_shared/`.

#### AI, Enrichment, and Prediction Services
AI capabilities classify inbound messages and support OCR/need processing. Equivalent or supporting Node 20 implementations exist in:
- `ai-volunteer-mvp/functions/src/ai/messageClassifier.ts`
- `ai-volunteer-mvp/functions/src/ai/processOCR.ts`
- `ai-volunteer-mvp/functions/src/triggers/needProcessor.ts`

A separate Python prediction service produces need predictions, with its main entry at `ai-volunteer-mvp/prediction-service/needPredictionService.py`. This is a distinct Python runtime/service boundary from Deno Edge Functions and the frontend.

#### Matching, Notification, and Feedback Loop
Matching combines volunteer attributes, location/region, availability or response signals, and database-level scores. The Node-side matching model is represented by `ai-volunteer-mvp/functions/src/matching/intelligentMatchingService.ts`, with geocoding in `ai-volunteer-mvp/functions/src/location/geocodeService.ts`. Notifications are dispatched by `ai-volunteer-mvp/functions/src/notifications/notifyVolunteer.ts`; responses return through the webhook path and update state used by volunteer/status screens.

#### Runtimes and Deployment
The frontend is TypeScript/Next.js and is configured for Vercel (`ai-volunteer-mvp/vercel.json`). Supabase supplies Postgres, Auth, Storage, RLS, and Deno Edge Function hosting (`ai-volunteer-mvp/supabase/config.toml`). Node 20 remains required for the functions project (`ai-volunteer-mvp/functions/.nvmrc`), and Python/pytest supports prediction processing. Containerization is available through `ai-volunteer-mvp/Dockerfile`.

Main entry points: [`ai-volunteer-mvp/supabase/functions/need-created/index.ts`](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/need-created/index.ts) (Need orchestration), [`ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql`](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql) (Supabase system of record), [`ai-volunteer-mvp/frontend/app/page.tsx`](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/app/page.tsx) (App surfaces), [`ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx`](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx) (Need submission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_app["App surfaces<br/>Next.js App Router<br/>[page.tsx]"]
  node_submission["Need submission<br/>UI workflow<br/>[SubmissionForm.tsx]"]
  node_api_client["Backend API client<br/>browser API boundary<br/>[client.ts]"]
  node_auth_callback["Auth callback<br/>Next.js route<br/>[route.ts]"]
  node_supabase_client["Supabase browser client<br/>auth/data client<br/>[client.ts]"]
end

subgraph group_supabase["Supabase platform"]
  node_whatsapp_webhook{{"WhatsApp webhook<br/>Deno Edge Function<br/>[index.ts]"}}
  node_need_created{{"Need orchestration<br/>Deno Edge Function<br/>[index.ts]"}}
  node_volunteer_response{{"Volunteer response<br/>Deno Edge Function<br/>[index.ts]"}}
  node_edge_shared["Edge shared services<br/>Deno utilities<br/>[supabase.ts]"]
  node_supabase[("Supabase system of record<br/>Postgres, Auth, Storage")]
  node_matching_rpc["Matching RPC<br/>Postgres RPC"]
  node_rls["RLS and tenancy<br/>database authorization"]
end

subgraph group_services["Supporting services"]
  node_prediction["Need prediction service<br/>Python service"]
  node_node_processor["Legacy need processor<br/>Node 20 service<br/>[needProcessor.ts]"]
  node_node_matching["Legacy matching service<br/>Node 20 service"]
  node_notifier["Volunteer notifier<br/>Node 20 service<br/>[notifyVolunteer.ts]"]
end

node_whatsapp(("WhatsApp<br/>messaging channel"))

node_app -->|"hosts"| node_submission
node_submission -->|"submits need"| node_api_client
node_app -->|"reads auth and state"| node_supabase_client
node_auth_callback -->|"completes authentication"| node_supabase
node_supabase_client -->|"authenticated data access"| node_supabase
node_api_client -->|"creates need"| node_need_created
node_whatsapp -->|"inbound messages"| node_whatsapp_webhook
node_whatsapp_webhook -->|"normalizes intake"| node_need_created
node_need_created -->|"uses"| node_edge_shared
node_need_created -->|"requests prediction"| node_prediction
node_need_created -->|"persists enriched need"| node_supabase
node_need_created -->|"finds candidates"| node_matching_rpc
node_matching_rpc -->|"scores volunteer data"| node_supabase
node_supabase -->|"enforced by"| node_rls
node_need_created -.->|"initiates outreach"| node_notifier
node_notifier -->|"sends notifications"| node_whatsapp
node_whatsapp -->|"accept or decline"| node_volunteer_response
node_volunteer_response -->|"updates response state"| node_supabase
node_node_processor -.->|"supporting AI/OCR path"| node_prediction
node_node_matching -.->|"uses volunteer data"| node_supabase

click node_app "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/app/page.tsx"
click node_submission "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx"
click node_api_client "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/lib/api/client.ts"
click node_auth_callback "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/app/auth/callback/route.ts"
click node_supabase_client "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/lib/supabase/client.ts"
click node_whatsapp_webhook "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/whatsapp-webhook/index.ts"
click node_need_created "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/need-created/index.ts"
click node_volunteer_response "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/volunteer-response/index.ts"
click node_edge_shared "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/_shared/supabase.ts"
click node_supabase "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql"
click node_matching_rpc "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260423000005_match_volunteers_rpc.sql"
click node_rls "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260501000000_multitenancy_rls.sql"
click node_prediction "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/prediction-service/needPredictionService.py"
click node_node_processor "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/triggers/needProcessor.ts"
click node_node_matching "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/matching/intelligentMatchingService.ts"
click node_notifier "https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/notifications/notifyVolunteer.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_app,node_submission,node_api_client,node_auth_callback,node_supabase_client toneBlue
class node_whatsapp_webhook,node_need_created,node_volunteer_response,node_edge_shared,node_supabase,node_matching_rpc,node_rls toneAmber
class node_prediction,node_node_processor,node_node_matching,node_notifier toneMint
class node_whatsapp toneNeutral
```

## Components

### Next.js frontend

- [App surfaces](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/app/page.tsx): Next.js App Router · Public, volunteer, admin, status, and monitoring views. · `ai-volunteer-mvp/frontend/app/page.tsx`
- [Need submission](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx): UI workflow · `ai-volunteer-mvp/frontend/features/need/SubmissionForm.tsx`
- [Backend API client](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/lib/api/client.ts): browser API boundary · `ai-volunteer-mvp/frontend/lib/api/client.ts`
- [Auth callback](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/app/auth/callback/route.ts): Next.js route · `ai-volunteer-mvp/frontend/app/auth/callback/route.ts`
- [Supabase browser client](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/frontend/lib/supabase/client.ts): auth/data client · `ai-volunteer-mvp/frontend/lib/supabase/client.ts`

### Supabase platform

- [WhatsApp webhook](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/whatsapp-webhook/index.ts): Deno Edge Function · `ai-volunteer-mvp/supabase/functions/whatsapp-webhook/index.ts`
- [Need orchestration](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/need-created/index.ts): Deno Edge Function · Validates, enriches, matches, and initiates outreach. · `ai-volunteer-mvp/supabase/functions/need-created/index.ts`
- [Volunteer response](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/volunteer-response/index.ts): Deno Edge Function · `ai-volunteer-mvp/supabase/functions/volunteer-response/index.ts`
- [Edge shared services](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/functions/_shared/supabase.ts): Deno utilities · Shared Supabase, AI, HTTP, Google auth, and image validation access. · `ai-volunteer-mvp/supabase/functions/_shared/supabase.ts`
- [Supabase system of record](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql): Postgres, Auth, Storage · Stores needs, volunteers, predictions, matches, and response state. · `ai-volunteer-mvp/supabase/migrations/20260422000001_firestore_to_supabase.sql`
- [Matching RPC](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260423000005_match_volunteers_rpc.sql): Postgres RPC · Database-level candidate scoring and selection. · `ai-volunteer-mvp/supabase/migrations/20260423000005_match_volunteers_rpc.sql`
- [RLS and tenancy](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/supabase/migrations/20260501000000_multitenancy_rls.sql): database authorization · Critical data trust boundary. · `ai-volunteer-mvp/supabase/migrations/20260501000000_multitenancy_rls.sql`

### Supporting services

- [Need prediction service](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/prediction-service/needPredictionService.py): Python service · Produces need predictions outside the Edge runtime. · `ai-volunteer-mvp/prediction-service/needPredictionService.py`
- [Legacy need processor](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/triggers/needProcessor.ts): Node 20 service · Supporting AI/OCR trigger implementation. · `ai-volunteer-mvp/functions/src/triggers/needProcessor.ts`
- [Legacy matching service](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/matching/intelligentMatchingService.ts): Node 20 service · Supporting intelligent matching and geocoding. · `ai-volunteer-mvp/functions/src/matching/intelligentMatchingService.ts`
- [Volunteer notifier](https://github.com/mahakagarwal7/volunteer_ai/blob/main/ai-volunteer-mvp/functions/src/notifications/notifyVolunteer.ts): Node 20 service · `ai-volunteer-mvp/functions/src/notifications/notifyVolunteer.ts`

### Other components

- **WhatsApp**: messaging channel · Inbound intake and outbound volunteer outreach.

## Connections

- App surfaces → Need submission: hosts
- Need submission → Backend API client: submits need
- App surfaces → Supabase browser client: reads auth and state
- Auth callback → Supabase system of record: completes authentication
- Supabase browser client → Supabase system of record: authenticated data access
- Backend API client → Need orchestration: creates need
- WhatsApp → WhatsApp webhook: inbound messages
- WhatsApp webhook → Need orchestration: normalizes intake
- Need orchestration → Edge shared services: uses
- Need orchestration → Need prediction service: requests prediction
- Need orchestration → Supabase system of record: persists enriched need
- Need orchestration → Matching RPC: finds candidates
- Matching RPC → Supabase system of record: scores volunteer data
- Supabase system of record → RLS and tenancy: enforced by
- Need orchestration → Volunteer notifier: initiates outreach
- Volunteer notifier → WhatsApp: sends notifications
- WhatsApp → Volunteer response: accept or decline
- Volunteer response → Supabase system of record: updates response state
- Legacy need processor → Need prediction service: supporting AI/OCR path
- Legacy matching service → Supabase system of record: uses volunteer data