Booking System – Production Case Study

Overview

This repository documents the design and implementation of a real-world chauffeur booking platform built for a transportation company.

The production system includes instant quotes, multi-step reservations, authentication, admin dashboards, and driver workflows. This case study focuses on architecture and decisions, not sensitive code.

---

System Architecture

• Frontend: React + TypeScript
• Backend: Hono (Edge-first)
• Platform: Cloudflare Pages
• Database: SQL (migrations-based)
• Auth: Session/JWT-based (role-aware)
• Deployment: CI/CD with environment separation

graph TB
    subgraph Client["Client Layer"]
        Browser["Browser/Mobile App<br/>React + TypeScript"]
    end
    
    subgraph Edge["Edge Backend - Cloudflare"]
        API["Hono API<br/>Request Validation<br/>Auth Middleware"]
        Auth["Authentication<br/>JWT/Session"]
        RateLimit["Rate Limiting<br/>Error Handling"]
    end
    
    subgraph Database["Database Layer"]
        SQL[("SQL Database<br/>Migrations-based<br/>Indexed Tables")]
    end
    
    subgraph Services["Operational Services"]
        Status["Booking Status<br/>Transitions"]
        Admin["Admin Assignment<br/>Workflows"]
        Notify["Driver<br/>Notifications"]
        Audit["Audit<br/>Logging"]
    end
    
    Browser -->|HTTPS/JSON| API
    API --> Auth
    API --> RateLimit
    API -->|Secure Connection| SQL
    SQL -.->|Background Ops| Status
    SQL -.->|Background Ops| Admin
    SQL -.->|Background Ops| Notify
    SQL -.->|Background Ops| Audit
    
    style Client fill:#e1f5ff
    style Edge fill:#fff4e1
    style Database fill:#f0e1ff
    style Services fill:#e1ffe1

Loading

🏗️ System Architecture Overview

The booking system is designed as an edge-first, modular full-stack application optimized for performance, security, and operational clarity.

High-Level Architecture

Client (Browser / Mobile)

• React + TypeScript frontend
• Multi-step booking flow
• Form validation and optimistic UI updates
• Role-aware routing (Customer / Admin / Driver)

⬇️ HTTPS (JSON APIs)

Edge Backend (Cloudflare Pages + Hono)

• Lightweight API layer deployed at the edge
• Request validation and normalization
• Authentication middleware
• Business logic orchestration
• Rate limiting and error handling

⬇️ Secure DB Connection

Database Layer

• Relational SQL database
• Migration-based schema management
• Strict separation of read/write operations
• Indexed booking and availability tables for fast queries

⬇️ Background Operations

Operational Services

• Booking status transitions
• Admin assignment workflows
• Driver notifications
• Audit logging for system events

Authentication & Authorization Flow

Role-based access control (RBAC)

Separate permissions for:

• Customers (booking & history)
• Admins (pricing, vehicles, assignments)
• Drivers (assigned trips only)

Session/JWT-based authentication All protected routes enforced server-side

Deployment & Environments

• Development: Local Vite + mocked services
• Staging: Production-like environment for validation
• Production: Edge deployment with environment-isolated secrets

Environment variables are strictly scoped per deployment and never exposed client-side.

Design Principles

• Edge-first performance
• Minimal backend surface area
• Explicit trust boundaries
• Fail-safe defaults
• Client safety over convenience

This architecture enables fast booking experiences, secure admin operations, and scalable growth without exposing sensitive business logic.

---

Core Booking Flow

flowchart LR
    A["1. Service &<br/>Vehicle Selection"] --> B["2. Instant<br/>Pricing Calculation"]
    B --> C["3. Customer Details<br/>& Confirmation"]
    C --> D["4. Admin<br/>Assignment"]
    D --> E["5. Driver<br/>Notification"]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#fce4ec
    style E fill:#f3e5f5

Loading

---

Security Considerations

• Environment-based secrets
• Role-based access (Admin / Driver / Customer)
• Input validation & rate limiting
• Sanitized public endpoints

---

Code Snippets

API Route Structure

// api/routes/booking.ts
import { Hono } from "hono";

const booking = new Hono();

booking.post("/quote", async (c) => {
  const input = await c.req.json();

  // Validation only — no pricing logic exposed
  if (!input.service || !input.vehicle) {
    return c.json({ error: "Invalid request" }, 400);
  }

  return c.json({
    success: true,
    message: "Quote request accepted",
  });
});

export default booking;

Auth Middleware Pattern

export const requireRole = (role: "admin" | "driver") => {
  return async (c, next) => {
    const user = c.get("user");

    if (!user || user.role !== role) {
      return c.json({ error: "Unauthorized" }, 403);
    }

    await next();
  };
};

Frontend Booking Step Component

type BookingStepProps = {
  onNext: () => void;
};

export function BookingStep({ onNext }: BookingStepProps) {
  return (
    <section>
      <h2>Select Service</h2>
      <button onClick={onNext}>Continue</button>
    </section>
  );
}

---

What's Not Included (By Design)

• Production database schema
• Authentication secrets
• Payment logic
• Admin credentials
• Client-specific business rules

---

Screenshots

• Customer booking flow
• Admin dashboard (redacted)
• Vehicle management
• Booking timeline

---

Lessons Learned

• Edge deployments reduce latency for quote calculations
• Explicit role separation simplifies admin logic
• Sanitizing public demos protects clients and IP

---

Tech Stack Summary

React · TypeScript · Hono · SQL · Cloudflare · Vite

---

Author

Yoseph B. Gebremedhin Full Stack Developer – Production systems, not demos