From bfd3509add15f365981f2126990ba21c8a06dc26 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 24 Jun 2026 07:08:25 +0200 Subject: [PATCH] docs: update README with full CE feature docs, architecture, and deployment guide --- README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 140 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index e215bc4..5868875 100644 --- a/README.md +++ b/README.md @@ -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.*