Edusi Developer Docs

Build, run, and ship an open-source bilingual learning platform that teaches English and technology through Yoruba, adaptive AI support, and child-friendly play.

Open education in the language children think in.

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.

Who it serves

Children in underserved or remote Nigerian communities, plus parents in urban areas who want affordable, engaging tutoring support.

What it teaches

English and technology literacy through bilingual lessons, voice interaction, visual support, progress tracking, and game-like feedback.

How it reaches learners

A responsive web app for phones, tablets, and desktops, with WhatsApp learning flows for families with limited bandwidth or intermittent connectivity.

Get the full stack
running locally.

Use Node 22+, npm 10+, Python 3.12+, and the Supabase CLI. Docker is optional for local service orchestration.

Clone and configure

root
gh repo clone immerSIR/edusi
cd edusi
cp .env.example .env

Frontend

localhost:3000
cd frontend
npm install
npm run dev

Backend

localhost:8000
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Four lanes make up the product.

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.

01

Frontend

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.

02

Backend

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.

03

Supabase

Postgres schema, RLS, seed data, child profiles, storage, and curriculum content.

  • Add SQL files under supabase/migrations/.
  • Run supabase db reset after schema changes.
  • Update frontend types and backend schemas together.

Do not edit migrations that have already shipped.

04

WhatsApp

Learning flows span the FastAPI API and the Supabase Edge Function webhook.

  • backend/app/api/whatsapp.py
  • backend/app/services/whatsapp_service.py
  • supabase/functions/whatsapp-webhook/

Use a tunnel for local Meta webhook callbacks.

Where to make changes.

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.

Reset locally before schema PRs.

Supabase owns data shape and access control, so schema and policy changes need a full local reset before review.

Local database

supabase
supabase start
supabase db reset

WhatsApp webhook

edge function
supabase functions serve whatsapp-webhook --env-file .env

Know which values are public.

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.

Verify the lane you changed.

Run focused local checks, then let GitHub Actions repeat the full CI and Pages publishing path.

Frontend

  • npm run lint
  • npm run build
  • npm run test

Backend

  • python -m compileall app
  • pytest
  • Keep route handlers thin.

Deployment

  • Apply Supabase migrations first.
  • Set backend secrets server-side.
  • Configure CORS_ORIGINS.
GitHub Pages is published by .github/workflows/pages.yml. The repository Pages source should remain set to GitHub Actions to avoid duplicate legacy Pages deployment checks.

People behind the project.

Edusi was created by a small team listed here in the original project order.

01

Mohamed Doumbia

Technical lead and repository maintainer; built the frontend, backend, Supabase, AI, and WhatsApp integration layers.

02

Kingsolomon Ehinola

Project collaborator; contributed to product direction, learner needs, and project shaping.

03

Deborah Nabuduwa

Project collaborator; contributed to product direction, learner needs, and project shaping.