01 Executive Summary

Zahraa Capital's Zone 3 has a real, narrow transportation problem: people already travel in and out of the area by car, but there is no structured way for someone with a spare seat to be found by someone who needs one. Ma3ak Fe Tareeqak solves that first, narrow problem — a community ride board, not a dispatched taxi service — and Ma3ak Delivery reuses the same trust, verification, and matching machinery for small local deliveries.

The two services share one account model, one verification pipeline, one admin panel, and one database. A resident registers once; becoming a driver or delivery provider is an additional, admin-verified capability on the same account, not a different product. This is the single most important structural decision in the whole system and it shapes almost every table and screen described below.

Given the deployment target is ordinary shared PHP/MySQL hosting (no Docker, no queue workers, no guaranteed shell access to install system packages), the architecture is deliberately a clean, dependency-light custom PHP MVC rather than a full framework — see §4 for the reasoning. Everything is designed so a future native mobile app, GPS/maps, online payments, and multi-city expansion can be added additively, without re-architecting the core.

02 Assumptions

Stated explicitly so they can be corrected rather than silently baked in.

• Legal form: this is a community-organized service, not a licensed taxi/courier dispatch company. No claim of regulatory compliance with Egyptian transportation law is made anywhere in the product (see §7 and the Legal Pages module) until you've had professional legal review.
• Single currency: EGP only for the MVP; no multi-currency support is built now (the currency column exists purely so it isn't a breaking schema change later).
• Single timezone: Africa/Cairo, stored in UTC in the database, rendered in local time.
• Cash-only MVP: per your spec, no payment gateway integration now — payment_methods/transactions exist as a real but currently CASH-only abstraction.
• No live GPS tracking in the MVP — locations are City → Area → Zone → landmark text, exactly as specified. latitude/longitude columns exist and are nullable everywhere a location is recorded.
• Single admin organization initially (one system admin, a handful of branch admins), not a multi-tenant SaaS product — branches model service lines (ride vs. delivery vs. future lines) inside one operator, not independent customers.
• Traffic volume is modest (a single residential community, growing to a handful of neighborhoods) — this justifies avoiding queues, caches, and horizontal scaling infrastructure now (see §4).
• Shared hosting has: PHP 8.1+, MySQL/MariaDB, .htaccess support (Apache), cron access, and SSH for deployment. unconfirmed — see §18.

03 Risks & Concerns

04 Design Decisions Made (and why)

Your spec explicitly asked me to push back where something would be weak, unsafe, or overengineered rather than follow it blindly. Here is every place I made a judgment call.

No framework — a small custom MVC, not Laravel

Laravel is an excellent framework, but on unconfirmed shared hosting it adds real deployment risk: it needs Composer to be runnable on the host (or a build-and-upload step), a writable storage/ tree with specific permissions, a scheduler that depends on cron being configurable, and generally assumes more control over the PHP environment than shared hosting reliably grants. None of Laravel's flagship value (Eloquent, Artisan, queues, Blade) is load-bearing for a system this size — a request/response cycle, PDO with prepared statements, a router, and a handful of service classes cover 100% of the requirements above. Decision: a small, explicit PHP 8.x MVC (see §8), Composer used only for autoloading and 2–3 tiny, framework-agnostic libraries if the host supports it, with a documented zero-Composer fallback if it doesn't.

Tailwind CSS + Alpine.js, not Bootstrap, not a JS framework

Bootstrap's RTL build is turnkey but visually generic, and the brand asks for a distinctive, restrained pastel identity — fighting Bootstrap's own opinionated components to get that look creates more work, not less. A full JS framework (React/Vue) would need a build pipeline and turns every page into an API-consuming SPA, which is unnecessary for a server-rendered, mobile-first app and complicates the "PHP renders HTML" mental model this system otherwise has throughout. Decision: Tailwind CSS (compiled once at build time into a static CSS file — no Node.js needed on the production host) for layout/visual system, with Alpine.js (≈15 KB, no build step) for the sprinkles of interactivity server-rendered pages need — bottom sheets, tabs, toasts, confirm dialogs. This is a well-worn, low-risk pairing for exactly this kind of project.

One polymorphic documents table, not three

Your spec's suggested schema lists vehicle_documents and user_documents separately. They have identical lifecycle, state machine, storage, and review UI — the only difference is what they're attached to. Duplicating the table means duplicating the review queue, the expiration job, and the access-control code three times, which is exactly the "repeated logic" your spec asks me to avoid. Decision: one documents table with owner_type (USER / VEHICLE) + owner_id, and a document_types lookup table so admins can add new required document types later without a schema change.

Ride "offers" and "requests" collapse into three tables, not five

Read literally, the spec's ride section implies separate ride_requests, ride_offers, and rides tables, with an ambiguous relationship between a driver's "offer" (in the pricing sense) and a driver's "offer" (in the published-trip sense, §10). I've resolved this into: ride_offers = a driver's published trip ("I'm going there"), ride_requests = a passenger's search intent (optional — a passenger can also just browse and book an offer directly), and ride_bookings = the actual stateful link between one passenger and one ride offer, carrying the full state machine from §13. This is fewer tables, no loss of the required states, and one obvious place to look for "what's the status of this ride."

Roles ARE capabilities — implemented as many-to-many, not a single role column

This is the load-bearing decision from your §4. user_roles is a join table, not a single enum column on users — a user can hold DRIVER and DELIVERY_PROVIDER simultaneously. Current availability (§9) is a completely separate concept from capability (§5) and is modeled in its own table, keyed by which capability is currently active.

Sessions for the web app, bearer tokens for the future API — not JWT, not OAuth2

The web/PWA app authenticates with ordinary secure PHP sessions (simplest, safest default for a server-rendered app). The REST API (needed today for the PWA's own AJAX calls, and reused unchanged by a future native app) authenticates with a long-lived, hashed personal_access_token per device — the same pattern Laravel Sanctum popularized, implemented directly, without pulling in a JWT library or standing up an OAuth2 authorization server neither of which this system's threat model or client mix actually needs yet.

No maps/GPS, no chat, no queue, no cache — deliberately deferred

Consistent with §78 of your spec ("do not overengineer"). Matching in the MVP is a deterministic SQL query (area/zone match, time window, seat count), not a geospatial one. Notifications are DB-backed and rendered in-app/PWA; there's no Redis, no message queue, no job runner — a lightweight cron script handles the two time-based jobs the system actually needs (document expiration sweep, stale-offer expiry sweep).

05 Roles, Capabilities & Permissions

Two layers that must not be confused: capabilities (what a user is allowed to be — passenger, driver, delivery provider, admin) and availability (what a verified provider is doing right now — offline / available / busy). Only the first layer maps to permissions.

Capability catalog

Permission matrix

Permissions are checked server-side, on every request, via a small policy class per resource (e.g. RideBookingPolicy::canAccept($user, $booking)) — never by hiding a button in the template. Ownership checks (§13 IDOR requirement) live in the same policy layer: a driver can only accept bookings on their own ride offers, a branch admin can only review documents belonging to users assigned to their branch.

06 Complete User Flows

6.1 Registration → becoming a verified driver

6.2 Ride: from search to completion (passenger side)

6.3 "I'm going there" (driver proactively publishes)

6.4 Delivery: creation to completion

6.5 Document rejection loop

6.6 Document expiration (automatic, cron-driven)

07 Business Rules (centralized, server-enforced)

Every rule below is enforced in one place — a service class the API/controllers call — never duplicated between the web controller and a future mobile API controller.

Driver / provider eligibility (checked before every state-changing action, not just at go-available time)

• Cannot publish a ride offer or go AVAILABLE unless driver_profiles.verification_status = APPROVED and every required document for that user+vehicle is APPROVED and not expired, and users.status = ACTIVE.
• A document expiring mid-availability immediately forces AVAILABLE → OFFLINE (checked by the expiration sweep, and re-checked defensively on every accept/publish action, not trusted from a cached flag).
• Cannot accept a booking/delivery beyond capacity — enforced by the atomic seat/slot update in §9, never by an application-level "check then write."
• Cannot accept a delivery already accepted by someone else — same atomic-conditional-update pattern, first writer wins, everyone else gets a clean "تم قبول هذا الطلب من مزود آخر" instead of a race.

Passenger / customer rules

• Cannot accept/request an EXPIRED or already-FULL offer (re-validated server-side at request time, not just filtered out of the list client-side).
• Cannot rate a ride/delivery that isn't COMPLETED, and cannot rate the same completed service twice (UNIQUE(service_type, service_id, rater_id)).

Account status gates

• SUSPENDED/BLOCKED users cannot create requests, publish offers, accept anything, or message support beyond viewing their own complaint. Existing in-flight rides/deliveries are not silently deleted — they either complete normally or an admin explicitly cancels/reassigns them (audit-logged).

08 System Architecture

A single PHP application, server-rendered, following a light MVC + service-layer split. No microservices, no separate API server — the REST API (§11) is served by the same app, same codebase, same database, just a different route prefix and auth guard.

Browser / PWA ──┐
                 │  HTTPS
Future Mobile App┘
        │
        ▼
 Apache/LiteSpeed (shared hosting)
        │  .htaccess routes everything to public/index.php
        ▼
 Front Controller (public/index.php)
        │
        ├─ Middleware pipeline: HTTPS-enforce → session/token auth → CSRF (web only)
        │                        → rate limit → route → permission policy
        ▼
 Router  ──▶  Controllers (thin: parse input, call service, render/respond)
        │
        ▼
 Services (business rules, state machines, transactions)  ◀── this is where §7 lives
        │
        ▼
 Repositories (PDO, prepared statements only)
        │
        ▼
 MySQL 8 / MariaDB (utf8mb4, InnoDB, FKs)

 Cross-cutting: Logger, Notification dispatcher (IN_APP now; PUSH/SMS/EMAIL/WHATSAPP
 as pluggable channel drivers later), Document storage adapter (local disk now;
 swappable for S3-compatible storage later), Audit log writer.

Proposed project structure

/app
  /Controllers        Web/{...}.php   Api/{...}.php
  /Services           RideService, DeliveryService, VerificationService,
                       AvailabilityService, NotificationService, ...
  /Repositories        one per aggregate (RideOfferRepository, ...)
  /Policies             ownership + permission checks per resource
  /Models               thin data objects, no active-record magic
  /Middleware
  /Validators
  /Support             Fsm.php (generic state-machine helper), Money.php, Slug.php
/config                 config.php reads getenv(), never hard-coded secrets
/database
  /migrations           plain numbered .sql files, applied by a small migrate.php runner
  /seeders              seed_dev.php (clearly marked demo data), seed_reference.php (cities/areas/zones, doc types, roles)
/public
  index.php             single front controller
  /assets               compiled Tailwind CSS, JS, icons, manifest.json, sw.js
/resources
  /views                PHP templates, partial-based, RTL by default
  /lang                 ar.php (primary), en.php (admin fallback where useful)
/routes
  web.php               session-authenticated, CSRF-protected
  api.php                token-authenticated, versioned under /api/v1
/storage
  /private/documents/{users,vehicles}/...   never web-served directly
  /logs
/tests
/docs

09 Database Architecture

39 tables, grouped by concern. utf8mb4_unicode_ci, InnoDB, explicit foreign keys, soft-delete (deleted_at) on user-facing entities that must survive for history/audit, hard timestamps everywhere. Full column-level DDL is written during Phase 2 from this design — reproduced here at entity/relationship level so it can be reviewed before a single CREATE TABLE is run.

9.1 Identity, roles & capabilities

9.2 Availability

9.3 Geography / service areas

A "location" on a ride/delivery row is not a foreign key to one universal locations table — it's an inline snapshot (*_city_id, *_area_id, *_zone_id, *_landmark, *_latitude, *_longitude) on the ride/delivery row itself, because a request's pickup point is a fact about that request at that moment, not a reusable master-data record. Only the City/Area/Zone taxonomy itself is master data.

9.4 Branches

9.5 Verification: driver, vehicle, delivery provider, documents

9.6 Rides

9.7 Deliveries

9.8 Ratings, notifications, complaints, payments, audit

10 State Machines

10.1 Ride booking (per passenger, per offer)

REQUESTED → ACCEPTED is the concurrency-critical transition: accepting attempts an atomic UPDATE ride_offers SET seats_remaining = seats_remaining - :n WHERE id = :offer_id AND seats_remaining >= :n inside a transaction. Zero affected rows ⇒ the accept fails cleanly with "لم تعد هناك مقاعد متاحة" and the booking is auto-set to a system-cancelled outcome instead of silently double-booking. ACCEPTED → CONFIRMED only fires once that update actually succeeds — they are kept as two distinct states specifically so "the driver said yes" and "the seat is actually locked" are never conflated in the data.

Terminal states are truly terminal — no code path transitions out of COMPLETED, CANCELLED_*, REJECTED, or EXPIRED. The generic Fsm helper (§8) is given an explicit adjacency map per entity and refuses any transition not in it, so this is enforced once, in code, not by convention.

10.2 Ride offer (the trip itself, independent of any one passenger)

10.3 Delivery request

AVAILABLE → ACCEPTED uses the same atomic-conditional pattern: UPDATE delivery_requests SET status='ACCEPTED', accepted_provider_id=:pid WHERE id=:id AND status IN ('AVAILABLE','OFFERED'). Zero affected rows ⇒ "تم قبول هذا الطلب من مزود آخر."

10.4 Document verification

11 API Architecture

Versioned under /api/v1. Web pages authenticate with the session cookie + CSRF token; the same endpoints accept an Authorization: Bearer <token> header for the PWA's own fetch calls today and any future native app tomorrow — one implementation, two auth guards.

Response envelope (uniform, exactly as you specified)

// success
{
  "success": true,
  "message": "تم تنفيذ العملية بنجاح",
  "data": { },
  "errors": []
}

// validation / business error
{
  "success": false,
  "message": "حدث خطأ",
  "data": null,
  "errors": [ { "field": "phone", "message": "رقم الهاتف غير صحيح" } ]
}

Auth & profile

Verification (driver / vehicle / delivery provider)

Availability

Rides

Deliveries

Ratings, notifications, complaints

Admin (web-first, mirrored to API as needed)

12 UI/UX Architecture

Visual system

Neutral warm-white surfaces, near-black ink text, soft borders — the four pastel brand tones (#FBF0B2 #FFC7EA #D8B4F8 #CAEDFF) appear only as small accents: status badges, capability chips, empty-state illustration backgrounds, and one accent color per major section of the app (rides lean blue, deliveries lean yellow) so a user develops a quiet visual sense of "which part of the app am I in" without a loud color scheme anywhere. Type: Cairo throughout, RTL by default (<html dir="rtl" lang="ar">), with numerals kept as Arabic-Indic or Western digits per a single configurable setting (Western digits recommended for price/phone clarity).

Screen inventory

Reusable component set

Button, Input, Select, Textarea, Modal, Bottom Sheet, Card, Badge, Alert, Toast, Tabs, Bottom Navigation (user-facing), Top Navigation + Sidebar (admin), Status Indicator (dot + Arabic label, never color alone), Document Card, Vehicle Card, Ride Card, Delivery Card, User Card, Rating stars, Empty State, Loading skeleton, Error state, Confirmation Dialog — each a single PHP view-partial + Tailwind classes, never copy-pasted markup.

13 Security Architecture

Authentication

• password_hash() with PASSWORD_BCRYPT (cost 12), never a custom hash.
• PHP sessions: httponly, secure, samesite=Lax cookies; session ID regenerated on login and on privilege change (capability grant).
• Login throttling via login_attempts: exponential backoff per (identifier, IP) pair; generic "بيانات الدخول غير صحيحة" for both wrong-password and unknown-account, to resist enumeration.
• Bearer tokens hashed at rest (never store the raw token), revocable per-device, expirable.

Authorization & IDOR

• Every resource-fetching controller action resolves the resource, then calls its Policy with (current_user, resource) before touching the response — never trusts that a valid-looking ID in the URL implies access. This is a hard rule, not a guideline: repositories return the row, the policy decides if the caller may see it, the controller never skips the policy call.
• Branch-scoping is enforced at the query layer (branch admins' list queries are pre-filtered by their assigned branches; there is no admin screen that shows unscoped data by omission).

Document security (§8 of your spec, non-negotiable)

• Stored under /storage/private/documents/{users|vehicles}/{randomized-uuid}.{ext}, outside the web root if the host allows a directory above public_html; if not, inside it but behind a hard deny from all .htaccess, with a PHP streaming endpoint as the only access path.
• Server-side validation on every upload: real MIME sniffed via finfo (never the client's Content-Type), extension cross-checked against an allow-list from document_types.allowed_mime_types, size checked against max_size_mb, and the file is never trusted by its original name — a fresh UUID filename is generated server-side.
• Every view/download is authorization-checked and written to document_access_logs — "who looked at whose ID card, when" must always be answerable.

Standard web hardening

• SQL injection: PDO prepared statements exclusively — no string-concatenated queries anywhere, enforced by code review discipline plus a lint check in CI.
• XSS: all output through a single e() escaping helper in views; no raw echo $_....
• CSRF: per-session token, required on every state-changing web form; the API's bearer-token requests are exempt (no ambient credential to forge) but still origin-checked.
• Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy (script-src self + Google Fonts only), Strict-Transport-Security once HTTPS is confirmed on the host.
• Rate limiting on auth + write endpoints, keyed by IP and by user, stored in a small counter table (no Redis needed at this scale).

Concurrency-as-a-security-property

Double-booking a seat or double-accepting a delivery isn't just a bug — it's a fairness/trust failure for a community platform. Both are closed exclusively via atomic, single-statement conditional UPDATE ... WHERE patterns inside a transaction, never a PHP-level "read the count, then decide" (§10, §61).

14 Testing Strategy

Required edge cases (from your §71 — all must have an explicit test)

• Two users request the last seat simultaneously → exactly one CONFIRMED, one clean rejection.
• Driver cancels after acceptance → cascades to affected bookings + notifications, never a silent orphan.
• Document expires while provider is AVAILABLE → forced OFFLINE, verified by the expiration sweep test.
• Suspended user with an active ride → ride still resolves; user cannot start new ones.
• Delivery provider double-accept race → same atomic guarantee as rides.
• User requests another user's document by ID → 403, logged as a suspicious access attempt.
• Ride/delivery ID substitution (IDOR) across every mutating endpoint.
• Negative/zero/absurd price or passenger count → rejected server-side even if the client-side form was bypassed.
• Malicious upload: PHP payload renamed .jpg, oversized file, disallowed MIME → all rejected before ever touching disk with the wrong name.
• Direct role/capability tampering via a crafted request → rejected, since capabilities are only ever written by the verification service, never accepted as client input.
• Session expiry mid-multi-step form (e.g., mid document upload) → clear re-login prompt, no partial/corrupt state persisted.

15 MVP Scope

16 Phase-by-Phase Implementation Plan

Per your §87, each phase ends with: tests run, DB integrity checked, security re-checked, mobile UI + RTL checked, authorization re-checked, docs updated — then the next phase starts. No phase is skipped or parallelized into "build everything, test at the end."

17 Deployment Architecture (shared hosting)

No Docker, no container registry, no orchestrator — none of that is available on typical shared hosting, and none of it is needed at this scale. The realistic deployment shape is:

Local/dev machine
   │  git push
   ▼
GitHub repository (private)
   │  either:
   │   (a) SSH + git pull on the host, if the shared plan exposes SSH + git, or
   │   (b) SFTP/rsync of changed files, if it doesn't
   ▼
zahara.m3lsh.com  (public_html/ = /public, everything else one level up if the
                    plan allows a directory outside the web root; otherwise
                    /storage/private/ locked down via .htaccess as the fallback)
   │
   ├─ Apache + PHP-FPM (or mod_php) — confirm version on host
   ├─ MySQL/MariaDB database (separate credentials, never in Git)
   ├─ Cron (host-provided, cPanel-style) running:
   │     - php artisan-equivalent scripts/expire_documents.php   (daily)
   │     - php scripts/expire_stale_offers.php                    (hourly)
   └─ .env (uploaded once, out of Git, permissions 600)

Migrations are plain numbered .sql files applied by a tiny migrate.php CLI runner (tracks applied migrations in a migrations table) — no framework migration tool required. This keeps "how do I stand up a fresh copy of this database" a one-command answer on a host where Composer/Artisan may not be available at all.

18 Questions & Decisions Requiring Your Confirmation