AAICBI Learning Management System

A full-featured LMS built for Africa's AI Capacity Building Initiative: courses with progress-locked modules, AI-graded assessments, real payments, publicly verifiable certificates, an employer portal for discovering and hiring trainees, and a course review/testimonial system — built out from the original M9 foundation scaffold through 47 sequenced milestones across six stages, all now complete except one external, non-technical dependency (see "What's genuinely not done" below).

Setup

For a complete, step-by-step guide covering both local development and live production deployment (Vercel + Neon), see DEPLOYMENT.md in this same folder. The quick version below is a fast reference for anyone already familiar with the stack; DEPLOYMENT.md is the one to follow if this is your first time running the project.

If you obtained this project by extracting it from a .skill file rather than having Claude generate it fresh, some folder names under src/app/ may still read as __id__ or __code__ instead of [id]/[code] (Next.js's real dynamic-route syntax) — a packaging limitation, not a typo. Run python3 scripts/materialize_template.py . from the skill directory once to fix that before continuing.

npm install
cp .env.example .env        # see that file's own comments for what each key is for and which are optional
docker compose up -d        # starts local Postgres
npx prisma generate         # requires internet access — downloads the query engine
npx prisma db push          # creates tables from prisma/schema.prisma
npm run db:seed             # demo staff, trainee, employer, course, and testimonial
npm run dev

Then open http://localhost:3000.

• Staff login: [email protected] / ChangeMe123! → /admin/login
• Trainee login: [email protected] / TraineeDemo123! → /trainee/login
• Employer login: [email protected] / EmployerDemo123! → /employer/login (pre-approved — visit /employer/discover to see the demo trainee)
• Demo exam code: AAICBI-EXCEL-DEMO

Only AUTH_SECRET and ANTHROPIC_API_KEY are required to run the app at all — every other key in .env.example (email, payments, WhatsApp, Google Translate, avatar storage) has its own real fallback behavior when left unset, documented directly in that file's own comments next to each one. Nothing crashes because a key is missing; features that depend on one degrade to "not available yet" instead.

Note on prisma generate: it needs to reach binaries.prisma.sh to download the query engine binary. If you're running this inside a network-restricted sandbox (as this scaffold was built and tested in), that step will fail with a 403 — it works fine on a normal machine or CI runner with unrestricted internet. tsc --noEmit will show a cascade of @prisma/client "no exported member" errors in that case — that's this same cause, verified against the original unmodified template, not a bug in this project. See references/porting-notes.md in the skill for the verification.

This same restriction means real schema validation (as opposed to the individual, seeded-Postgres checks used throughout this whole build) could never run from inside this sandbox — and the very first real prisma generate, run by someone with actual internet access, did catch something genuine: Exam had two fields both named course — a legacy free-text label predating the real Course relation, and that relation itself, added later without noticing the name was already taken. Confirmed no application code anywhere referenced the relation by that name before fixing it (it was defined but never actually used), and fixed by renaming the relation to parentCourse — the exact same naming-collision fix courseModule (vs the legacy module label) already applied earlier in the same model, just not consistently carried forward when this second relation was added. Also swept the entire schema afterward for any other duplicate field name across every model — this was the only one.

Run the parser tests any time with npm test — they don't need a database or the Prisma client, so they're a fast sanity check after any change to the DOCX import logic.

Deploying

Works on Vercel out of the box for the Next.js app; point DATABASE_URL at a managed Postgres (Neon, Supabase, Railway, RDS...) instead of the local docker-compose one. On Vercel, the vercel-build script (scripts/vercel-build.mjs) runs prisma migrate deploy before the build on production deployments only; previews and local builds never touch the database. Elsewhere, run npx prisma migrate deploy against the production database as part of your deploy step. See docs/public-ecosystem.md.

build is deliberately prisma generate && next build, not just next build. @prisma/client's own postinstall usually regenerates the client automatically, but Vercel's build cache can skip a fresh npm install on a redeploy, silently leaving a stale, mismatched client in place — a well-known real-world failure mode for Prisma projects on Vercel, not a hypothetical one. Running prisma generate explicitly as the first step of build guarantees a fresh client on every single deploy, cache or no cache.

What's included

Trainee experience — self-registration and login, structured courses with progress-locked modules and lessons, AI-graded assessments with instant feedback and per-attempt analysis, offline material downloads (redirect-based for video, proxied for documents), lesson-level Q&A with staff replies and likes, WhatsApp notifications alongside email (code complete, pending Meta's own approval process — see "What's genuinely not done" below), and publicly verifiable certificates the moment a course is completed.

This is the beginning of the README. Read the rest at the original. Read the full README ↗