# ably-labs/realtime-ticket-booking-solution architecture

> Architecture diagram of the GitHub repository ably-labs/realtime-ticket-booking-solution, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ably-labs/realtime-ticket-booking-solution
- Repository: https://github.com/ably-labs/realtime-ticket-booking-solution

## Overview

##### Project Type and Purpose
- This project is a real-time ticket booking solution that ties together event booking with streaming data pipelines. The README clearly states that it relies on a Confluent Platform running Kafka, ksqlDB, and Schema Registry. It further uses modern frameworks such as FastAPI for the web API and Ably for real-time client communications. Ngrok is used to expose services externally.

##### Analyzing the File Structure
- Top-level files:
- app.py: Likely the entry point for the FastAPI application handling API requests.
- models.py: Contains domain and data models, representing business logic.
- requirements.txt: Lists Python dependencies (like FastAPI, other libraries).
- LICENSE, .gitignore, README.md: Contain meta and guidance information.
- Directories:
- queries: Contains ksqlDB SQL queries (ksqldb-queries.sql) that interact with Kafka streams.
- schemas: Holds Avro schema definitions (booking-schema.avsc, conference-schema.avsc) and documentation (schemas.md). This directory indicates the use of a Schema Registry and structured message formats.
- test-scripts: Contains scripts for testing booking and event creation functionality.
- The layout shows a focused backend service that integrates with streaming infrastructure and schema validation.

##### Key Components
a. API Layer (Backend):
- FastAPI service (from app.py) that processes incoming HTTP requests related to ticket booking.
- Connection from the API to the underlying business logic defined in models.py.

b. Messaging and Streaming Infrastructure:
- Kafka Broker: Indicate the Kafka clusters responsible for handling messages.
- ksqlDB: Highlight the use of ksqlDB for querying streaming data using the SQL queries found in the 'queries' directory.
- Schema Registry: Include the external service that validates the Avro schemas stored in the 'schemas' folder (booking and conference schemas).

c. Real-Time Communication and External Services:
- Ably: Represent Ably as the component handling real-time WebSocket communications or messaging to end clients.
- Ngrok: Note Ngrok’s role as a tunneling service providing external access to the otherwise local API endpoints.

d. Test Components:
- Test-scripts: Reference these as part of quality assurance and simulation for booking events.

##### Relationships and Interactions
- User requests arrive at the FastAPI service.
- The API processes ticket bookings and communicates with Kafka to publish booking events.
- Kafka, configured with the Schema Registry, validates messages against Avro schemas.
- ksqlDB uses the queries from the queries folder for real-time stream processing.
- Ably serves as the external edge, pushing processed updates to clients, possibly via WebSockets.

##### Architectural Patterns and Technologies
- Separation between the API layer (FastAPI and business logic) and the streaming platform (Kafka ecosystem).
- Integration points where external tooling (Ably, Ngrok) connects to the internal services.
- Mention the use of Avro schemas and Schema Registry, which help maintain consistent messaging formats across systems.
- That the solution follows principles such as decoupled architecture via messaging and enables real-time communication via websocket-based services (Ably).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        Client["Client (User)"]:::external
        Ngrok["Ngrok Tunnel"]:::external
        Ably["Ably Real-time Gateway"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        FastAPI["FastAPI Service (app.py)"]:::api
        Models["Business Logic/Models (models.py)"]:::api
    end

    %% Messaging and Streaming Layer
    subgraph "Messaging and Streaming"
        Kafka["Kafka Broker"]:::stream
        SchemaRegistry["Schema Registry"]:::stream
        ksqlDB["ksqlDB Engine (queries)"]:::stream
        subgraph "Avro Schemas"
            BookingSchema["booking-schema.avsc"]:::stream
            ConferenceSchema["conference-schema.avsc"]:::stream
        end
    end

    %% Auxiliary Testing
    TestScripts["Test Scripts"]:::test

    %% Connections
    Client -->|"HTTP_Request"| Ngrok
    Ngrok -->|"forwards_request"| FastAPI
    FastAPI -->|"processes_booking"| Models
    FastAPI -->|"publishes_event"| Kafka
    Kafka -->|"validates_message"| SchemaRegistry
    Kafka -->|"streams_data"| ksqlDB
    ksqlDB -->|"processed_updates"| Ably
    Ably -->|"real_time_updates"| Client
    TestScripts ---|"simulate_bookings"| FastAPI

    %% Click Events
    click FastAPI "https://github.com/ably-labs/realtime-ticket-booking-solution/blob/main/app.py"
    click Models "https://github.com/ably-labs/realtime-ticket-booking-solution/blob/main/models.py"
    click ksqlDB "https://github.com/ably-labs/realtime-ticket-booking-solution/blob/main/queries/ksqldb-queries.sql"
    click BookingSchema "https://github.com/ably-labs/realtime-ticket-booking-solution/blob/main/schemas/booking-schema.avsc"
    click ConferenceSchema "https://github.com/ably-labs/realtime-ticket-booking-solution/blob/main/schemas/conference-schema.avsc"
    click TestScripts "https://github.com/ably-labs/realtime-ticket-booking-solution/tree/main/test-scripts"

    %% Styles
    classDef api fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef stream fill:#FFCC80,stroke:#FB8C00,stroke-width:2px;
    classDef external fill:#C5E1A5,stroke:#558B2F,stroke-width:2px;
    classDef test fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
```
