falah-mobile/HANDOVER.md

# Falah Mobile — Micro Learning Platform Handover

## Project Overview

Falah Mobile is a Next.js 16 PWA serving a full Islamic lifestyle platform (Nur AI coaching, Halal marketplace, community, wallet, and **micro learning courses**). The micro learning module is the focus of this handover — a complete E2E system for browsing, purchasing, consuming, and certifying bite-sized (5 min) courses derived from books.

Production URL: `https://falahos.my/mobile`
Staging URL: `https://falahos.my:4014/mobile`

### Repository

| Detail | Value |
|:-------|:------|
| **Source path (server)** | `/root/falah-mobile` |
| **Gitea remote** | `http://git.falahos.my/wmj/falah-mobile.git` (internal: `localhost:3080/wmj/falah-mobile.git`) |
| **Gitea repo ID** | `1` |
| **Full name** | `wmj/falah-mobile` |
| **Default branch** | `main` |
| **Last commit** | `bfd3509` — "docs: update README with full CE feature docs, architecture, and deployment guide" |
| **GitHub mirror** | `https://github.com/maifors/falah-mobile.git` (auto-synced via Gitea cron) |


## ✅ What Is Complete (Live)

### Course Library — 4 Courses, 21 Modules, 6 Categories

| Course | Author | Modules | Category |
|--------|--------|:-------:|:---------|
| Atomic Habits | James Clear | 5 | Self Improvement |
| The Defining Decade | Meg Jay | 6 | Self Improvement |
| Simplicity Parenting | Kim John Payne | 5 | Self Improvement |
| Tao Te Ching | Lao Tzu | 5 | Self Improvement |

6 categories defined (Self Improvement ✅, Basic Quran/Hadith/Prayer/History/Finance — empty, ready for content).

### Course Content Delivery
- **Course listing** with category badges + search bar + category filter tabs
- **Course detail page** with module timeline, progress bar, quiz badges
- **Module page** with lesson content (markdown), Listen 🎧 button, Quiz section
- **TTS audio** using browser Web Speech API with female voice selection (preferred: Google UK English Female → Samantha → Microsoft Zira → fallback)
- **Markdown stripping** for TTS (strips `#`, `##`, `**bold**`, `*italic*`, `[links]`, `> quotes`, `- lists`, `1. lists`, `` `code` ``)
- **Quiz system** — 3–5 multiple-choice questions per module, submit/score/retry
- **Certificate issuance** — auto-issued when all modules completed, with PDF generation and serial number. Displayed as 🎓 View Certificate badge on course detail page.

### Payments & Subscription
| Product | Price | Status |
|---------|:-----:|:------:|
| Atomic Habits (one-time) | $4.99 | ❌ Not mapped in checkout (old courses only have 3 mapped) |
| The Defining Decade (one-time) | $4.99 | ❌ Not mapped in checkout |
| Simplicity Parenting (one-time) | $4.99 | ❌ Not mapped in checkout |
| Tao Te Ching (one-time) | $4.99 | ❌ Not mapped in checkout |
| Learn Pass Monthly | $9.99/mo | ✅ Live on Polar |
| Learn Pass Annual | $79.99/yr | ✅ Live on Polar |
| In-app toggle (monthly/annual) | — | ✅ LearnPassCard component |

**IMPORTANT:** The checkout API at `src/app/api/learn/checkout/route.ts` only has `PRODUCTS` mapping for the *original 3 courses* (atomic-habits, deep-work, 7-habits). New courses (defining-decade, simplicity-parenting, tao-te-ching) need their Polar price IDs added to this map for individual purchase to work.

### Demo Credentials
- `demo@falahos.my` / `password123` (Premium, FLH 10,000)
- `premium@falahos.my` / `Premium123!` (Premium, FLH 50,000)

### TTS Voice
- Client-side browser SpeechSynthesis with voice selection
- Pitch: 1.15, Rate: 0.9

---

## 📋 Pending / Next Steps

