# cao-trong-khang/ticketbox architecture

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

- Interactive diagram: https://gitdiagram.com/cao-trong-khang/ticketbox
- Repository: https://github.com/cao-trong-khang/ticketbox

## Overview

TicketBox is a concert-ticketing system with a React web app, NestJS API and Android check-in app. The main audience workflow is browse concerts, place an order and pay; organizers manage concerts and ticket types, while staff scan tickets and VIP guests, including offline check-in with later sync. The map also preserves artist-bio generation and VIP imports documented in the README. Edges are limited to sampled calls/references or README-described workflows; unsampled feature links are omitted rather than inferred.

Main entry points: [`backend/src/main.ts`](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/main.ts) (NestJS API), [`frontend/src/app/router.tsx`](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/app/router.tsx) (Web Routes), [`mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt`](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt) (Check-in Repository), [`frontend/src/lib/api-client.ts`](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/lib/api-client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web App"]
  node_webrouter["Web Routes<br/>[router.tsx]"]
  node_concertbrowse["Concert Browsing"]
  node_weborders["Order &amp; Payment UI"]
  node_organizerui["Organizer Console"]
  node_authui["Web Authentication<br/>[session.ts]"]
  node_apiclient["API Client<br/>[api-client.ts]"]
end

subgraph group_backend["Backend API"]
  node_api["NestJS API<br/>[main.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_access["Access Control"]
  node_orders["Order Management"]
  node_payments["Payment Processing"]
  node_checkinapi["Check-in Service"]
end

subgraph group_operations["Concert Operations"]
  node_concerts["Concert Catalog"]
  node_organizer["Concert Management"]
  node_artistbio["AI Artist Bio"]
  node_vipimports["VIP Imports"]
  node_notifications["Notifications"]
end

subgraph group_checkin["Mobile Check-in"]
  node_mobileapp["Staff Check-in UI<br/>[StaffCheckInApp.kt]"]
  node_repository["Check-in Repository"]
  node_localscan["Offline Scan Logic<br/>[ScanValidator.kt]"]
  node_localdb[("Local Check-in Store<br/>[CheckInDatabase.kt]")]
  node_network["Check-in API Client"]
  node_sync["Background Sync"]
end

subgraph group_platform["Shared Platform"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_kafka["Kafka"]
  node_minio[("MinIO")]
end

node_user(("Audience / Staff"))

node_user -->|"uses"| node_webrouter
node_webrouter -->|"routes to"| node_concertbrowse
node_webrouter -->|"routes to"| node_weborders
node_webrouter -->|"routes to"| node_organizerui
node_webrouter -->|"checks session"| node_authui
node_concertbrowse -.->|"requests data"| node_apiclient
node_weborders -.->|"requests checkout"| node_apiclient
node_organizerui -.->|"requests changes"| node_apiclient
node_apiclient -.->|"calls API"| node_api
node_api -.->|"authenticates"| node_auth
node_api -.->|"serves catalog"| node_concerts
node_api -.->|"serves management"| node_organizer
node_api -->|"serves orders"| node_orders
node_orders -.->|"checkout proceeds"| node_payments
node_api -->|"serves payments"| node_payments
node_api -->|"serves bio preview"| node_artistbio
node_api -.->|"serves imports"| node_vipimports
node_api -->|"serves notifications"| node_notifications
node_user -->|"uses"| node_mobileapp
node_mobileapp -.->|"operates check-in"| node_repository
node_repository -->|"validates scans"| node_localscan
node_repository -->|"reads and writes"| node_localdb
node_repository -->|"sends sync"| node_network
node_sync -->|"runs sync"| node_repository
node_network -.->|"calls check-in API"| node_checkinapi
node_api -->|"routes check-in"| node_checkinapi
node_api -->|"guards requests"| node_access
node_api -.->|"persists application data"| node_database
node_api -.->|"uses cache / limits"| node_redis
node_api -.->|"publishes events"| node_kafka
node_api -.->|"stores banners"| node_minio

click node_webrouter "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/app/router.tsx"
click node_concertbrowse "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/concerts/pages/ConcertDetailPage.tsx"
click node_weborders "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/orders/pages/OrderPendingPage.tsx"
click node_organizerui "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/organizer-concerts/pages/OrganizerConcertEditPage.tsx"
click node_authui "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/auth/session.ts"
click node_apiclient "https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/lib/api-client.ts"
click node_api "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/main.ts"
click node_auth "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/auth/auth.service.ts"
click node_access "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/rbac/permissions.guard.ts"
click node_concerts "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/concerts/concerts.service.ts"
click node_organizer "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/concerts/organizer-concerts.service.ts"
click node_orders "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/orders/orders.controller.ts"
click node_payments "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/payments/payments.controller.ts"
click node_artistbio "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/artist-bio/artist-bio-preview.controller.ts"
click node_vipimports "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/vip-imports/vip-imports.controller.ts"
click node_notifications "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/notifications/notifications.controller.ts"
click node_mobileapp "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/ui/navigation/StaffCheckInApp.kt"
click node_repository "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt"
click node_localscan "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/domain/ScanValidator.kt"
click node_localdb "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/local/CheckInDatabase.kt"
click node_network "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/network/CheckInApiClient.kt"
click node_sync "https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/sync/CheckInSyncWorker.kt"
click node_checkinapi "https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/check-in/check-in.service.ts"

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_webrouter,node_concertbrowse,node_weborders,node_organizerui,node_authui,node_apiclient toneBlue
class node_api,node_auth,node_access,node_orders,node_payments,node_checkinapi toneAmber
class node_concerts,node_organizer,node_artistbio,node_vipimports,node_notifications toneMint
class node_mobileapp,node_repository,node_localscan,node_localdb,node_network,node_sync toneRose
class node_database,node_redis,node_kafka,node_minio,node_user toneIndigo
```

## Components

### Web App

- [Web Routes](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/app/router.tsx): `frontend/src/app/router.tsx`
- [Concert Browsing](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/concerts/pages/ConcertDetailPage.tsx): `frontend/src/features/concerts/pages/ConcertDetailPage.tsx`
- [Order & Payment UI](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/orders/pages/OrderPendingPage.tsx): `frontend/src/features/orders/pages/OrderPendingPage.tsx`
- [Organizer Console](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/organizer-concerts/pages/OrganizerConcertEditPage.tsx): `frontend/src/features/organizer-concerts/pages/OrganizerConcertEditPage.tsx`
- [Web Authentication](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/features/auth/session.ts): `frontend/src/features/auth/session.ts`
- [API Client](https://github.com/cao-trong-khang/ticketbox/blob/main/frontend/src/lib/api-client.ts): `frontend/src/lib/api-client.ts`

### Backend API

- [NestJS API](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/main.ts): `backend/src/main.ts`
- [Authentication](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`
- [Access Control](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/rbac/permissions.guard.ts): `backend/src/modules/rbac/permissions.guard.ts`
- [Order Management](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/orders/orders.controller.ts): `backend/src/modules/orders/orders.controller.ts`
- [Payment Processing](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/payments/payments.controller.ts): `backend/src/modules/payments/payments.controller.ts`
- [Check-in Service](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/check-in/check-in.service.ts): `backend/src/modules/check-in/check-in.service.ts`

### Concert Operations

- [Concert Catalog](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/concerts/concerts.service.ts): `backend/src/modules/concerts/concerts.service.ts`
- [Concert Management](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/concerts/organizer-concerts.service.ts): `backend/src/modules/concerts/organizer-concerts.service.ts`
- [AI Artist Bio](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/artist-bio/artist-bio-preview.controller.ts): `backend/src/modules/artist-bio/artist-bio-preview.controller.ts`
- [VIP Imports](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/vip-imports/vip-imports.controller.ts): `backend/src/modules/vip-imports/vip-imports.controller.ts`
- [Notifications](https://github.com/cao-trong-khang/ticketbox/blob/main/backend/src/modules/notifications/notifications.controller.ts): `backend/src/modules/notifications/notifications.controller.ts`

### Mobile Check-in

- [Staff Check-in UI](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/ui/navigation/StaffCheckInApp.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/ui/navigation/StaffCheckInApp.kt`
- [Check-in Repository](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt`
- [Offline Scan Logic](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/domain/ScanValidator.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/domain/ScanValidator.kt`
- [Local Check-in Store](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/local/CheckInDatabase.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/local/CheckInDatabase.kt`
- [Check-in API Client](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/network/CheckInApiClient.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/network/CheckInApiClient.kt`
- [Background Sync](https://github.com/cao-trong-khang/ticketbox/blob/main/mobile-checkin/app/src/main/java/com/ticketbox/checkin/sync/CheckInSyncWorker.kt): `mobile-checkin/app/src/main/java/com/ticketbox/checkin/sync/CheckInSyncWorker.kt`

### Shared Platform

- **PostgreSQL**
- **Redis**
- **Kafka**
- **MinIO**

### Other components

- **Audience / Staff**

## Connections

- Audience / Staff → Web Routes: uses (evidence: `frontend/src/app/router.tsx`)
- Web Routes → Concert Browsing: routes to (evidence: `frontend/src/app/router.tsx`)
- Web Routes → Order & Payment UI: routes to (evidence: `frontend/src/app/router.tsx`)
- Web Routes → Organizer Console: routes to (evidence: `frontend/src/app/router.tsx`)
- Web Routes → Web Authentication: checks session (evidence: `frontend/src/app/router.tsx`)
- Concert Browsing → API Client: requests data
- Order & Payment UI → API Client: requests checkout
- Organizer Console → API Client: requests changes
- API Client → NestJS API: calls API
- NestJS API → Authentication: authenticates
- NestJS API → Concert Catalog: serves catalog
- NestJS API → Concert Management: serves management
- NestJS API → Order Management: serves orders (evidence: `backend/src/modules/orders/orders.controller.ts`)
- Order Management → Payment Processing: checkout proceeds
- NestJS API → Payment Processing: serves payments (evidence: `backend/src/modules/payments/payments.controller.ts`)
- NestJS API → AI Artist Bio: serves bio preview (evidence: `backend/src/modules/artist-bio/artist-bio-preview.controller.ts`)
- NestJS API → VIP Imports: serves imports
- NestJS API → Notifications: serves notifications (evidence: `backend/src/modules/notifications/notifications.controller.ts`)
- Audience / Staff → Staff Check-in UI: uses (evidence: `README.md`)
- Staff Check-in UI → Check-in Repository: operates check-in
- Check-in Repository → Offline Scan Logic: validates scans (evidence: `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt`)
- Check-in Repository → Local Check-in Store: reads and writes (evidence: `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt`)
- Check-in Repository → Check-in API Client: sends sync (evidence: `mobile-checkin/app/src/main/java/com/ticketbox/checkin/data/CheckInRepository.kt`)
- Background Sync → Check-in Repository: runs sync (evidence: `mobile-checkin/app/src/main/java/com/ticketbox/checkin/sync/CheckInSyncWorker.kt`)
- Check-in API Client → Check-in Service: calls check-in API
- NestJS API → Check-in Service: routes check-in
- NestJS API → Access Control: guards requests
- NestJS API → PostgreSQL: persists application data
- NestJS API → Redis: uses cache / limits
- NestJS API → Kafka: publishes events
- NestJS API → MinIO: stores banners