root
155 lines
4.9 KiB
Markdown
155 lines
4.9 KiB
Markdown
# 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.*
|