### Priority: Phase 5+ Course Content (27 more courses)
39-course library planned. Only 4 built. Remaining 35 courses span 6 categories:
- **Self Improvement** (14 more needed) — Deep Work, 7 Habits, Mindset, Learning How to Learn, You Are Awesome, Al-Ghazali, Rumi, Love Languages, Whole-Brain Child, Crucial Conversations, How to Talk So Kids Will Listen, etc.
- **Basic Quran** (0/8 courses) — need content creation
- **Basic Hadith** (0/6 courses) — need content creation
- **Basic Prayer & Worship** (0/6 courses) — need content creation
- **Basic Islamic History** (0/5 courses) — need content creation
- **Basic Islamic Finance** (0/4 courses) — need content creation

Each course follows the micro-learning template:
```
5 modules × 5 min each
3–5 multiple-choice questions per module (format: {questions: [{question, options[], correctIndex}]})
Key takeaway per module
```

Course seed file template: `/root/falah-mobile/scripts/seed-phase4.ts`

### Priority: Add New Courses to Checkout
The `PRODUCTS` map in `src/app/api/learn/checkout/route.ts` needs entries for each new course that has a Polar price. Create Polar products first, then add `"course-{slug}": { priceId, name, metadata, tier: "one_time" }` to the map.

### Priority: Course Image / Thumbnail Art
Course cards have emoji + gradient placeholders. Need proper cover images stored in `public/courses/` or served via Gitea.

### Other Backlog
- **Gitea course sync** — `/root/falah-mobile/scripts/init-gitea-courses.sh` syncs course content from Gitea. Script exists but needs testing.
- **Server-side TTS generation** — Current Web Speech API is client-side. Could use Azure Cognitive Services or ElevenLabs for higher quality.
- **Certificate PDF design** — Current PDF generation in `src/lib/learn.ts` (functions: `generateCertificatePdf`, `generateSerialNumber`, `buildVerifyUrl`). Design may need polish.
- **Admin dashboard** — No admin UI for course management. Courses are seeded via DB scripts.
- **Course progress analytics** — No analytics on completion rates, quiz scores, popular courses.

---

## 📦 Tech Stack

| Layer | Technology |
|-------|-----------|
| **Framework** | Next.js 16 (App Router, React Server Components) |
| **Language** | TypeScript |
| **Database** | SQLite (production: `/app/data/dev.db` on Docker volume) |
| **ORM** | Prisma v5.22 (schema at `prisma/schema.prisma`) |
| **Auth** | Ummah ID (external service) — JWT delegation |
| **Styling** | Tailwind CSS, dark theme (`#07090C` bg, `#C9A84C` gold, `#00C48C` green) |
| **Payments** | Polar.sh (checkout API, webhooks) |
| **TTS** | Browser Web Speech API (`SpeechSynthesisUtterance`) |
| **Certificate PDF** | Generated server-side (see `src/lib/learn.ts`) |
| **Deployment** | Docker (standalone Next.js output) |
| **Reverse Proxy** | Traefik (routes `/mobile/*` → `falah-mobile:3000`) |
| **Host** | Contabo VPS (Ubuntu 24.04) |
| **Git** | Gitea at `git.falahos.my` |

---

## 🏗 Architecture

### Deployment Flow
```
Source: /root/falah-mobile/
  → npm run build (produces .next/standalone)
  → docker build -t falah-mobile:latest .
  → docker compose up -d --no-deps falah-mobile
```

### Route Structure (Next.js App Router, basePath: "/mobile")
```
/mobile
  /learn                    ← Course catalog with search + category tabs (client)
  /learn/[slug]             ← Course detail with module timeline (client)
  /learn/[slug]/[moduleId]  ← Module reader: content + TTS + quiz (client)
  /api/learn
    /courses                ← GET: list courses (supports ?category=&search=)
    /courses/[slug]          ← GET: course detail + modules + enrollment
    /categories             ← GET: list all categories
    /categories/seed        ← POST: seed categories (dev only)
    /checkout               ← POST: create Polar.sh checkout or mock purchase
    /progress               ← POST: mark module complete (auto-issues certificate at 100%)
    /tts                    ← GET: module text; POST: request audio
    /certificates           ← GET: user's certificates
    /certificates/[serial]  ← GET: single certificate
    /sync                   ← POST: sync from Gitea
```

