# themusicianone/backend-ticketing architecture

> Architecture diagram of the GitHub repository themusicianone/backend-ticketing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/themusicianone/backend-ticketing
- Repository: https://github.com/themusicianone/backend-ticketing

## Overview

This repository implements a high-concurrency ticketing backend plus a separate fake payment-provider service. The customer purchase path reserves seats in a time-limited hold, starts checkout and records a pending order, then applies payment outcomes to confirm or fail the order; confirmation marks seats sold and creates tickets. Event/venue setup, seat generation, authentication, expiry, webhooks, and payment reconciliation are additional capabilities. Relationships reflect the sampled services and source-index references; unsampled controller and provider internals are represented without asserting unshown call paths.

Main entry points: [`src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java) (Order Lifecycle), [`src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java`](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java) (Seat Holds), [`src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java`](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java) (Checkout Orchestration), [`fake-payment-provider/app/webhooks.py`](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/webhooks.py) (Webhook Delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Event Catalog"]
  node_venue_service["Venue Management"]
  node_event_service["Event Management<br/>[EventService.java]"]
  node_seat_service["Seat Inventory<br/>[SeatService.java]"]
  node_seat_store[("Seat Records")]
end

subgraph group_reservation["Seat Reservation"]
  node_hold_service["Seat Holds<br/>[HoldService.java]"]
  node_hold_store[("Hold Records")]
  node_hold_strategy["Concurrency Strategy"]
  node_hold_expiry["Hold Expiry<br/>[HoldExpiryJob.java]"]
end

subgraph group_commerce["Orders Payments"]
  node_checkout["Checkout Orchestration"]
  node_order_service["Order Lifecycle<br/>[OrderService.java]"]
  node_order_store[("Order Records")]
  node_ticket_store[("Issued Tickets")]
  node_gateway["Payment Gateway"]
  node_payment_outcome["Payment Outcomes"]
  node_webhook_service["Payment Webhooks"]
  node_reconcile["Payment Reconciliation"]
end

subgraph group_identity["Identity"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_users[("User Accounts")]
end

subgraph group_provider["Fake Provider"]
  node_fake_api["Provider API<br/>[main.py]"]
  node_fake_checkout["Provider Checkout<br/>[checkout.py]"]
  node_fake_payments["Provider Payments<br/>[payments.py]"]
  node_fake_store[("Provider Store<br/>[store.py]")]
  node_fake_models["Payment Models<br/>[models.py]"]
  node_fake_webhooks["Webhook Delivery<br/>[webhooks.py]"]
  node_chaos["Chaos Controls<br/>[chaos.py]"]
end

node_customer(("Customer"))
node_admin(("Administrator"))

node_event_service -->|"loads venue"| node_venue_service
node_event_service -.->|"defines event"| node_seat_service
node_seat_service -->|"reads writes"| node_seat_store
node_hold_service -->|"checks seats"| node_seat_store
node_hold_service -->|"saves holds"| node_hold_store
node_hold_service -->|"claims seats"| node_hold_strategy
node_hold_expiry -.->|"expires holds"| node_hold_service
node_checkout -->|"starts payment"| node_gateway
node_checkout -->|"starts checkout"| node_order_service
node_checkout -->|"stores order"| node_order_store
node_order_service -->|"updates hold"| node_hold_store
node_order_service -->|"updates seats"| node_seat_store
node_order_service -->|"updates order"| node_order_store
node_order_service -->|"creates tickets"| node_ticket_store
node_payment_outcome -->|"applies status"| node_order_service
node_reconcile -->|"checks payment"| node_gateway
node_reconcile -->|"applies result"| node_payment_outcome
node_webhook_service -.->|"dispatches status"| node_payment_outcome
node_auth -->|"loads accounts"| node_users
node_fake_api -->|"routes requests"| node_fake_checkout
node_fake_api -->|"routes requests"| node_fake_payments
node_fake_store -->|"stores payments"| node_fake_models
node_fake_webhooks -->|"applies settings"| node_chaos
node_fake_webhooks -->|"builds events"| node_fake_models
node_fake_webhooks -.->|"posts events"| node_webhook_service
node_customer -.->|"authenticates"| node_auth
node_admin -.->|"manages events"| node_event_service
node_customer -.->|"requests hold"| node_hold_service
node_customer -.->|"checks out"| node_checkout

click node_venue_service "https://github.com/themusicianone/backend-ticketing/tree/main/src/main/java/io/github/themusicianone/ticketing_backend/venue"
click node_event_service "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/event/EventService.java"
click node_seat_service "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatService.java"
click node_seat_store "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatRepository.java"
click node_hold_service "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java"
click node_hold_store "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldRepository.java"
click node_hold_strategy "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/SeatHoldStrategy.java"
click node_hold_expiry "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldExpiryJob.java"
click node_checkout "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java"
click node_order_service "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java"
click node_order_store "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/OrderRepository.java"
click node_ticket_store "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/TicketRepository.java"
click node_gateway "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentGateway.java"
click node_payment_outcome "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentOutcomeService.java"
click node_webhook_service "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentWebhookService.java"
click node_reconcile "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentReconciliationService.java"
click node_auth "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/auth/AuthService.java"
click node_users "https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/user/UserRepository.java"
click node_fake_api "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/main.py"
click node_fake_checkout "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/checkout.py"
click node_fake_payments "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/payments.py"
click node_fake_store "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/store.py"
click node_fake_models "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/models.py"
click node_fake_webhooks "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/webhooks.py"
click node_chaos "https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/chaos.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_venue_service,node_event_service,node_seat_service,node_seat_store toneBlue
class node_hold_service,node_hold_store,node_hold_strategy,node_hold_expiry toneAmber
class node_checkout,node_order_service,node_order_store,node_ticket_store,node_gateway,node_payment_outcome,node_webhook_service,node_reconcile toneMint
class node_auth,node_users toneRose
class node_fake_api,node_fake_checkout,node_fake_payments,node_fake_store,node_fake_models,node_fake_webhooks,node_chaos,node_customer,node_admin toneIndigo
```

## Components

### Event Catalog

- [Venue Management](https://github.com/themusicianone/backend-ticketing/tree/main/src/main/java/io/github/themusicianone/ticketing_backend/venue): `src/main/java/io/github/themusicianone/ticketing_backend/venue`
- [Event Management](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/event/EventService.java): `src/main/java/io/github/themusicianone/ticketing_backend/event/EventService.java`
- [Seat Inventory](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatService.java): `src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatService.java`
- [Seat Records](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatRepository.java): `src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatRepository.java`

### Seat Reservation

- [Seat Holds](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java): `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java`
- [Hold Records](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldRepository.java): `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldRepository.java`
- [Concurrency Strategy](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/SeatHoldStrategy.java): `src/main/java/io/github/themusicianone/ticketing_backend/hold/SeatHoldStrategy.java`
- [Hold Expiry](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldExpiryJob.java): `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldExpiryJob.java`

### Orders Payments

- [Checkout Orchestration](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java): `src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java`
- [Order Lifecycle](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java): `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`
- [Order Records](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/OrderRepository.java): `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderRepository.java`
- [Issued Tickets](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/order/TicketRepository.java): `src/main/java/io/github/themusicianone/ticketing_backend/order/TicketRepository.java`
- [Payment Gateway](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentGateway.java): `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentGateway.java`
- [Payment Outcomes](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentOutcomeService.java): `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentOutcomeService.java`
- [Payment Webhooks](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentWebhookService.java): `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentWebhookService.java`
- [Payment Reconciliation](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentReconciliationService.java): `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentReconciliationService.java`

### Identity

- [Authentication](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/auth/AuthService.java): `src/main/java/io/github/themusicianone/ticketing_backend/auth/AuthService.java`
- [User Accounts](https://github.com/themusicianone/backend-ticketing/blob/main/src/main/java/io/github/themusicianone/ticketing_backend/user/UserRepository.java): `src/main/java/io/github/themusicianone/ticketing_backend/user/UserRepository.java`

### Fake Provider

- [Provider API](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/main.py): `fake-payment-provider/app/main.py`
- [Provider Checkout](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/checkout.py): `fake-payment-provider/app/checkout.py`
- [Provider Payments](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/payments.py): `fake-payment-provider/app/payments.py`
- [Provider Store](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/store.py): `fake-payment-provider/app/store.py`
- [Payment Models](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/models.py): `fake-payment-provider/app/models.py`
- [Webhook Delivery](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/webhooks.py): `fake-payment-provider/app/webhooks.py`
- [Chaos Controls](https://github.com/themusicianone/backend-ticketing/blob/main/fake-payment-provider/app/chaos.py): `fake-payment-provider/app/chaos.py`

### Other components

- **Customer**
- **Administrator**

## Connections

- Event Management → Venue Management: loads venue (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/event/EventService.java`)
- Event Management → Seat Inventory: defines event
- Seat Inventory → Seat Records: reads writes (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/seat/SeatService.java`)
- Seat Holds → Seat Records: checks seats (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java`)
- Seat Holds → Hold Records: saves holds (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java`)
- Seat Holds → Concurrency Strategy: claims seats (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/hold/HoldService.java`)
- Hold Expiry → Seat Holds: expires holds
- Checkout Orchestration → Payment Gateway: starts payment (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java`)
- Checkout Orchestration → Order Lifecycle: starts checkout (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java`)
- Checkout Orchestration → Order Records: stores order (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/CheckoutService.java`)
- Order Lifecycle → Hold Records: updates hold (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`)
- Order Lifecycle → Seat Records: updates seats (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`)
- Order Lifecycle → Order Records: updates order (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`)
- Order Lifecycle → Issued Tickets: creates tickets (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/order/OrderService.java`)
- Payment Outcomes → Order Lifecycle: applies status (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentOutcomeService.java`)
- Payment Reconciliation → Payment Gateway: checks payment (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentReconciliationService.java`)
- Payment Reconciliation → Payment Outcomes: applies result (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentReconciliationService.java`)
- Payment Webhooks → Payment Outcomes: dispatches status (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/payment/PaymentWebhookService.java`)
- Authentication → User Accounts: loads accounts (evidence: `src/main/java/io/github/themusicianone/ticketing_backend/auth/AuthService.java`)
- Provider API → Provider Checkout: routes requests (evidence: `fake-payment-provider/app/main.py`)
- Provider API → Provider Payments: routes requests (evidence: `fake-payment-provider/app/main.py`)
- Provider Store → Payment Models: stores payments (evidence: `fake-payment-provider/app/store.py`)
- Webhook Delivery → Chaos Controls: applies settings (evidence: `fake-payment-provider/app/webhooks.py`)
- Webhook Delivery → Payment Models: builds events (evidence: `fake-payment-provider/app/webhooks.py`)
- Webhook Delivery → Payment Webhooks: posts events
- Customer → Authentication: authenticates
- Administrator → Event Management: manages events
- Customer → Seat Holds: requests hold
- Customer → Checkout Orchestration: checks out