falah-mobile/README.md

# 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](https://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

```bash
# 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 pack
- `LLM_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.*