### Key Source Files
| File | Purpose |
|------|---------|
| `prisma/schema.prisma` | All data models (LearnCourse, LearnModule, LearnEnrollment, etc.) |
| `src/app/learn/page.tsx` | Course catalog with category tabs + search |
| `src/app/learn/[slug]/page.tsx` | Course detail + timeline + certificate badge |
| `src/app/learn/[slug]/[moduleId]/page.tsx` | Module reader + TTS + quiz |
| `src/app/api/learn/courses/route.ts` | Course listing API with category/search/filter |
| `src/app/api/learn/courses/[slug]/route.ts` | Course detail API |
| `src/app/api/learn/categories/route.ts` | Categories API |
| `src/app/api/learn/checkout/route.ts` | Polar checkout (update PRODUCTS map for new courses!) |
| `src/app/api/learn/progress/route.ts` | Progress + certificate issuance |
| `src/app/api/learn/tts/route.ts` | TTS text endpoint |
| `src/app/api/learn/certificates/route.ts` | User certificates |
| `src/lib/learn.ts` | Certificate PDF generation, serial number |
| `src/lib/prisma.ts` | Prisma client singleton |
| `src/lib/auth.ts` | JWT auth middleware |
| `src/components/LearnPassCard.tsx` | Subscription monthly/annual toggle |
| `scripts/seed-phase4.ts` | Course seed template |
| `Dockerfile` | Builds standalone Next.js production image |

---

## 🔧 Key Skills for Continuation

1. **Prisma ORM with SQLite** — schema changes (`db push`), seed scripts, query patterns
2. **Next.js 16 App Router** — file-based routing, server/client components, API routes
3. **React (useState, useEffect, useCallback, useMemo)** — all frontend pages are client components
4. **Polar.sh API** — checkout creation, webhook handling, subscription management
5. **Docker deployment** — multi-stage build, volume mounts, compose orchestration
6. **Tailwind CSS** — theming (dark mode, custom color palette)
7. **Web Speech API** — browser TTS voice selection
8. **SQLite** — direct DB manipulation for quick data fixes (seed scripts, format migrations)

---

## ⚙️ Common Commands

```bash
cd /root/falah-mobile

# Build
npm run build

# Deploy
docker build -t falah-mobile:latest .
docker compose up -d --no-deps falah-mobile

# DB operations
docker cp falah-mobile-falah-mobile-1:/app/data/dev.db /tmp/dev.db
# edit /tmp/dev.db with sqlite3
docker cp /tmp/dev.db falah-mobile-falah-mobile-1:/app/data/dev.db
docker restart falah-mobile-falah-mobile-1

# Prisma schema change
npx prisma db push    # applies schema changes to SQLite directly

# Check logs
docker logs falah-mobile-falah-mobile-1

# Seed categories endpoint (dev only, on rebuild)
curl -X POST https://falahos.my/mobile/api/learn/categories/seed

# API test
curl -s https://falahos.my/mobile/api/learn/courses | python3 -m json.tool
```

---

## 🐛 Known Issues

1. **Health check slow** — Docker health check for mobile container takes 30s+ to become "healthy", but API works immediately (HTTP 200).
2. **`.env` permission error** — Container logs show `EACCES: permission denied, open '/app/.env'` despite env vars being loaded correctly via Docker compose.
3. **New courses not individually purchasable** — Checkout `PRODUCTS` map only has 3 old courses mapped. New courses need Polar price IDs added.
4. **Staging shares volume** — `falah-mobile-staging` and `falah-mobile` production share the same DB volume. Restarting staging after production writes can cause DB contention.
5. **No category icon for course thumbnails** — Thumbnail uses category's icon/color gradient, but some courses may have missing visuals.
6. **Course card click doesn't navigate on course detail page** — Module cards have `router.push()` but the nested "Listen" button's `stopPropagation()` may cause issues. Direct URL navigation works (`/mobile/learn/{slug}/{module-slug}`).