falah-mobile/docs/wiki/Production-Bugfix-Plan.md

# FalahMobile — Production Readiness Bugfix Plan

> **Lead:** pi-agent · **Date:** 2026-07-06 · **Branch:** `staging` · **Target:** `stagingx.falahos.my`

---

## Situation Report

Complete codebase audit of FalahMobile identified **25 issues** across 6 independent domains. Zero file overlap between domains enables parallel execution.

### Build Status (Before)

| Check | Status |
|-------|--------|
| `next build` | ❌ Fails — TypeScript errors |
| `tsc --noEmit` | ❌ 10 errors (missing deps, conflicting types) |
| ESLint | ❌ Circular dependency crash |
| Vitest | ❌ Missing deps |
| Playwright | ❌ Missing deps |

---

## Squad Execution Plan

```
                    ┌─────────────────────────────────────┐
                    │  Lead: pi-agent                      │
                    │  - Branch: staging                   │
                    │  - Coordination & QA gate            │
                    │  - Gitea wiki                        │
                    └─────────────────────────────────────┘
                                    │
        ┌───────────┬───────────────┼───────────────┬───────────┐
        │           │               │               │           │
   ┌────┴────┐ ┌────┴────┐  ┌──────┴──────┐ ┌──────┴──────┐ ┌──┴──────┐
   │Squad 1  │ │Squad 2  │  │ Squad 3     │ │ Squad 4     │ │Squad 5  │
   │Security │ │ Build   │  │ Money       │ │ Core Chat   │ │ Profile │
   │OpenCode │ │OpenCode │  │ OpenCode    │ │ OpenCode    │ │Claude   │
   └────┬────┘ └────┬────┘  └──────┬──────┘ └──────┬──────┘ └──┬──────┘
        │           │               │               │           │
   3 files      3 files          2 files          1 file      1 file
```

| Squad | Commander | Files | Task |
|-------|-----------|-------|------|
| 🛡️ **Security** | OpenCode | `chat/daily/route.ts`, `chat/history/[userId]/route.ts`, `forum/posts/route.ts` | Add auth verification & premium checks |
| 🏗️ **Build** | OpenCode | `package.json`, `node_modules/` | Install missing devDeps, fix vitest setup |
| 💰 **Money** | OpenCode | `wallet/route.ts`, `wallet/page.tsx` | Fix cashout balance deduction, UI refresh |
| 🧠 **Core Chat** | OpenCode | `nur/page.tsx` | Wire send/receive, persona API, mood check-in |
| 👤 **Profile** | Claude | `profile/page.tsx` | Replace hardcoded data with `useAuth()` |

### Quick Fixes (Applied Directly by Lead)

| # | Fix | File |
|---|-----|------|
| 1 | Remove JWT fallback secret — fail loudly in prod | `src/lib/auth.ts` |
| 2 | Fix ESLint config — remove circular dependency | `eslint.config.mjs` |
| 3 | Fix tsconfig — exclude test files from build check | `tsconfig.json` |
| 4 | Fix `.gitignore` — wildcard `.env*` coverage | `.gitignore` |
| 5 | Fix `/dua` → `/prayer` slash command | `nur/page.tsx` |
| 6 | Fix forum thread detail query param | `forum/[threadId]/page.tsx` |

---

## QA Gate Checklist

> **Non-negotiable.** Every item must pass before staging deployment.

### Build & Type Safety
```
[ ] next build --webpack                — Compiles without errors
[ ] tsc --noEmit                        — Zero type errors
[ ] eslint src/                         — Zero lint errors
```

### Tests
```
[ ] npx vitest run                      — All unit tests pass
[ ] npx playwright test                 — All e2e tests pass
```

### Functional Verification
```
[ ] Auth flow: register → login → protected route
[ ] Cashout flow: create cashout → balance deducted
[ ] Nur chat: send message → AI responds → message appears
[ ] Persona switch: change scholar → API called → persisted
[ ] Mood check-in: select mood → stored in localStorage
[ ] Forum: create thread → post reply → view thread detail
[ ] Prayer times: loads with geolocation
[ ] Halal Monitor: search city → shows map with markers
[ ] Wallet: balance displayed correctly → cashout submitted
```

### Security
```
[ ] All API endpoints auth-protected (except login/register)
[ ] No hardcoded secrets in source code
[ ] Premium-gated features return 403 for free users
```

### Docker & Deployment
```
[ ] docker build -t falah-mobile:staging .   — Builds successfully
[ ] Docker Swarm stack deploys cleanly
[ ] Health check passes after deployment
[ ] Traefik routes correctly
```

---

## Deployment Runbook — Staging

### 1. Build Docker Image
```bash
docker build -t falahos/falah-mobile:staging .
```

### 2. Push to Registry
```bash
docker tag falahos/falah-mobile:staging git.falahos.my/falahos/falah-mobile:staging
docker push git.falahos.my/falahos/falah-mobile:staging
```

### 3. Deploy to Swarm
```bash
# Update the service with the new image
docker service update \
  --image git.falahos.my/falahos/falah-mobile:staging \
  --with-registry-auth \
  falah_falah-mobile
```

### 4. Verify
```bash
docker service ps falah_falah-mobile
curl -I https://stagingx.falahos.my/mobile
```

### 5. Rollback (if needed)
```bash
docker service rollback falah_falah-mobile
```

---

## Infrastructure

### Docker Swarm Stack
- **Manager Node:** `vmi3361598` (Contabo VPS, 8GB RAM)
- **Stack Name:** `falah`
- **Service:** `falah_falah-mobile`
- **Image:** `falahos/falah-mobile:latest` → staging tag
- **Proxy:** Traefik with Let's Encrypt
- **Route:** `Host(falahos.my) && PathPrefix(/mobile)`
- **Data:** SQLite on Docker volume `falah-mobile-data`

### Credentials (Bitwarden: `bitwarden.falahos.my`)
- **Gitea:** `wmj` / `Abedib@99` at `git.falahos.my`
- **Staging SSH:** `root@13.140.161.244` / `Abedib@99`
- **Gitea API Token:** `hermes-bot` token

---

## Rollback Procedure

```bash
# Rollback the service to previous image
ssh root@13.140.161.244
docker service rollback falah_falah-mobile
docker service ps falah_falah-mobile

# If rollback fails, redeploy from known-good backup
docker service update \
  --image falahos/falah-mobile:latest \
  falah_falah-mobile
```