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

docker build -t falahos/falah-mobile:staging .

2. Push to Registry

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

# 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

docker service ps falah_falah-mobile
curl -I https://stagingx.falahos.my/mobile

5. Rollback (if needed)

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

# 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