Who it serves
Children in underserved or remote Nigerian communities, plus parents in urban areas who want affordable, engaging tutoring support.
Build, run, and ship an open-source bilingual learning platform that teaches English and technology through Yoruba, adaptive AI support, and child-friendly play.
Edusi combines "education" with "si", the Yoruba word for "open". The product starts with Nigerian children learning English and technology through Yoruba, then keeps the platform flexible enough for other languages and communities.
Children in underserved or remote Nigerian communities, plus parents in urban areas who want affordable, engaging tutoring support.
English and technology literacy through bilingual lessons, voice interaction, visual support, progress tracking, and game-like feedback.
A responsive web app for phones, tablets, and desktops, with WhatsApp learning flows for families with limited bandwidth or intermittent connectivity.
Use Node 22+, npm 10+, Python 3.12+, and the Supabase CLI. Docker is optional for local service orchestration.
gh repo clone immerSIR/edusi
cd edusi
cp .env.example .env
cd frontend
npm install
npm run dev
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
Keep browser-safe access in the frontend and provider secrets on the backend. Shared contracts should move together across API schemas, frontend types, and migrations.
Next.js screens, hooks, shared API helpers, child-friendly UI, and PWA assets.
frontend/src/app/ contains routes and pages.frontend/src/components/ contains reusable UI.frontend/src/lib/api.ts centralizes backend calls.Public values use NEXT_PUBLIC_* and are visible in the browser.
FastAPI route handlers, Pydantic schemas, and provider integrations.
backend/app/api/ keeps route handlers.backend/app/services/ owns provider logic.backend/app/core/config.py loads local settings.Service-role keys, AI keys, and WhatsApp tokens stay server-side.
Postgres schema, RLS, seed data, child profiles, storage, and curriculum content.
supabase/migrations/.supabase db reset after schema changes.Do not edit migrations that have already shipped.
Learning flows span the FastAPI API and the Supabase Edge Function webhook.
backend/app/api/whatsapp.pybackend/app/services/whatsapp_service.pysupabase/functions/whatsapp-webhook/Use a tunnel for local Meta webhook callbacks.
Start in the narrowest owning folder, then update adjacent contracts only when behavior crosses boundaries.
| Path | Purpose |
|---|---|
frontend/ |
Next.js App Router app, TypeScript, Tailwind CSS, PWA assets, Supabase browser client, and UI workflows. |
backend/ |
FastAPI server, service integrations, request and response schemas, and backend tests. |
supabase/migrations/ |
Database schema, row-level security policies, seed data, curriculum records, and storage setup. |
supabase/functions/ |
Edge Functions, including the WhatsApp webhook entry point. |
.github/workflows/ |
CI, coverage, and GitHub Pages publishing workflows. |
Supabase owns data shape and access control, so schema and policy changes need a full local reset before review.
supabase start
supabase db reset
supabase functions serve whatsapp-webhook --env-file .env
Use .env.example as the source of truth. Browser variables are public; provider credentials and service-role access are backend-only.
| Variable | Scope | Used by |
|---|---|---|
NEXT_PUBLIC_SUPABASE_URL |
Public | Frontend and backend Supabase URL configuration. |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY |
Public | Browser Supabase access. |
NEXT_PUBLIC_API_URL, NEXT_PUBLIC_BACKEND_URL |
Public | Frontend API calls to FastAPI. |
SUPABASE_SERVICE_ROLE_KEY |
Secret | Privileged backend database operations. |
OPENAI_API_KEY, GOOGLE_TRANSLATE_API_KEY, GOOGLE_GEMINI_API_KEY |
Secret | Voice, translation, and generation services. |
WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN, WHATSAPP_APP_SECRET |
Secret | WhatsApp Cloud API and webhook verification. |
Never commit .env, service-role keys, provider API keys, WhatsApp tokens, generated transcripts, dependency folders, or build output.
Run focused local checks, then let GitHub Actions repeat the full CI and Pages publishing path.
npm run lintnpm run buildnpm run testpython -m compileall apppytestCORS_ORIGINS..github/workflows/pages.yml. The repository Pages source should remain set to GitHub Actions to avoid duplicate legacy Pages deployment checks.
Edusi was created by a small team listed here in the original project order.
Technical lead and repository maintainer; built the frontend, backend, Supabase, AI, and WhatsApp integration layers.
Project collaborator; contributed to product direction, learner needs, and project shaping.
Project collaborator; contributed to product direction, learner needs, and project shaping.