VTEAM Ticket Management System

The central command center for Vinschool Central Park Student Council events

Features • Tech Stack • Getting Started • Usage

---

📖 Introduction

VTEAM Ticket Management is the comprehensive staff-facing platform for verifying and managing ticket sales for major Vinschool Central Park Student Council events. Designed for high-performance and reliability, this system serves as the operational backbone for events like PROM and the SILENCIO (VTEAM's Halloween event), handling hundreds of real-time transactions and verifications.

The system provides two critical functions for the event team:

1. Staff-Managed Walk-in Sales ("Offline"): A fast, efficient interface for selling tickets on-site.
2. Online Order Verification: A centralized dashboard for coordinators to review and approve payment proofs from student online orders.

📸 Demo/footage of VTEAM Ticket Management System in action

"400 students lined up and this system worked flawlessly."

⚠️ The Challenge: Why this system exists?

High-stakes events with limited timeframes are unforgiving. Without this dedicated infrastructure, the event operations would face critical failure points:

• The "Manual Email" Pain: Manually sending confirmation emails after each sale is slow, error-prone, and distracts staff from the customer.
  • Solution: Automated Instant Delivery triggers a professional confirmation email immediately after every successful purchase, giving students instant peace of mind without staff effort.
• The "Overselling" Nightmare: With separate personel selling simultaneously, tracking real-time availability manually is impossible.
  • Solution: Unified Real-time Inventory (PostgreSQL) acts as the single source of truth, locking concurrency conflicts to prevent selling more tickets than available seats.
• The Efficiency Bottleneck: Manually searching for a student, verifying payment, and entering data takes ~2 minutes per person. For a queue of 400 students, that is unmanageable.
  • Solution: Instant Autocomplete, Optimistic UI and a built in change calculators cuts processing time to <60 seconds per student, preventing riots.

✨ Features

🏦 Walk-in Ticket Sales (Offline Mode)

Designed for speed and accuracy at physical ticket booths:

• Smart Student Autocomplete:
  • Instantly find students by Name, Event ID, Email, or Homeroom.
  • Eliminates manual entry errors and speeds up the queue.
• Direct Sales Processing:
  • Support for Cash and Bank Transfer payments.
  • Customizable ticket types with real-time inventory tracking.
  • Immediate email confirmation.
• Offline Resilience:
  • IndexedDB Caching: Prevent unnecessary API calls and improve performance.
  • Local State Persistence: Never lose a partial order.

📊 Real-Time Analytics

• Live Revenue Tracking: Monitor total funds collected across all channels.
• Staff Performance: Track individual sales and verification counts.
• Visual Charts: Interactive breakdowns of ticket types, sales velocity, and payment methods.

📢 Google Spreadsheet Integration

[!IMPORTANT] > Direct Google Ecosystem Integration Unlike traditional architectures, this system communicates directly with the Google Spreadsheet API to function as a dynamic backend CMS.

• Real-time Synchronization:

  • Student Data: Fetches the latest student list from a central "Master Sheet".
  • Orders: Automatically syncs every offline order to daily sales sheets (e.g., "Offline sales 07-12-2025").
  • Inventory: Pulls ticket types, prices, and inventory limits directly from the spreadsheet configuration.

• Resilient Data Pipeline:

  • Auto-Provisioning: Automatically creates and formats new sheets for each sales day.
  • Hybrid Storage: Persists data to Neon PostgreSQL for reliability while simultaneously mirroring to Google Sheets for operations team accessibility.
  • Smart Formatting: Applies conditional formatting and headers programmatically to new sheets.

🛠️ Tech Stack

Core

• Next.js 16 - App Router & Turbopack.
• TypeScript - Strict type safety.
• React 19 - Latest concurrent features.

Data & State

• Neon PostgreSQL - Serverless database.
• Drizzle ORM - Database access.
• TanStack Query - Async state & caching.
• IndexedDB - Client-side caching for offline support.

UI / UX

• Tailwind CSS 4 - Styling.
• Radix UI - Accessible components.
• Framer Motion - Animations.

🚀 Getting Started

Prerequisites

• Node.js 20+
• Neon PostgreSQL Database
• Google Cloud Console Project (OAuth)
• Google Sheets (for data sync)

Installation

1. Clone the repository:

   git clone https://github.com/vteam/vteam-offline-ticket.git
   cd vteam-offline-ticket

2. Install dependencies:

   npm install

3. Environment Setup: Copy the example env file and configure your credentials.

   cp copy.env .env

   Required: Database URLs, BetterAuth Secret, Google Client ID/Secret, Google Sheets IDs.

4. Run Development Server:

   npm run dev

   Open http://localhost:3000 to view the app.

---

Developed with ❤️ by Cao Cự Chính