nextVillage.community (also known as vAI)

An AI-facilitated learning platform for young people in rural communities to develop the skills to lead their own futures — learning modules, AI-tool workshops, certifications, and real community-impact challenges (health, agriculture, fishing, entrepreneurship, animal husbandry), with facilitator/admin dashboards to track outcomes for grant reporting.

Tech stack

• Frontend: Vite + React + TypeScript, React Router, Tailwind CSS
• Backend: Supabase (Postgres, Auth, Storage, Edge Functions) + Vercel serverless functions (api/)
• AI providers: Anthropic, OpenAI, Groq, Cerebras, Together, Hugging Face — routed through api/chat.js and related proxy endpoints
• Email: Resend (transactional/auth email via Supabase SMTP)
• Hosting: Vercel (auto-deploys main)

Local setup

npm install

Copy .env.local.example if one exists, or ask a teammate for a .env.local — it's git-ignored and not checked in. Required variables fall into a few groups:

• Supabase: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
• AI providers: ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY, AI_TOGETHER_API_KEY, HF_TOKEN
• Email: RESEND_API_KEY
• Misc third-party: CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN, SPEECHGEN_EMAIL / SPEECHGEN_TOKEN / SPEECHGEN_VOICE, NEWS_API_SECRET, CRON_SECRET

npm run dev          # frontend (Vite) + local backend (real-e2b-server.cjs) together
npm run dev:frontend # just Vite
npm run dev:backend  # just the backend server

Scripts

Command	What it does
npm run build	Production build
npm test	Run the Vitest suite
npm run deadcode	Scan for unused files/dependencies (knip) — informational, not a CI gate
npm run lint	ESLint
npm run assess:baseline / assess:monthly	Standalone scripts for the personality/proficiency assessment pipeline

Database & migrations

Schema lives in supabase/migrations/ as a single baseline migration reflecting the actual live schema (reset 2026-07-14 — see supabase/migrations_archive/README.md for why). All future schema changes should be new migration files layered on top of that baseline, not made directly through the Supabase dashboard — direct dashboard edits are exactly what caused the previous migration history to drift from reality.

To pull the current live schema and check for drift:

supabase db pull    # requires Docker (or a lightweight alternative like colima) for the shadow database

Contributing

Full process (branching, PRs, what the CI check verifies) is in docs/platform-management/GitHub-Push-Process-Report.pdf. Short version: branch off development, open a PR into main, wait for the typecheck-and-build check (which also runs the test suite) to pass, merge. Direct pushes to main are blocked for everyone except the repo owner.

Deployment

Vercel auto-deploys on push to main. Preview deployments are generated for every PR.