JAHEEZ — Smart Delivery & Errands Platform

جاهز — “Ready” in Arabic. A multi-app motorcycle-delivery and errand platform built for Safi, Morocco.

JAHEEZ connects customers ordering food, groceries, and errands with motorcycle drivers in their city. It consists of four separate apps managed from a single monorepo.

---

Architecture

Frontend UI  →  Backend API/Socket  →  Routes  →  Middleware/Validators
→  Controllers  →  Services  →  Repositories  →  Supabase/PostgreSQL

Frontend apps are display clients only. Pricing, promos, permissions, fraud detection, finance, dispatch, payout, delay logic, and all business-critical mutations live exclusively in the backend.

Online card payments are intentionally disabled. Only Morocco-compatible providers (CMI, Payzone, Cashplus) will be enabled after staging validation passes. Stripe is not supported.

---

Project Layout

Jaheez-v1/
├── backend/                    Node.js + Express + TypeScript API
│   └── src/
│       ├── features/           17 domain modules (see below)
│       ├── middleware/         Auth, RBAC, validation, error handling
│       ├── redis/              Redis client (ephemeral state only)
│       ├── workers/            Dispatch + heartbeat background workers
│       ├── notifications/      Push notification sender
│       ├── validators/         Zod request validators
│       └── utils/              Shared utilities
├── frontend/
│   ├── user-app/               Expo SDK 55 — customer mobile app
│   ├── driver-app/             Expo SDK 55 — driver mobile app
│   └── admin/                  Vite + React — web admin panel
├── shared/                     TypeScript types & constants (shared across apps)
├── supabase_migrations/        SQL migrations (009 → 056, 47 files)
├── supabase_schema.sql         Full schema snapshot
├── scripts/                    Dev/test utility scripts
├── docs/                       Architecture and audit documents
└── LOCAL_SETUP.md              Complete local dev setup guide

The active mobile apps are under frontend/. Do not run Expo from old root-level user-app/ or driver-app/ directories — those are legacy remnants.

---

Applications

Backend API

Path: backend/ Port: 3002 Run: npm run dev (inside backend/)

Stack:

• Node.js 20+
• TypeScript (strict mode)
• Express 4
• Supabase PostgreSQL (source of truth)
• Socket.IO (real-time order tracking)
• Redis (ephemeral — heartbeats, locks, offer timers)
• JWT (separate secrets per role: admin, driver, customer)
• Zod (runtime request validation)
• Winston (structured logging)
• Vitest (unit tests)

Backend Domain Modules (src/features/):