Ticketing System - Architecture & Technical Documentation

1. Executive Summary

Ticketing System is a high-performance, distributed ticketing and fleet management system built on a microservices architecture. It handles everything from route planning and bus scheduling to secure ticket booking, payments, and real-time transit notifications.

---

2. Technology Stack

• Backend: Python 3.11+ with FastAPI (Asynchronous processing).
• Database: PostgreSQL (Relational data & persistence).
• Message Broker: RabbitMQ (Event-driven architecture).
• In-Memory Store: Redis (Real-time tracking & Payment Idempotency).
• Frontend (Customer): React.js with Vite & Tailwind CSS.
• Desktop App (Company Admin): C# / Avalonia UI (Cross-platform .NET).
• Authentication: JWT (JSON Web Tokens) with cross-service verification.
• Infrastructure: Docker & Docker Compose for container orchestration.

---

3. Client Ecosystem

• Customer Web Portal: React-based booking platform for passengers.
• Company Admin Dashboard: Avalonia UI desktop application for fleet and staff management.
• POS Mobile App (Point of Sale): React Native / Expo application for station agents to issue physical tickets and process on-site payments.
• Driver Mobile App: Mobile application for real-time trip tracking and ticket validation (QR scanning).

---

4. Core Technical Concepts & Logic

A. Event-Driven Notifications (RabbitMQ)

To keep the system decoupled, we use a Producer-Consumer pattern.

• Producers: ticketing-service, payment-service, and company-service.
• Consumer: notification-service.
• Logic: When a ticket is sold or a bus is swapped, the originating service publishes a "Topic" message to RabbitMQ. The Notification Service listens for these topics and triggers emails/SMS. This ensures that if the notification service is slow, it doesn't slow down the actual booking process.

B. Payment Idempotency (Redis)

To prevent duplicate charges (e.g., a user clicking "Pay" twice due to bad internet):

• Mechanism: Every payment request includes a unique idempotency_key (UUID) generated by the frontend.
• Check: The payment-service checks Redis for this key before processing. If it exists, it returns the previous result immediately without re-charging or re-saving.
• Persistence: Success results are cached in Redis for 24 hours.

C. Concurrency Control (Row-Level Locking)

In a high-traffic environment, two people might try to book the last seat at the exact same millisecond.

• Logic: We implement Pessimistic Locking using SQLAlchemy's .with_for_update().
• Result: When a user starts a booking, the database "locks" that specific Bus row. The second user’s request waits until the first is finished. If the first user takes the last seat, the second user receives a "Bus Full" error instead of a double booking.

D. Secure Ticketing (HMAC QR Codes)

Tickets must be tamper-proof.

• Logic: Instead of just a plain ID, the QR code contains a Signed Token.
• Mechanism: We use HMAC-SHA256 with a SECRET_KEY. When a driver scans the code, the qr-service re-calculates the signature. If even one character of the ticket was modified, the signature won't match, and the ticket is rejected.

---

5. Microservices Breakdown

1. auth-service

Manages users, roles (Customer, Driver, Company Admin, Super Admin), and JWT issuance.

2. company-service

The "Brain" of operations.

• Manages Buses, Routes, and Schedules.
• Bus Swap Logic: Allows an admin to replace a broken bus with a new one. It automatically migrates all active passengers to the new bus and checks if the new bus has enough capacity for the existing bookings.

3. ticketing-service

Handles the creation and listing of tickets. It calculates seat availability and generates the secure QR tokens.

4. payment-service

Integrates with Payment Providers (simulated for Momo/Card). Implements the Redis-based idempotency layer.

5. notification-service

The central hub for user engagement. Listens to RabbitMQ and routes alerts to Email/SMS providers.

6. tracking-service

Uses Redis to store high-frequency GPS coordinates from drivers. Allows customers to see where their bus is on a map in real-time.

7. ai-service

Provides an intelligent assistant for both customers (help booking) and admins (fleet analytics).

---

6. Security Architecture

1. Gateway Security: Nginx acts as a reverse proxy, hiding internal microservice ports from the public internet.
2. Internal Communication: Services communicate via a dedicated Docker network (ticketing-net).
3. Data Integrity: Passwords are never stored in plain text (Bcrypt hashing).
4. Encryption: Critical payloads are encrypted via common.middleware.EncryptionMiddleware.

---

7. How to Run (Development)

1. Environment: Ensure you have .env files in each service directory (or root).
2. Start Services:

   docker compose up -d --build

3. Database Migration: Handled automatically by services on startup or via Alembic.
4. Access:
   • Frontend: http://localhost:3000
   • Super Admin: http://localhost:3001
   • Backend API (Gateway): http://localhost:8000

---

Document Version: 1.0.0 | Date: Dec 20, 2025