docs: update README with full CE feature docs, architecture, and deployment guide
This commit is contained in:
root
@@ -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
|
## Features
|
||||||
npm run dev
|
|
||||||
# or
|
### 🌐 Souq — Halal Service Marketplace
|
||||||
yarn dev
|
| Feature | Route | Status |
|
||||||
# or
|
|---------|-------|--------|
|
||||||
pnpm dev
|
| Browse services w/ categories + search | `/souq` | ✅ |
|
||||||
# or
|
| Advanced filters (price range, sort, delivery days) | `/souq` | ✅ |
|
||||||
bun dev
|
| 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.
|
# Build
|
||||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
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.*
|
||||||
|
|||||||
Reference in New Issue
Block a user