Delivery Platform

A full-stack SaaS platform for restaurant delivery management. Restaurants can manage drivers, delivery zones, working hours, subscriptions, and real-time order fulfillment — all from a modern web dashboard.

---

Overview

Delivery Platform is a multi-tenant delivery management system built for restaurants that run their own delivery operations. It provides role-based portals for platform administrators, restaurant owners, and drivers, with features including:

• Restaurant management — profiles, working hour programs, and zone configuration
• Driver management — availability tracking, assignment, and QR-based delivery confirmation
• Delivery operations — order creation, driver assignment, commission tracking, and COD management
• Subscription billing — trial periods, plan management, and Stripe payment integration
• Geographic zones — radius and polygon-based delivery areas with per-km commission rates
• Automated scheduling — background jobs for working-hour activation and restaurant status management

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Local development setup                  │
│                                                              │
│  ┌──────────────┐         ┌──────────────────────────────┐  │
│  │   Frontend   │         │        Docker Compose         │  │
│  │  Next.js 15  │────────▶│  ┌──────────┐  ┌──────────┐  │  │
│  │  npm run dev │         │  │ Backend  │  │  MySQL   │  │  │
│  │  :3000       │         │  │ Laravel  │──│   8.0    │  │  │
│  └──────────────┘         │  │  :8000   │  │  :3307   │  │  │
│                           │  └────┬─────┘  └──────────┘  │  │
│                           │       │ Queue + Scheduler    │  │
│                           └───────┴──────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Layer	Technology
Frontend	Next.js 15, React 19, Tailwind CSS 4, shadcn/ui
Backend	Laravel 12, PHP 8.2, Laravel Sanctum
Database	MySQL 8.0
Payments	Stripe
Maps	Leaflet, Google Maps, Foursquare
Infrastructure	Docker, Docker Compose

---

Project Structure

delivery/
├── delivery-front/          # Next.js frontend application
│   ├── src/app/             # App Router pages (admin, owner, driver portals)
│   ├── src/components/      # UI components (shadcn/ui, maps, charts)
│   └── Dockerfile
├── delivery-back/
│   └── delivery/            # Laravel API backend
│       ├── app/             # Controllers, models, middleware
│       ├── database/        # Migrations and seeders
│       ├── routes/api.php   # REST API endpoints
│       └── Dockerfile
├── docker-compose.yml       # Orchestrates all services
├── .env.example             # Environment variable template
└── README.md

---

Prerequisites

• Docker 24+ and Docker Compose v2+ (for backend + database)
• Node.js 18+ and npm (for the frontend, run locally)

---

Quick Start

1. Clone the repository

git clone <repository-url>
cd delivery

2. Configure environment variables

cp .env.example .env

Edit .env if you need to change ports or add Stripe/API keys.

3. Start the backend (Docker)

docker compose up --build

This starts four containers:

Service	URL	Description
Backend API	http://localhost:8000	Laravel REST API
API Health	http://localhost:8000/up	Health check endpoint
MySQL	localhost:3307	Database (host port; internal port is 3306)

On first launch, the backend runs migrations and seeds demo accounts with sample data via DemoUserSeeder (no Faker/dev dependencies required).

4. Start the frontend (locally)

In a separate terminal:

cd delivery-front
cp .env.local.example .env.local
npm install
npm run dev

Service	URL
Frontend	http://localhost:3000

The frontend runs outside Docker for now — this avoids production-build SSR issues while the app is still being stabilized. The backend, database, queue, and scheduler all run in Docker.

5. Stop services

docker compose down

To also remove the database volume:

docker compose down -v

---

User Portals

The application provides separate interfaces for each role:

Portal	URL	Description
Restaurant Owner	http://localhost:3000/restaurants-owner	Dashboard, deliveries, drivers, zones
Restaurant Signup	http://localhost:3000/restaurants	Registration and login
Driver App	http://localhost:3000/driver	Delivery assignments and QR scanning
Admin Panel	http://localhost:3000/admin	Subscription plan management

---

Demo Credentials

