TicketBox System

TicketBox is an end-to-end concert ticketing platform with an audience web app, an administration console, a NestJS backend/worker, and a Flutter gate scanner.

The implemented workflow covers concert discovery, seat locking, mock payment, ticket and QR issuance, email delivery, online/offline gate scanning, and one-time check-in enforcement.

Projects

Project	Purpose	Documentation
backend-core	NestJS API, Prisma/PostgreSQL, Redis, worker, QR, email, PDF/CSV processing	Backend README
web-client	React audience site for events, seats, checkout, and personal tickets	Client README
web-admin	React administration console for events, artists, imports, tickets, devices, and statistics	Admin README
mobile-gate/mobile_gate	Flutter QR scanner with online and offline check-in	Mobile README
blueprint	System blueprint and implementation documentation	Blueprint README

Prerequisites

Required for the web/backend system:

• Node.js 20 or newer
• npm 10 or newer
• Docker Desktop with Docker Compose
• Git
• A Gemini API key for automatic artist PDF processing
• Optional SMTP credentials for real email delivery

Additional mobile requirements:

• Flutter SDK compatible with Dart ^3.12.1
• Java 17
• Android Studio with Android SDK 36
• Xcode and CocoaPods for iOS builds (macOS only)

Check installed tools:

node --version
npm --version
docker compose version
flutter doctor

Flutter is optional when only running the backend and web applications.

First-Time Backend Setup

From the repository root:

cd backend-core
npm install
docker compose up -d
Copy-Item .env.example .env

Open backend-core/.env and provide:

• JWT_SECRET
• JWT_REFRESH_SECRET
• PAYMENT_WEBHOOK_SECRET
• GEMINI_API_KEY
• The three generated QR_* values

Generate QR signing and encryption values:

npm run keys:generate

Copy the printed values into .env. Use long, different random strings for the JWT and payment secrets. For development without SMTP, use:

NOTIFICATION_PROVIDER=log

Prepare and seed the database:

npm run prisma:generate
npm run prisma:migrate:dev
npm run prisma:seed

The seed is intended for local demonstration data and recreates a populated system with Vietnamese artists, concerts, seating, users, purchases, tickets, check-in history, and dashboard statistics.

Install Web and Mobile Dependencies

Run once for each application you intend to use:

cd web-client
npm install

cd ..\web-admin
npm install

cd ..\mobile-gate\mobile_gate
flutter pub get

Run the Complete System

Use separate terminals from the repository root.

1. API

cd backend-core
npm run start:dev

2. Background worker

cd backend-core
npm run worker

The worker is required for order expiry, email/outbox delivery, VIP CSV imports, Gemini artist PDF processing, reminders, and queue processing.

3. Audience web

cd web-client
npm run dev

Normally available at http://127.0.0.1:5173.

4. Admin web

cd web-admin
npm run dev

Vite normally uses 5174 when the audience app already occupies 5173.

5. Mobile gate (optional)

cd mobile-gate\mobile_gate
flutter devices
flutter run

Android emulators use http://10.0.2.2:3000/api. A physical phone must use http://<computer-LAN-IP>:3000/api and be able to reach port 3000.

Local URLs

Service	URL
Backend API	http://localhost:3000/api
Swagger	http://localhost:3000/docs
Health check	http://localhost:3000/api/health
Audience web	http://127.0.0.1:5173
Admin web	URL printed by Vite, commonly http://localhost:5174
Prisma Studio (optional)	Run npm run db:studio in backend-core

Demo Accounts

All seeded demo accounts use Password123!.

Role	Email
Admin	admin@ticketbox.local
Organizer	organizer@ticketbox.local
Gate staff	staff@ticketbox.local
Audience	audience@demo.local

Main Workflows

Audience ticket purchase

1. Sign in and select a concert.
2. Choose exact VIP/SVIP seats or a standing-ticket quantity.
3. Create the order and temporarily lock inventory.
4. Complete the mock payment.
5. Receive issued QR tickets and optional email delivery.
6. Open Vé của tôi to display the ticket.

Gate check-in

1. Sign in to the Flutter app as staff.
2. Select a concert and download its offline package.
3. Scan the ticket online or offline.
4. Sync queued scans after reconnecting.
5. Already checked-in tickets are rejected on subsequent scans.

Administration

• Manage concerts, ticket types, seating, and check-in devices.
• Automatically create/reuse artists from PDF and link them to events.
• Import VIP guests from CSV.
• Review tickets, sales, check-in data, and dashboard charts.
• Delete only concerts without paid purchases and artists without event links.

Build

Backend:

cd backend-core
npm run build

Web applications:

cd web-client
npm run build

cd ..\web-admin
npm run build

Mobile Android builds:

cd mobile-gate\mobile_gate
flutter build apk --debug
flutter build appbundle --release --dart-define=API_BASE_URL=https://your-api.example.com/api

Production deployment should use HTTPS, production PostgreSQL/Redis, strong secrets, explicit CORS origins, a reverse proxy, and a real Android signing key.

Verification

# Backend
cd backend-core
npm run prisma:validate
npm test
npm run build

# Client web
cd ..\web-client
npm run build

# Admin web
cd ..\web-admin
npm run build

# Mobile
cd ..\mobile-gate\mobile_gate
flutter analyze
flutter test

Troubleshooting

• Backend fails at startup: compare .env with .env.example and fill every required secret.
• Prisma cannot connect: run docker compose ps inside backend-core and wait for PostgreSQL to become healthy.
• PDF or CSV jobs remain pending: start the backend worker.
• Browser reports CORS/network errors: confirm the API base, backend port, and CORS_ORIGIN.
• Android emulator cannot connect to localhost: use 10.0.2.2.
• Physical phone cannot connect: use the computer's LAN IP and check firewall and Wi-Fi client isolation.

For endpoint details, see backend-core/docs/api.md.