A distributed event ticket booking platform demonstrating polyglot microservice architecture with event-driven choreography saga.

• What is TicketFlow?
• Architecture Overview
• Booking Saga Flow
• Tech Stack
• Project Structure
• Quick Start
• API Reference Summary
• Environment Variables
• Development Tools
• Kafka Topics
• Why Polyglot?
• Why Kafka over RabbitMQ?
• Contributing
• License

TicketFlow is a production-grade reference implementation of a polyglot microservice platform for selling and managing event tickets. It is designed to demonstrate:

• Polyglot architecture — each service uses the runtime and framework best suited to its workload (Java Spring Boot for transactional services, Python FastAPI for document-centric services, and Bun/Elysia for high-throughput edge logic).
• Event-driven choreography saga — the entire booking lifecycle (seat locking, payment processing, confirmation) is coordinated asynchronously through Apache Kafka with no central orchestrator.
• Database-per-service — every service owns and manages its own datastore; no shared databases, no cross-service SQL joins.
• Production-ready observability — Prometheus metrics, Grafana dashboards, Jaeger distributed tracing, and Loki log aggregation are included out of the box.
• Cloud-native scalability — Kubernetes manifests with KEDA-based autoscaling that reacts to Kafka consumer lag, allowing each service to scale independently under load.

Whether you are exploring microservice design patterns, evaluating polyglot technology choices, or using TicketFlow as a scaffold for a real ticketing product, this repository provides a complete, runnable reference.

graph TB
    subgraph "Client Layer"
        FE["Frontend\nReact + Vite\n:5173"]
    end

    subgraph "API Gateway Layer"
        GW["API Gateway\nBun + Elysia\n:3000"]
    end

    subgraph "Java Services"
        US["User Service\nSpring Boot 3\n:3001"]
        BS["Booking Service\nSpring Boot 3\n:3003"]
    end

    subgraph "Python Services"
        ES["Event Service\nFastAPI\n:3002"]
        PS["Payment Service\nFastAPI\n:3005"]
        NS["Notification Service\nFastAPI\n:3006"]
    end

    subgraph "Bun Services"
        IS["Inventory Service\nElysia\n:3004"]
    end

    subgraph "Message Bus"
        KF["Apache Kafka"]
    end

    subgraph "Databases"
        PG[("PostgreSQL\nUsers / Bookings / Inventory")]
        MG[("MongoDB\nEvents / Payments / Notifications")]
        RD[("Redis\nSeat Locks")]
    end

    FE --> GW
    GW --> US
    GW --> ES
    GW --> BS
    GW --> IS
    GW --> PS
    GW --> NS

    US --> PG
    BS --> PG
    IS --> PG
    IS --> RD
    ES --> MG
    PS --> MG
    NS --> MG

    BS --> KF
    IS --> KF
    PS --> KF
    NS --> KF
    US --> KF
    ES --> KF

    KF --> IS
    KF --> PS
    KF --> NS
    KF --> BS

All client requests enter through the API Gateway (Bun + Elysia), which handles JWT validation, route proxying, and request logging. For reads and simple commands the gateway forwards directly to the target service over HTTP. For the booking lifecycle the gateway accepts the initial request and returns 202 Accepted; the client then polls for the result while the saga progresses asynchronously via Kafka.

The booking lifecycle is the centrepiece of TicketFlow's event-driven design. No service calls another service directly; every step is triggered by a Kafka event.

sequenceDiagram
    participant C as Client
    participant GW as Gateway
    participant BS as Booking Service
    participant KF as Kafka
    participant IS as Inventory Service
    participant PS as Payment Service
    participant NS as Notification Service

    C->>GW: POST /api/bookings
    GW->>BS: Forward request
    BS->>BS: Save booking (PENDING)
    BS->>KF: booking.initiated
    BS-->>C: 202 Accepted {bookingId}

    KF->>IS: booking.initiated
    IS->>IS: Lock seats (Redis SETNX)
    IS->>IS: Update DB (LOCKED)
    IS->>KF: seats.locked

    KF->>BS: seats.locked
    BS->>KF: payment.requested

    KF->>PS: payment.requested
    PS->>PS: Process payment
    PS->>PS: Save to MongoDB
    PS->>KF: payment.processed (SUCCESS)

    KF->>BS: payment.processed
    BS->>BS: Update booking (CONFIRMED)
    BS->>KF: booking.confirmed
    BS->>KF: seats.confirm

    KF->>IS: seats.confirm
    IS->>IS: Update DB (RESERVED)
    IS->>IS: Clear Redis locks

    KF->>NS: booking.confirmed
    NS->>NS: Send confirmation email
    NS->>NS: Save notification log

    C->>GW: GET /api/bookings/{id}
    GW->>BS: Forward request
    BS-->>C: {status: "CONFIRMED"}

If any step fails the saga runs compensating transactions in reverse:

