JAHEEZ — جاهز

Smart Delivery & Errands Platform — Safi, Morocco

JAHEEZ is a multi-app delivery and errand platform connecting customers with local drivers. Users order food, groceries, pharmacy items, parcels, or custom errands. Drivers accept and fulfill deliveries. Admins manage the platform.

---

Apps in This Monorepo

---

Prerequisites

• Node.js ≥ 18
• npm ≥ 9
• Expo CLI: npm install -g expo-cli (or use npx expo)
• Expo Go app on your phone (for mobile testing)
• Supabase project (for backend)
• A code editor (VS Code recommended)

---

Environment Setup

1. Copy environment files

# Root (for admin API)
cp .env.example .env

# User app
cp user-app/.env.example user-app/.env

# Admin panel
cp admin/.env.example admin/.env

2. Fill in your Supabase credentials

Get these from your Supabase project dashboard → Settings → API:

• SUPABASE_URL / EXPO_PUBLIC_SUPABASE_URL / VITE_SUPABASE_URL
• SUPABASE_ANON_KEY / EXPO_PUBLIC_SUPABASE_ANON_KEY / VITE_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY (root .env only — for admin API)

3. Optional services

• Infobip — SMS OTP (set INFOBIP_API_KEY and INFOBIP_BASE_URL)
• Stripe — Card payments (set STRIPE_SECRET_KEY and EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY)
• ModernMT — Dynamic translation (set EXPO_PUBLIC_MODERNMT_API_KEY)

---

Running the User App

cd user-app
npm install
npx expo start

Then scan the QR code with Expo Go on your phone, or press:

• a — Open on Android emulator
• i — Open on iOS simulator
• w — Open in web browser

---

Running the Driver App

cd driver-app
npm install
npx expo start

---

Running the Admin Panel

cd admin
npm install
npm run dev

Opens at http://localhost:5173. Login requires an admin account.

---

Running the Admin API

# From root directory
npm install
node scripts/admin-api.js

Runs on http://localhost:3001. Required for:

• Admin panel authentication
• User registration (phone-disabled fallback)
• Store/driver/order management

Creating an Admin Account

node scripts/create-admin.js

Seeding Sample Stores

node scripts/seed-stores.js

---

Project Structure

jaheez/
├── user-app/          # Customer mobile app (Expo/React Native)
├── driver-app/        # Driver mobile app (Expo/React Native)
├── admin/             # Admin web panel (Vite/React)
├── shared/            # Shared TypeScript types & constants
├── scripts/           # Backend scripts (admin API, seeding)
├── supabase_schema.sql   # Database schema
├── docs/              # Project documentation
└── design/            # Design reference images

---

Design System

All colors, fonts, spacing, and shadows are defined in:

• user-app/constants/brand.ts — Single source of truth

Key brand colors:

• Red #F03030 — Primary CTA, buttons, brand
• Yellow #F5CE2E — Accents, backgrounds, brand
• Background #FEFDF8 — Warm white screen background

Font family: Cairo (Arabic-first, supports Latin)

---

Common Troubleshooting

Metro bundler port conflict

# Kill existing Metro process
npx kill-port 8081
# Or start on a different port
npx expo start --port 8082

Clear Metro cache

cd user-app
npx expo start --clear

Missing Supabase credentials

If you see [JAHEEZ] ❌ Missing Supabase credentials, copy .env.example to .env and fill in your values.

Expo Go “incompatible version”

Make sure your Expo Go app version matches the SDK version (55). Update Expo Go from the app store.

---

Documentation

See docs/ for detailed documentation:

• PROJECT_DISCOVERY.md — What JAHEEZ is
• PROJECT_IMPROVEMENT_STRATEGY.md — Improvement roadmap
• CURRENT_PROJECT_STATUS.md — Current development status
• APP_STRUCTURE_AUDIT.md — Codebase structure
• SCREEN_AND_FEATURE_STATUS.md — Screen-by-screen status
• TECHNICAL_AUDIT.md — Dependencies and config analysis
• MISSING_WORK.md — Outstanding tasks

---

Security

⚠️ Never commit .env files with real credentials. Use .env.example as a template.

The .gitignore is configured to exclude:

• .env files (in root, user-app, driver-app, admin)
• node_modules/
• Native build artifacts

Jaheez