This is the complete, production-ready **Business Require...

A public project built with the Lightcap AI agent by anon-33a5 — open to read, run, fork, and export. Updated .

Prompt

This is the complete, production-ready Business Requirements Document (BRD) and Entity-Relationship Diagram (ERD) specification for your delivery orchestration platform. It merges the central Laravel Web Panel, the Redis-backed queue engine, the dual Flutter/React Native mobile applications, and all the custom business logic guardrails we brainstormed into a single blueprint.

PART 1: Platform Business Requirements Document (BRD)

1. System Overview & Core Objectives

The platform is designed to handle high-concurrency, localized on-demand delivery routing. It eliminates manual scheduling by running automated, gender-isolated First-In, First-Out (FIFO) dispatch lines managed via Redis, paired with strict financial escrow rules to manage cash-on-delivery (COD) workflows securely.

2. Comprehensive User Persona Capabilities

A. Super Admin & Supervisors (Unified Laravel Web Panel)

  • Role-Based Separation: Powered by Spatie permissions, isolating operational oversight from administrative financial authority.
  • Live Dashboard Matrix: Dynamic map view tracking active moving driver pins (with unmasked PII data for supervisors) and live order queues.
  • Movable Collector Status: Supervisors can toggle their system status (Active / Inactive). Activating it instantly broadcasts an alert and shifts their map beacon color from Red to Green, telling nearby drivers where to settle cash balances.
  • Manual Store Override Routing: Ability to choose any store from a searchable dropdown and draft an order on their behalf using the split-form layout.

B. Store Operators (Mobile App / Web POS Terminal)

  • Order Formulation Engine: Standard single order submission or dynamic double order creation via the [Add Second Order] form layout.
  • Package Escrow Control: The unique capability to flag order delivery transfers as either Settled (خالص) or Unsettled Debt (غير خالص).
  • Fraud Accountability: Stores are bound by a maximum threshold of 5 fraudulent/false order notifications raised by verified drivers before facing automated account suspension and penalty assessments.

C. Logistics Drivers (Mobile App)

  • The Geofenced Shift Switch (ON/OFF Gate): Access to enter the live routing queue is completely locked until the device's physical coordinates fall within an active market hotspot.
  • Subscription Maintenance: Drivers pay for platform access in advance or on a daily basis. A zero balance blocks the account from going online.
  • Automatic Idle Triggers: The app monitors active standby periods. Drivers sitting idle for 60 continuous minutes without taking an assignment are logged out automatically.
  • The Attendance Incentive Engine: Access to high-percentage weekend reward bonuses requires completing a mandatory baseline attendance shift across Monday through Wednesday.

3. High-Dependency Logic Systems

The Double-Order Split Form Flow

When a merchant designs an order payload, the system avoids messy multi-tab navigation by handling it inside a single view:

