docs: update README with full CE feature docs, architecture, and deployment guide

2026-06-24 07:08:25 +02:00
parent cfff74e2db
commit bfd3509add
1 changed files with 140 additions and 22 deletions
@@ -1,36 +1,154 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Falah Mobile — Islamic Lifestyle Platform

-## Getting Started
+**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).

-First, run the development server:
+---

-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+## 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
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### API Routes

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+| 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) |

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+---

-## Learn More
+## Development

-To learn more about Next.js, take a look at the following resources:
+```bash
+# Install dependencies
+npm ci

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+# Build
+npm run build

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+# Build Docker image
+docker build -t falah-mobile:latest .

-## Deploy on Vercel
+# Run production
+docker compose up -d

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+# Run staging
+docker compose -f docker-compose.staging.yml up -d
+```

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+### 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.*