Hands-on science education for African universities — no physical lab required.
29 interactive experiments across 5 disciplines, an AI lab assistant, and real analytics,
served from the Cloudflare edge to any device, even on flaky connections.

---

Table of Contents

• Overview
• Key Features
• Experiment Catalogue
• Architecture
• Tech Stack
• Getting Started
• Project Structure
• Testing
• Roadmap
• Contributing
• License

---

Overview

Laboratory access is one of the biggest bottlenecks in African science education: equipment is scarce, consumables are expensive, and a single broken centrifuge can sideline an entire cohort. AfriLab closes that gap with a fully simulated laboratory platform where students perform real experimental procedure — titrating, pipetting, wiring circuits, reading ECGs — in the browser, with measurement recording, AI-guided hints, and instructor oversight built in.

The whole platform is a single SvelteKit application deployed to Cloudflare Pages, backed by D1 (SQLite at the edge), KV sessions, R2 asset storage, and Workers AI for tutoring. It ships as an installable PWA with offline support, so learning doesn't stop when the connection does.

---

Key Features

              

• 29 interactive simulations, 5 disciplines — Chemistry, Biology, Physics, Pharmacy, and Medical labs with step-guided procedures, 3D equipment (Three.js), safety banners, timers, and data recorders.
• AI lab assistant — a context-aware tutor powered by Cloudflare Workers AI (@cf/meta/llama-3.1-70b-instruct) that knows your discipline, experiment, current step, and recent measurements — and gives progressive hints instead of answers.
• Progress & analytics — measurement recording, lab reports, certificates, a student dashboard with history and progress tracking, a leaderboard, and an instructor analytics view.
• Collaboration — presence indicators and a collaboration panel so students can work together in the lab.
• Offline-first PWA — installable, with a service worker, offline page, and connection indicator.
• Multi-institution by design — institution registry, role-based access (student / instructor / admin), enrollments, assignments, and Google OAuth sign-in alongside email/password auth.

---

Experiment Catalogue

Every experiment below has a working simulation engine in src/lib/simulations/ and a lab route under src/routes/labs/.

Discipline	Experiments
Chemistry	Acid–Base Titration · UV-Vis Spectroscopy · Calorimetry · Chromatography · Electrochemistry · Organic Synthesis
Biology	Microscopy · DNA Extraction · Cell Division · Enzyme Kinetics · Genetics · Photosynthesis · Ecosystem
Physics	Ohm's Law · Optics · Pendulum · Projectile Motion · Thermodynamics · Wave Motion
Pharmacy	Compounding · Dosage Calculations · Drug Interactions · Pharmacokinetics · Quality Control
Medical	Auscultation · Blood Analysis · ECG Reading · Patient Assessment · Vital Signs

---

Architecture

AfriLab runs entirely on Cloudflare's edge network — there is no separate backend to deploy:

Layer	Technology	Role
Frontend & SSR	SvelteKit 2 + Svelte 5 on Cloudflare Pages	Server-rendered UI, lab routes, dashboards
API	SvelteKit server routes (/api/*)	AI chat & hints, analytics, demo lifecycle, seeding
Database	Cloudflare D1 (SQLite)	Users, institutions, experiments, sessions, measurements, assessments
Sessions & cache	Cloudflare KV	Low-latency session storage
Object storage	Cloudflare R2	3D models, videos, and lab assets
AI	Cloudflare Workers AI	Llama 3.1 70B lab assistant and adaptive hints
Auth	Custom sessions + Google OAuth 2.0	Email/password and institutional Google sign-in
3D rendering	Three.js	Interactive lab equipment (beakers, burettes, flasks)

---

Tech Stack

Category	Choice
Framework	SvelteKit 2, Svelte 5, Vite 6
Language	TypeScript
Styling	Tailwind CSS 3 (+ forms & typography plugins)
Platform	Cloudflare Pages via @sveltejs/adapter-cloudflare
Data	D1, KV, R2
AI	Workers AI (@cf/meta/llama-3.1-70b-instruct)
3D	Three.js
Unit tests	Vitest + Testing Library
E2E tests	Playwright

---

Getting Started

Prerequisites

• Node.js 18+
• A Cloudflare account with the Wrangler CLI (npm install -g wrangler)

Setup

# 1. Clone
git clone https://github.com/ghwmelite-dotcom/AfriLab.git
cd AfriLab

# 2. Install dependencies
npm install

# 3. Create the Cloudflare resources
wrangler d1 create afrilab-db
wrangler kv:namespace create SESSIONS
wrangler r2 bucket create afrilab-assets

# 4. Copy the generated IDs into wrangler.toml

# 5. Apply the database schema and seed data
npm run db:migrate          # local D1
npm run db:migrate:prod     # production D1

# 6. Run the dev server
npm run dev

To run with real Cloudflare bindings locally:

npm run build
npm run preview:wrangler

For Google sign-in, set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET as secrets and configure GOOGLE_REDIRECT_URI (see the comments in wrangler.toml). Without them, email/password auth still works.

Deploy

npm run deploy    # builds and deploys to Cloudflare Pages

---

Project Structure

afrilab/
├── migrations/                  # D1 schema + seed migrations (0001–0005)
├── src/
│   ├── lib/
│   │   ├── components/
│   │   │   ├── ai/              # Chat assistant & hint button
│   │   │   ├── analytics/       # Dashboard & page tracking
│   │   │   ├── collaboration/   # Presence & collaboration panel
│   │   │   ├── lab/             # Lab canvas, 3D equipment, data recorder, certificates
│   │   │   ├── layout/          # Header, sidebar, footer
│   │   │   ├── onboarding/      # First-run experience
│   │   │   ├── pwa/             # Install prompt & offline indicator
│   │   │   └── ui/              # Shared UI primitives
│   │   ├── server/              # auth, OAuth, db, AI prompt builders & hints
│   │   ├── simulations/         # 29 experiment engines, one file each
│   │   │   ├── biology/  chemistry/  medical/  pharmacy/  physics/
│   │   ├── stores/              # Svelte stores (lab, AI, user, theme, notifications…)
│   │   ├── types/               # Shared TypeScript definitions
│   │   └── utils/               # Helpers (incl. Three.js utilities)
│   ├── routes/
│   │   ├── api/                 # ai/chat, ai/hint, analytics, demo-login, demo-cleanup, seed
│   │   ├── auth/                # login, register, logout, Google OAuth flow
│   │   ├── dashboard/           # student home, labs, progress, history, leaderboard, profile
│   │   ├── instructor/          # students, assignments, analytics
│   │   ├── labs/                # 29 lab pages across 5 disciplines
│   │   ├── admin/               # admin & seeding
│   │   └── offline/             # offline fallback page
│   ├── hooks.server.ts          # session resolution
│   └── service-worker.ts        # PWA offline support
├── e2e/                         # Playwright end-to-end suites
├── static/                      # favicon, web manifest, service worker assets
├── docs/                        # documentation & assets (incl. this README's artwork)
└── wrangler.toml                # Cloudflare bindings & configuration

---

Testing

npm run test:run       # unit tests (Vitest, single run)
npm run test:coverage  # unit tests with coverage
npm run test:e2e       # Playwright end-to-end tests
npm run test:e2e:ui    # Playwright interactive UI mode

---

Roadmap

• Expand the experiment catalogue (organic synthesis pathways, more medical scenarios)
• Richer instructor tooling: rubric-based grading and cohort comparisons
• Real-time multiplayer lab benches
• Localized content for more African languages
• LMS integration (LTI) for universities

---

Contributing

Contributions are welcome — from new simulations to accessibility fixes.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-experiment
3. Make your changes (TypeScript, follow the existing code style, add tests for new behavior)
4. Run npm run test:run and npm run build
5. Open a pull request

Please report bugs and request experiments via GitHub Issues.

---

License

Distributed under the MIT License. See LICENSE for details.

---

Built for African education.
_{Powered by SvelteKit and the Cloudflare edge.}