[Fill Form: Order #1]
       │
       ├──► Action A: [ Send Single Order ] ──► Queries Redis Queue ──► Dispatches Immediately
       │
       └──► Action B: [ Add Second Order ]  ──► Spawns Form #2 Below ──► Action C: [ Send Both Orders ] 
                                                                                   │
                                                                                   ▼
                                                                     Ties both under parent_batch_id
                                                                     Grabs FIRST single driver in queue

The Unsettled Debt Protocol (2-Hour Hard Lock Lifecycle)

To secure physical cash without administrative overhead, the platform shifts tracking directly between the merchant and the operator:

  1. Flag Creation: Store taps [غير خالص] during pickup. The order database entry logs the unsettled_at timestamp.
  2. Grace Period Activation: A 2-hour backend cron task monitors this timestamp. The driver can continue delivering this specific batch.
  3. The 10-Minute Final Warning: At 1 hour and 50 minutes, an automated high-priority push notification hits the driver's screen.
  4. The Hard Lockout: If 2 hours pass without the store clearing the debt, the driver's interface triggers a structural lockdown view. The ON status is force-killed, blocking them from viewing or accepting any new orders until the store confirms receipt of the cash.

PART 2: Comprehensive Entity-Relationship Diagram (ERD)

Below is the structured relational schema written in standard database notation, complete with fields, data types, indexes, and explicit foreign key relationships.

1. System Users (users)

Stores platform staff, managing system access tiers.

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • name (VARCHAR(255))
  • email (VARCHAR(255), Unique Index)
  • password (VARCHAR(255))
  • status (ENUM('active', 'inactive'), Default 'active')
  • is_collector (BOOLEAN, Default FALSE)
  • collector_status (ENUM('active', 'inactive'), Default 'inactive')
  • created_at / updated_at (TIMESTAMP)

2. Store Registry (stores)

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • name (VARCHAR(255))
  • branch_name (VARCHAR(255), Nullable)
  • phone (VARCHAR(255), Unique Index)
  • password (VARCHAR(255))
  • category (ENUM('restaurant', 'cafe', 'retail', 'other'))
  • country / city / region (VARCHAR(100))
  • logo_path (VARCHAR(255), Nullable)
  • latitude (DECIMAL(10, 8))
  • longitude (DECIMAL(11, 8))
  • status (ENUM('active', 'suspended', 'pending_activation'))
  • activated_at (TIMESTAMP, Nullable) -> Tracks the 30-day churn warning system.
  • created_at / updated_at (TIMESTAMP)

3. Driver Profiles (drivers)

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • name (VARCHAR(255))
  • phone (VARCHAR(255), Unique Index)
  • password (VARCHAR(255))
  • gender (ENUM('male', 'female'), Index)
  • vehicle_type (ENUM('small_car', 'large_car', 'vespa'))
  • trust_status (ENUM('trusted', 'untrusted'), Default 'trusted')
  • operating_scope (ENUM('single_zone', 'multi_zone', 'all_zones'))
  • max_batch_capacity (INT, Default 2)
  • prepaid_days_balance (INT, Default 0) -> Deducted day-by-day upon toggle ON.
  • is_online (BOOLEAN, Default FALSE, Index)
  • created_at / updated_at (TIMESTAMP)

4. Orders Core Matrix (orders)

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • order_number (VARCHAR(100), Unique Index) -> The user-visible order lookup code.
  • store_id (BIGINT UNSIGNED, FK -> stores.id)
  • driver_id (BIGINT UNSIGNED, FK -> drivers.id, Nullable)
  • created_by_user_id (BIGINT UNSIGNED, FK -> users.id, Nullable) -> Identifies Supervisor override creation.
  • customer_phone (VARCHAR(255))
  • delivery_address (TEXT)
  • destination_latitude (DECIMAL(10, 8))
  • destination_longitude (DECIMAL(11, 8))
  • item_value (DECIMAL(10, 2))
  • delivery_fee (DECIMAL(10, 2))
  • preferred_vehicle (ENUM('small_car', 'large_car', 'vespa', 'general'))
  • preferred_driver_gender (ENUM('male', 'female', 'general'))
  • payment_method (ENUM('cash', 'digital'))
  • status (ENUM('pending_queue', 'dispatched', 'picked_up', 'delivered', 'cancelled', 'emergency_hold'), Index)
  • settlement_status (ENUM('pure_cash', 'unsettled_debt', 'settled'), Default 'pure_cash')
  • unsettled_at (TIMESTAMP, Nullable)
  • parent_batch_id (BIGINT UNSIGNED, FK -> orders.id, Nullable) -> Links the second order form seamlessly.
  • created_at / updated_at (TIMESTAMP)

5. Financial Transaction Ledgers (driver_ledgers)

Tracks subscription days and the multi-tier reward wallets.

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • driver_id (BIGINT UNSIGNED, FK -> drivers.id)
  • transaction_type (ENUM('subscription_deduction', 'advance_payment', 'bonus_credit', 'attendance_penalty', 'payout'))
  • amount (DECIMAL(10, 2))
  • wallet_type (ENUM('cash_balance', 'reward_wallet'), Default 'cash_balance')
  • description (TEXT)
  • created_at (TIMESTAMP)

6. Merchant Fraud Registry (store_strikes)

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • store_id (BIGINT UNSIGNED, FK -> stores.id)
  • driver_id (BIGINT UNSIGNED, FK -> drivers.id)
  • order_id (BIGINT UNSIGNED, FK -> orders.id)
  • reason (TEXT)
  • created_at (TIMESTAMP)

7. Action Lifecycle Auditing (order_histories)

  • id (BIGINT UNSIGNED, PK, Auto Increment)
  • order_id (BIGINT UNSIGNED, FK -> orders.id)
  • actor_type (ENUM('system', 'store', 'driver', 'supervisor'))
  • actor_id (BIGINT UNSIGNED) -> ID matching the actor profile entity.
  • action (VARCHAR(255)) -> e.g., 'triggered_unsettled_lock', 'supervisor_override_assignment'
  • notes (TEXT, Nullable)
  • created_at (TIMESTAMP)

4. Architectural Cardinality & Relations

  • stores hasMany orders (1:M) — A store generates many order payloads over time.
  • drivers hasMany orders (1:M) — A driver handles many delivered assignments.
  • users hasMany orders (1:M) — A Supervisor account can spawn multiple override orders on behalf of merchants.
  • orders hasMany orders (Self-Referencing 1:M via parent_batch_id) — A primary order can hold an attached secondary order spawned via the double-form workflow.
  • stores hasMany store_strikes (1:M) — Tracks fraud occurrences to automate store suspension metrics.
  • drivers hasMany driver_ledgers (1:M) — Houses financial transactions across cash deposits and locked reward balances.

what we could improve in this app

Lightcap

Lightcap Small built this together — split into 5 parts and worked in parallel, so it came together fast.

It doesn't compile yet — build failed, so the later checks couldn't run.

The 81 files are a real first draft in your workspace, not a dead end. Reply "continue" and I'll take another pass at the errors, or open the Files tab to jump in yourself.

_334.5k tokens · 41m 12s · built in parallel_

Browse all public projects

Lightcap