mahakagarwal7/volunteer_ai

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.