wmj
5b08f8b041
Comprehensive document covering: - Auth chain (how login works end-to-end) - Three-database architecture (UmmahID SQLite, V1 Mobile SQLite, Postgres) - Password management (self-heal = single source of truth) - FLH Islamic Finance endpoints and data flow - Testing checklist for future verification - Troubleshooting history
Falah Mobile — Islamic Lifestyle Platform
Falah Mobile is the mobile frontend for the Falah OS ecosystem — a Shariah-compliant digital economy platform. Built with Next.js 16 and Prisma (SQLite), it serves as a Progressive Web App (PWA) at falahos.my/mobile.
Features
🌐 Souq — Halal Service Marketplace
| Feature | Route | Status |
|---|---|---|
| Browse services w/ categories + search | /souq |
✅ |
| Advanced filters (price range, sort, delivery days) | /souq |
✅ |
| Create listing (packages, tags, images) | /souq/create |
✅ |
| Listing detail w/ packages (3 tiers) | /souq/[id] |
✅ |
| Seller profile w/ stats & listings | /souq/seller/[id] |
✅ |
| Order placement | /souq/[id] |
✅ |
| Orders list (buyer/seller tabs) | /souq/orders |
✅ |
| Order detail w/ chat, progress stepper | /souq/orders/[id] |
✅ |
| Review submission (star rating 1-5) | /souq/orders/[id] |
✅ |
| Delivery file upload | /souq/orders/[id] |
✅ |
| Seller workflow (start, deliver, confirm) | /souq/orders/[id] |
✅ |
💰 Wallet & FLH Token
- FLH Balance with live display
- Top-up via Polar.sh (5 tiers: 500–50,000 FLH)
- Cash out FLH balance
- Mock mode for development (falls back when Polar unconfigured)
- Premium multiplier (2x FLH for premium members)
🤖 Nur AI Coach
- AI-powered Islamic lifestyle coaching
- Customizable personas (Scholar, Mentor, Friend)
- Prayer tracking, Dhikr counter, Qibla compass
- Daily verses and reminders
📚 Learn — Micro-Learning Platform
- Structured courses with modules
- Certificate generation on completion
- Progress tracking & quiz assessments
- TTS audio for hands-free learning
👥 Community
- Forum with Shariah content moderation
- Private Groups with invite codes
- Gamification: XP, streaks, achievements, levels
- Referral system with FLH rewards
📱 PWA Features
- Installable on iOS/Android home screen
- Offline support
- Push notifications
- Audio playback (Dhikr, TTS, Adhan)
Tech Stack
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router, Standalone output) |
| Database | SQLite via Prisma ORM |
| Auth | Ummah ID (OIDC) + JWT (jose) |
| Payments | Polar.sh (FLH top-ups) |
| AI Chat | OpenAI-compatible API (configurable) |
| Storage | Local filesystem (public/ directory) |
| Deployment | Docker (port 4013 prod / 4014 staging) |
Architecture
Falah Mobile (Next.js 16, standalone output)
├── /mobile/ ← basePath (Traefik reverse proxy)
├── /mobile/souq/* ← Integrated marketplace
├── /mobile/wallet ← FLH wallet + top-up
├── /mobile/learn/* ← Micro-learning courses
├── /mobile/nur ← AI coaching
├── /mobile/forum/* ← Community forum
├── /mobile/api/souq/* ← Souq API endpoints
├── /mobile/api/wallet/* ← Wallet API
├── /mobile/api/webhooks/* ← Polar.sh + external webhooks
└── Prisma SQLite ← Single dev.db volume
API Routes
| Route | Description |
|---|---|
GET /api/souq/listings |
Listings with filters (category, price, sort, delivery) |
GET /api/souq/listings/[id] |
Listing detail with seller & reviews |
POST /api/souq/listings |
Create listing (auth required) |
GET /api/souq/categories |
Category list |
GET/POST /api/souq/orders |
Order CRUD |
PATCH /api/souq/orders/[id] |
Update order status, messages, delivery files |
POST /api/souq/reviews |
Create review (auth required) |
GET /api/souq/sellers/[id] |
Seller profile with stats |
POST /api/souq/upload |
File upload for deliveries |
POST /api/wallet/top-up/create-checkout |
Polar.sh checkout for FLH purchase |
POST /api/webhooks/polar-checkout |
Polar.sh webhook (credits FLH) |
Development
# Install dependencies
npm ci
# Build
npm run build
# Build Docker image
docker build -t falah-mobile:latest .
# Run production
docker compose up -d
# Run staging
docker compose -f docker-compose.staging.yml up -d
Environment Variables
See .env.example for all required vars:
JWT_SECRET— JWT signing key (required)DATABASE_URL— SQLite path (file:./dev.db)POLAR_ACCESS_TOKEN— Polar.sh API token (optional, mock mode used otherwise)POLAR_FLH_*— Product price IDs for each FLH packLLM_API_KEY— OpenAI-compatible API key for AI chat
Deployment
| Environment | Host | Port |
|---|---|---|
| Production | falahos.my (via Traefik) |
4013 |
| Staging | falahos.my/mobile-staging |
4014 |
Both run as Docker containers with persistent SQLite volumes.
Related Repositories
- Falah OS Core — Backend services, Netlify functions, landing pages
- Ummah ID — Identity service (OIDC provider)
- iStore — App marketplace (store.falah-os.com)
Built for the Ummah. Shariah-compliant by design.