ticketflow/
├── README.md
├── Makefile                        # Developer shortcuts
├── docker-compose.yml              # Full dev stack
├── docker-compose.prod.yml         # Production overrides
├── .env.example                    # Template environment file
│
├── gateway/                        # API Gateway (Bun + Elysia)
│   ├── src/
│   │   ├── index.ts
│   │   ├── routes/
│   │   ├── middleware/
│   │   └── config.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── Dockerfile
│
├── services/
│   ├── user-service/               # Java + Spring Boot 3
│   │   ├── src/main/java/
│   │   ├── src/main/resources/
│   │   ├── pom.xml
│   │   └── Dockerfile
│   │
│   ├── event-service/              # Python + FastAPI
│   │   ├── app/
│   │   │   ├── main.py
│   │   │   ├── routers/
│   │   │   ├── models/
│   │   │   └── kafka/
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   │
│   ├── booking-service/            # Java + Spring Boot 3
│   │   ├── src/main/java/
│   │   ├── src/main/resources/
│   │   ├── pom.xml
│   │   └── Dockerfile
│   │
│   ├── inventory-service/          # Bun + Elysia
│   │   ├── src/
│   │   ├── package.json
│   │   └── Dockerfile
│   │
│   ├── payment-service/            # Python + FastAPI
│   │   ├── app/
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   │
│   └── notification-service/       # Python + FastAPI
│       ├── app/
│       ├── requirements.txt
│       └── Dockerfile
│
├── frontend/                       # React 18 + Vite
│   ├── src/
│   ├── public/
│   ├── package.json
│   ├── vite.config.ts
│   └── Dockerfile
│
├── infra/
│   ├── kafka/
│   │   └── topics.sh               # Topic creation script
│   ├── postgres/
│   │   └── init.sql                # Schema initialisation
│   ├── mongo/
│   │   └── init.js                 # Collection + index setup
│   ├── prometheus/
│   │   └── prometheus.yml
│   ├── grafana/
│   │   └── dashboards/
│   ├── jaeger/
│   └── loki/
│
├── k8s/
│   ├── namespace.yaml
│   ├── secrets/
│   │   └── app-secrets.yaml.example
│   ├── gateway/
│   ├── services/
│   └── keda/
│       └── scaledobjects.yaml
│
├── scripts/
│   ├── seed.sh
│   ├── health-check.sh
│   └── e2e-booking.sh
│
└── docs/
    ├── architecture.md
    ├── development.md
    ├── deployment.md
    ├── event-catalog.md
    ├── api-reference.md
    ├── observability.md
    ├── adr/
    │   ├── 001-polyglot-architecture.md
    │   ├── 002-kafka-over-rabbitmq.md
    │   ├── 003-async-saga-pattern.md
    │   └── 004-database-per-service.md
    └── services/
        ├── gateway.md
        ├── user-service.md
        ├── event-service.md
        ├── booking-service.md
        ├── inventory-service.md
        ├── payment-service.md
        └── notification-service.md

Note: For Docker Compose development you only strictly need Docker + Make. The language runtimes are required only if you want to run individual services outside of containers.

git clone https://github.com/your-org/ticketflow.git
cd ticketflow

# Copy the example environment file and review/edit as needed
make setup

# Starts Kafka, databases, all microservices, and the frontend
make dev

This command:

1. Pulls or builds all Docker images.
2. Starts Zookeeper + Kafka and waits for the broker to be healthy.
3. Creates all Kafka topics via infra/kafka/topics.sh.
4. Starts PostgreSQL, MongoDB, and Redis; runs migrations and index creation.
5. Starts all eight application services.
6. Starts Prometheus, Grafana, Jaeger, Loki, Mailpit, and Redpanda Console.

# Creates sample venues, events, and a test user account
make seed

Credentials for the seeded test user:

• Email: test@ticketflow.dev
• Password: Test1234!

make health

Expected output:

gateway           ✓  http://localhost:3000/health
user-service      ✓  http://localhost:3001/actuator/health
event-service     ✓  http://localhost:3002/health
booking-service   ✓  http://localhost:3003/actuator/health
inventory-service ✓  http://localhost:3004/health
payment-service   ✓  http://localhost:3005/health
notification-service ✓  http://localhost:3006/health
frontend          ✓  http://localhost:5173

# Guided script that registers a user, creates a booking, and polls for confirmation
make e2e

All requests go through the gateway at http://localhost:3000. Protected routes require Authorization: Bearer <token>.

Full request/response schemas and error codes are documented in docs/api-reference.md.

The .env.example file contains all variables. Run make setup to copy it to .env.

Full payload schemas in docs/event-catalog.md.

Each technology was chosen to match the characteristics of its service.

TicketFlow originally used RabbitMQ. The migration to Kafka was driven by:

1. Event log replay — Kafka retains messages for a configurable period. Services can replay missed events from their last committed offset on restart.
2. Consumer groups — Multiple instances of the same service share a consumer group and automatically partition work without additional coordination.
3. KEDA integration — KEDA's Kafka trigger scales pod replicas based on consumer lag.
4. Partition-based ordering — Booking events for the same bookingId are routed to the same partition, guaranteeing ordered processing per booking.
5. Saga auditability — The Kafka topic acts as an immutable audit log of every saga step.

Full rationale in docs/adr/002-kafka-over-rabbitmq.md.

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/your-feature.
3. Make changes, add tests, ensure make test passes.
4. Open a pull request against main.

Code style per language:

• Java: Google Java Style Guide
• Python: Black formatter + isort (make lint)
• TypeScript: ESLint + Prettier (bun run lint)

MIT License. See LICENSE for details.