System Architecture & Features Document
Prepared by:
Gehad El-Sobky
Digital Transformation & AI Consultant
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
Executive Summary
This document defines the complete System Architecture and Feature Specification for a next-generation, bilingual (Arabic + English), dual-platform (iOS + Android) on-demand home services marketplace targeting the State of Qatar as the primary market, with architecture designed for GCC-wide expansion in Phase 3.
The platform enters with full Arabic RTL support, Android from day one, a B2B corporate accounts vertical, a loyalty and subscription engine, and an AI-powered bilingual assistant features.
Full Arabic RTL
Android + iOS Day One
B2B Corporate Vertical
AI-Powered Assistant
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
1
Product Overview & Application Components
Platform Architecture Overview
The platform is a two-sided marketplace connecting consumers (demand) with verified home service vendors (supply), mediated by a platform layer that handles discovery, booking, payment, quality assurance, and logistics. A separate B2B layer serves corporate accounts with contract-based billing.
Application Components
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
2
Service Lines & Categories
The platform launches with six core service categories. Each category supports multiple sub-services with distinct pricing models. Expansion categories are added in Phases 2 and 3.
Laundry (غسيل)
Wash & Fold, Dry Clean, Iron Only, Carpet, Shoe, Curtains, Per item / Per kg
Home Cleaning (تنظيف المنازل)
Regular, Deep, Move-In/Out, Post-Construction, Studio to Villa packages
Car Wash (غسيل السيارات)
Exterior, Interior, Full Detail, Engine Clean, At-Home, Fleet, Per vehicle
AC Cleaning (تنظيف المكيفات)
Split Unit, Cassette, Central AC Duct, Filter Replacement, Sanitization
Pest Control (مكافحة الحشرات)
General Insects, Cockroach, Rodents, Bed Bugs, Termites, Preventive
Home Products Store (متجر المنزل)
Laundry Care, Cleaning Supplies, Trash Bags, Mops & Brushes, e-commerce
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
3
User Roles & Permissions
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
4
Feature Specifications — Customer Application
3.1 Authentication & Onboarding
Phone OTP Login
Qatar +974 default, international supported. 6-digit OTP
Google / Apple Sign-In
OAuth 2.0 via Firebase Auth.
Biometric Login
Face ID / Touch ID / Fingerprint.
Language Selection
Full-screen selector on first launch: العربية (RTL) / English (LTR).
Profile Setup
Display name, language, profile photo, notification preferences, address.
Guest Browsing
Browse all vendor listings without account. Cart state preserved in local storage. Checkout requires account, smooth transition with cart preserved after login.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
5
Address Management & Vendor Discovery
Address & Location Management
01 GPS Auto-Detect
One-tap "Use my current location." Reverse geocodes via Google Maps Geocoding API. Map pin confirmation. iOS precise / Android foreground location.
02 Address Book
Unlimited saved addresses with custom labels (Home / Work / Other / Custom). Building, Floor/Apt, Street, Zone, Google Maps pin. Default auto-selected at checkout.
03 Zone Matching
Service zones as GeoJSON polygons. Customer address geocoded and matched against zone polygons. Only vendors serving the customer's zone shown. Zone boundaries configurable by admin without app update.
Home Screen & Vendor Discovery
01 Home Screen
Dynamic: zone-based greeting, promo banner, 8-tile category grid, "Top in your area" carousel, draft cart, personalized recommendations, featured vendor. All managed from Admin CMS.
02 Vendor Listing
Card grid/list toggle. Ranking: Zone match → Premium pinned → Score = (0.4 × proximity) + (0.35 × rating) + (0.25 × acceptance_rate). Real-time availability dot.
03 Search & Filter
Full-text Arabic + English simultaneously (PostgreSQL tsvector). Filters: category, rating, price, availability, verified badge. Sort: Nearest / Highest Rated / Most Reviewed / Lowest Price / Fastest.
04 Vendor Profile Page
Cover photo, bilingual name, star rating breakdown, operating hours, service catalog, photo gallery, reviews, response rate, share/favorite, "Book now" CTA pinned at bottom.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
6
Order Flow
Real-time push notification at each transition with Arabic and English message. In-app timeline view with timestamps for full order visibility.
Service Selection
Step-by-step booking per category. Laundry: item picker + care notes. Cleaning: apartment size → add-ons → frequency. Car Wash: vehicle type → wash type. Running price total shown at each step.
Scheduling
Calendar with highlighted available dates. Vendor-defined time slots with capacity remaining shown. Min 2-hour lead time. Reschedule up to 1 hour before pickup. Estimated duration per service type.
Cart Management
Persistent cart (survives app close). Multiple services from same vendor. Special instructions per item (200-char). Itemised price breakdown with platform fee transparent. Cart auto-expires after 48 hours.
Cancellation Policy
Free: >1 hour before pickup. 20% fee: within 1 hour. 100% fee: vendor already picked up. Reason required. Refund to original payment method within 3–5 business days.
Re-Order
One-tap re-order from history. Pre-fills: same vendor, services, quantities, instructions. Prompts for new date/time. Favourite combinations saveable as "Templates" (max 5, Phase 2).
Recurring Booking
Weekly or monthly repeat schedule. Auto-confirmation if vendor has availability. Pause up to 2 months/year. Resume with one tap. 7-day cancellation notice required.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
7
Payment Features
QPAY Integration
Primary gateway for Qatar domestic transactions. QPAY checkout widget embedded natively in-app (no browser redirect). VISA, Mastercard, Qatar bank cards. QCB compliant. Settlement: T+1 to platform escrow.
Stripe Integration
International cards + Apple Pay (iOS) + Google Pay (Android) via Stripe. 3D Secure for transactions >QAR 200. Card tokenisation — zero raw card data on platform servers. Stripe Radar fraud detection.
Cash on Delivery
Available for service orders only. COD limit: QAR 500/order. Vendor marks COD collected at handoff. Platform deducts commission from next payout cycle. Disableable per vendor or zone by admin.
In-App Wallet
Holds refund credits, referral rewards, promo credits. Auto-applied at checkout (toggleable). Min withdrawal: QAR 50. Balance expires after 12 months of inactivity.
Payment Hold Model
Services: authorised at checkout → held in escrow → released to vendor after "Delivered" + 24-hour dispute window. Products: captured immediately. Hold duration: max 10 days before auto-release.
Promo Codes
Validation: expiry, category restriction, min order value, single-use, total uses cap, user segment. One promo + one vendor discount simultaneously. Best code auto-suggested. Invalid code shows specific reason.
Refund Workflow
Customer initiates with reason + photos. Support ticket auto-created. Ops reviews within 24 hours. Auto-approval for claims P0 — Launch
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
8
Reviews, Trust & Loyalty
Reviews & Trust System
Post-Order Review
Unlocked only after "Delivered" status. Push notification within 2 hours. 1–5 stars overall + sub-ratings (punctuality, quality, communication). Bilingual comment + up to 3 photos. Vendor can reply within 14 days.
Review Moderation
Auto-moderation: keyword filter in Arabic + English. NLP sentiment analysis flags very negative reviews for priority human review. Vendor can report a review — false reports add penalty to vendor record.
Vendor Rating Calculation
Weighted rolling average: last 90 days = 70%, older = 30%. Min 5 reviews before public rating shown (prior: "New" badge). Rating recalculated in real-time on each new review. Displayed to 1 decimal place.
Loyalty & Gamification
Points Earning Engine
1 pt per QAR 1 on services; 0.5 pts on products. Bonus: First order (+50), App review (+20), Photo review (+10), Referral (+100 both sides), Subscription (+30/mo), Gold upgrade (+100), Platinum (+200). Points ledger is immutable.
Membership Tiers
Silver (0–499 pts): standard. Gold (500–1,999 pts): 5% bonus points, free pickup >QAR 80, priority support. Platinum (2,000+ pts): 10% bonus, express access, 1 free delivery/month, exclusive deals. Tier maintained with 1 order in last 90 days.
Points Redemption
100 points = QAR 5. Min: 100 pts. Max per order: 30% of order total. Applied as line-item discount. Points expire 12 months after last transaction. Expiry warning push 30 days before.
Referral Program
Unique link via Firebase Dynamic Links. Referee: QAR 10 wallet credit after first order (min QAR 50). Referrer: 100 points. Max 10 successful referrals/month. Self-referral prevention via device fingerprinting.
Subscription Plans
Laundry Plan QAR 120/mo (4 pickups), Cleaning QAR 250/mo (2 sessions), Car Wash QAR 100/mo (4 washes), Ultimate Bundle QAR 340/mo. Auto-charge monthly. Pause up to 2 months/year.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
9
AI Assistant & Smart Features
Bilingual AI Chatbot
RAG Knowledge Base
Order Tracking via Chat
Smart Recommendations
Complaint Intake
Human Escalation
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
10
Notifications & Communication
Push Notifications
Via Firebase Cloud Messaging (FCM) for iOS + Android. Bilingual templates: ar and en versions sent in user's language. Categories with individual opt-in/out: Order Updates (mandatory), Promotional (opt-in), Loyalty & Points (opt-in), Reminders (opt-in). Rich notifications with order photo thumbnail. Deep-link to specific order/screen.
SMS Fallback
Critical notifications via SMS when push fails (device off, no internet, push disabled). SMS categories: OTP, Order Confirmed, Order Delivered, Payment Failed, Payment Confirmed. Provider: Twilio or AWS SNS with Qatar local sender ID. Arabic SMS uses native Arabic encoding (not transliterated). SMS opt-out via reply STOP.
In-App Notification Center
Bell icon with unread count badge. Scrollable history of all notifications (stored in database — no expiry). Mark as read individually or "mark all read." Distinct icons per notification type. Tap navigates to relevant screen. Filter by category. Unread count persisted server-side across devices.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
11
Feature Specifications — Vendor Portal
Vendor Onboarding
Automated bilingual email at each state change. Approved vendors receive portal access grant and welcome email with onboarding guide.
Vendor Registration
Self-service form. Required: business name (AR + EN), commercial registration number, owner name, mobile (OTP verified), email, bank IBAN. Documents: commercial license, owner ID, bank letter. Form saves progress — resumable.
Service Catalog Setup
Service name (AR + EN), description, pricing model (flat / per item / per kg / per sqm / per unit), base price, min order value, photos (up to 10 per service). Pricing tables for laundry items. Mark services active/inactive without deleting.
Zone Assignment
Admin assigns zones during verification. Vendor requests additional zones via portal (admin approval required). Zones displayed on map. Vendor can set different availability per zone. Zone coverage affects search visibility.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
12
Vendor Order Operations, Analytics & Payouts
Order Operations
Order Queue Dashboard
Real-time incoming orders (WebSocket). Each card: customer name, service summary, pickup slot, total value, time to respond. 30-minute SLA to accept/reject. Auto-decline if no response → hurts acceptance rate KPI.
Order Detail View
Customer address on map, service items with quantities and instructions, pre-order photos. Status update buttons: Picked Up → In Process → QC Done → Out for Delivery → Delivered. Post-delivery: upload completion photos.
Capacity Management
Weekly calendar: booked vs available per slot. Define working hours per day. Set capacity per time slot per category. Block specific dates. Recurring availability templates. Changes take effect immediately.
Order Messaging
Per-order message thread. Templates: pickup confirmation, clarification request, ready ETA, delay notice, custom. 200-char limit. All messages archived permanently with order record.
Analytics & Payouts
Revenue Dashboard
KPI cards: total revenue, orders, avg order value, completion rate, acceptance rate. Revenue chart + breakdown by category. Week-over-week and month-over-month comparison. Next payout date and estimated amount.
Performance Analytics
Rating trend (90-day rolling). Cancellation rate by reason. Customer retention rate. Response time trend. SLA compliance rate. Benchmark vs category average (anonymised). Low-performance alerts with recommended actions.
Premium Tier & Badge
Requirements: Rating ≥4.5, Acceptance ≥90%, Completion ≥95%, no active disputes, min 20 orders. Gold: QAR 150/mo. Platinum: QAR 400/mo. Badge shown on listing, profile, and search results.
Payout Calculation
Weekly every Sunday. Formula: Gross revenue − Platform commission − Dispute penalties + Adjustments. COD: payout = net of commission only (vendor already collected cash). Calculation visible to vendor before transfer.
Bank Transfer
Transfer to verified IBAN on file. Vendor receives push + email with transfer reference. Failed transfer: Finance Admin notified immediately. Payout history: full list with itemised breakdown, downloadable as PDF.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
13
Feature Specifications — Admin Panel
Platform Operations
Vendor Onboarding Queue
Filterable list of all pending applications. Bulk actions: approve / reject / request info. Document viewer inline. Notes field per application. SLA tracker: applications pending >48 hours flagged amber.
User Management
Search by phone, name, email. View full profile: order history, wallet, loyalty points, reviews, subscriptions. Actions: suspend, reset password, merge duplicates, grant wallet credit. Export CSV with filters.
Vendor Management
Search by name, zone, tier, status. Full vendor profile: metrics, orders, payouts, disputes. Actions: approve/reject, suspend, upgrade/downgrade tier, edit zones, add notes. Mass notification to vendor segments.
Order Operations
Global order search by ID, customer, vendor, status, date range. Manual status override with mandatory reason (audit-logged). SLA breach alerts: orders in "Placed" >35 min without vendor response highlighted red.
Dispute Management
Dispute queue with 24-hour SLA countdown. Full evidence panel: complaint, photos, order detail, chat transcript, vendor response. Vendor penalty: 3 confirmed-fault disputes → warning; 5 → tier demotion; 8 → suspension review.
Promo Code Manager
Create codes: discount type (% or fixed QAR), min order, max discount cap, category restriction, user segment, valid dates, max uses, single-use toggle. Activate/deactivate instantly. Bulk generate for campaigns (e.g., 500 unique one-time codes).
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
14
Admin Finance, Analytics & Marketing
Finance & Payouts
Payout Approval Queue
Weekly batch auto-calculated every Sunday. Finance Admin reviews before transfer authorisation. Per-vendor detail: gross revenue, commission, penalties, adjustments, net payout. Edit individual payouts with mandatory note. Approve all / reject / hold for dispute.
Revenue Reporting
Platform P&L: GMV, platform revenue (commissions), refunds issued, net revenue, active subscriptions MRR. Revenue by category and by zone. Commission rate analysis by vendor tier. Downloadable Excel with raw data.
Platform Analytics
Investor-grade: DAU/MAU ratio, retention cohort table, order frequency distribution, avg order value trend, NPS score, vendor supply health, customer LTV distribution. Exportable for board reports.
Marketing & Content
Push Campaigns
Targeted push campaigns: segment by zone, last-order-date cohort, membership tier, language. Bilingual message editor (AR/EN simultaneously). Schedule or send immediately. Preview on mock device. Delivery rate, open rate, CTR tracking. A/B test two message variants (50/50 split).
Home Screen CMS
Manage home screen banner (image upload, deep link URL, start/end date, language targeting). Manage featured vendors (drag-and-drop reorder). Manage service category grid order and icons. All changes apply immediately to production app without app update.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
15
B2B Corporate Accounts
Phase 2
Company Registration
Via web portal or admin-assisted. Required: company name (AR + EN), commercial registration number, billing address, primary admin contact. Documents: commercial license, authorized signatory ID. Finance Admin verification SLA: 2 business days.
Sub-Account Management
Corporate Admin invites employees by email or phone. Roles: Department Manager (view team orders, approve) / Employee (place orders only). Up to 200 employee accounts per company. Per-department monthly spend limits with 80% alert notifications.
Service Contract
Contract parameters: service types, agreed pricing (discounted), assigned vendor(s), coverage zones, monthly order limit, contract duration (6 or 12 months), auto-renewal. Contract stored as PDF accessible by Corporate Admin and Finance Admin.
Monthly Invoicing
Auto-generated on 1st of each month. Format: company details, itemised order list (date, service, employee, amount), subtotal, VAT, total. Payment: bank transfer Net 30. Automated reminders at day 7, 14, 21 for overdue invoices.
Corporate Reporting
Dashboard: total spend this month, orders by department, most used services/vendors, 12-month spend trend. Per-employee order history. Budget remaining. Export: Excel with full order data filterable by employee / department / service / date.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
16
Backend Module Structure
Each module in the NestJS backend is a self-contained domain with its own controller, service, repository, DTOs, and events. No module imports another module's repository directly. Cross-module data access goes through the module's exported service interface.
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
17
Phase 2 & Phase 3 Roadmap
Phase 2 — Differentiation & Growth
Goal: Build new features. Create switching costs through loyalty, subscriptions, and B2B.
- Loyalty & Referral: Points engine, membership tiers (Silver/Gold/Platinum), redemption at checkout, referral program with Firebase Dynamic Links
- Subscription Engine: Monthly recurring plan billing, Stripe subscription API, pause/resume/cancel workflow
- B2B Corporate Module: Company registration, sub-accounts, service contracts, monthly invoice generation, corporate reporting dashboard
- AI Chatbot: Claude API / GPT-4o, pgvector RAG pipeline, Arabic + English NLP, order tracking via chat, complaint intake, human escalation WebSocket handoff
- Vendor Analytics: Performance dashboard, monthly report export, Premium tier SLA scorecard
- Photo Logging & Express Tier: Pre-pickup photo capture, vendor receipt confirmation, express tier pricing + dedicated vendor network
- Marketing & Admin: Push campaign tool (segments + A/B test), platform analytics dashboard, Home Screen CMS, wallet system
Phase 3 — Scale & GCC Expansion
Goal: Expand to KSA and UAE markets. Build the logistics layer (Driver App).
- GCC Market Launch: Saudi Arabia (Riyadh, Jeddah), UAE (Dubai, Abu Dhabi) — separate zone/vendor networks, localised pricing
- Multi-Currency Support: QAR, SAR, AED, KWD with real-time FX handling
- Driver App (React Native): GPS-based job assignment, navigation, proof of pickup/delivery, earnings dashboard
- New Service Categories: Swimming Pool Maintenance + Deep Home Services (Handyman, Plumbing)
- AI-Powered Smart Scheduling: ML model predicts optimal pickup time slots per zone per day
- Franchise Vendor Model: High-performing vendors operate a sub-network of workers under their brand
- Hotel & PMS Integrations: Mews, Opera, Protel for hospitality B2B
- Microservices Extraction: Order Service, Payment Service, Notification Service extracted first
- Advanced Investor Analytics: Cohort LTV curves, churn prediction, NPS trend, burn rate tracking
© 2026 Gehad El-Sobky. Clarity. Progress. Growth.
18
Laundry Mobile App