After seeding, use these accounts to log in immediately (no OTP required — emails are pre-verified):

Role	Email	Password	Login URL
Platform Admin	admin@delivery.test	123	http://localhost:3000/admin/login
Restaurant Owner	owner@delivery.test	123	http://localhost:3000/restaurants-owner/login
Driver	driver@delivery.test	123	http://localhost:3000/driver/login

The demo owner (Sara Benali) has 3 restaurants, 11 menu items, 4 drivers, 5 clients, delivery zones, working hours, and sample deliveries. Additional driver/client accounts use password 123 as well.

Demo email verification: With APP_DEMO_MODE=true (default in Docker), OTP codes are shown on the verification page instead of being emailed. Sign up or log in with an unverified account to see the code.

Re-seed demo data: docker compose exec backend php artisan db:seed --class=DemoUserSeeder --force

---

Environment Variables

Variable	Default	Description
FRONTEND_PORT	3000	Frontend host port
BACKEND_PORT	8000	Backend API host port
DB_PORT	3307	MySQL host port (mapped; internal port is 3306)
DB_DATABASE	delivery	Database name
DB_USERNAME	delivery	Database user
DB_PASSWORD	delivery_secret	Database password
NEXT_PUBLIC_API_URL	http://localhost:8000	API URL for the browser
STRIPE_KEY	—	Stripe publishable key (backend)
STRIPE_SECRET	—	Stripe secret key (backend)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY	—	Stripe publishable key (frontend)
NEXT_PUBLIC_FOURSQUARE_API_KEY	—	Foursquare API key for map search

---

Development (Without Docker)

Backend only (local PHP + MySQL)

cd delivery-back/delivery
composer install
cp .env.example .env
php artisan key:generate
# Configure DB credentials in .env
php artisan migrate --seed
php artisan db:seed --class=DemoUserSeeder --force
php artisan serve          # http://localhost:8000
php artisan queue:listen   # separate terminal

Frontend (recommended)

cd delivery-front
cp .env.local.example .env.local
npm install
npm run dev                # http://localhost:3000

---

API Documentation

The backend exposes a RESTful API under /api. A Postman collection is included at:

delivery-front/Delivery.postman_collection.json

Key endpoint groups:

• Auth — /api/login, /api/signup, /api/verify-otp
• Restaurants — /api/restaurant
• Deliveries — /api/delivery
• Drivers — /api/driver
• Zones — /api/zone
• Subscriptions — /api/subscription, /api/payment
• Working Hours — /api/restaurant/{id}/working-hours

Full API documentation is available in delivery-back/delivery/documentation.md.

---

Docker Services

Container	Purpose
delivery-mysql	MySQL 8.0 database with persistent volume
delivery-backend	Laravel API server with auto-migration on startup
delivery-queue	Queue worker for transactional emails (OTP verification, driver welcome, delivery QR codes)
delivery-scheduler	Cron scheduler for working-hour and restaurant activation

The frontend is run locally with npm run dev (see Quick Start). A Dockerfile is included in delivery-front/ for future containerized deployment.

Useful commands

# View logs for a specific service
docker compose logs -f backend

# Run artisan commands
docker compose exec backend php artisan migrate:status

# Rebuild a single service
docker compose up --build frontend

# Reset everything (including database)
docker compose down -v && docker compose up --build

---

Features Highlights

Working Hour Programs

Restaurants can define multiple schedule programs (e.g., "Summer Hours", "Ramadan Hours") with date-bounded auto-activation. A background scheduler ensures the correct program is active at any given time.

Delivery Zones

Support for both radius-based and polygon-based delivery zones with configurable per-kilometer commission rates and user fees.

Driver Workflow

Drivers log in via a dedicated portal, view available deliveries, self-assign orders, and confirm deliveries through QR code scanning.

Subscription & Billing

Integrated Stripe payments with trial periods, monthly/yearly plans, and subscription-gated feature access.

---

Author

Built by Taha Hammdate at Zaytech Software.

---

License

This project is proprietary. All rights reserved.