Skip to content

PiqueTickets Monorepo Architecture

System Overview

PiqueTickets is a comprehensive event ticketing platform built as a monorepo containing multiple specialized applications that work together to serve different stakeholders in the event ecosystem. The platform enables event producers to create and manage shows, sell tickets to consumers, and check in attendees at events.

Architecture Philosophy

The PiqueTickets monorepo follows a microservices-inspired architecture where:

  • Single Source of Truth: All applications share a single PostgreSQL database managed by the Django API
  • Specialized Frontend Applications: Each user type (consumer, producer, check-in staff) has a dedicated application optimized for their needs
  • API-First Design: The Django REST API serves as the central hub for all business logic and data operations
  • Independent Deployment: Each application can be deployed independently while maintaining data consistency
  • Shared Infrastructure: Common services (database, cache, task queue) are shared across all applications
graph TB
    subgraph "Frontend Applications"
        F[Consumer Frontend<br/>Next.js]
        P[Producer Portal<br/>Next.js]
        C[Check-in App<br/>Vite + React]
    end

    subgraph "API Layer"
        API[Django REST API<br/>Python]
    end

    subgraph "Background Processing"
        CW[Celery Worker]
        CB[Celery Beat]
        CF[Celery Flower]
    end

    subgraph "Infrastructure Services"
        DB[(PostgreSQL<br/>Database)]
        Redis[(Redis<br/>Cache & Queue)]
    end

    subgraph "External Services"
        Stripe[Stripe<br/>Payments]
        SES[AWS SES<br/>Email]
        S3[AWS S3<br/>Storage]
    end

    F --> API
    P --> API
    C --> API

    API --> DB
    API --> Redis
    API --> Stripe
    API --> SES
    API --> S3

    CW --> DB
    CW --> Redis
    CB --> DB
    CB --> Redis
    CF --> Redis

    CW -.monitors.-> CF

Monorepo Structure

piquetickets/
├── apps/
│   ├── api/              # Django REST API backend
│   ├── frontend/         # Consumer-facing Next.js app
│   ├── producer/         # Producer portal Next.js app
│   └── checkin/          # Check-in Vite + React app
├── docs/                 # MkDocs documentation site
├── docker-compose.yml    # Local development orchestration
└── README.md             # Repository overview

Applications & Components

1. API (apps/api) - Django REST Framework

Purpose: Centralized backend providing RESTful APIs, business logic, and admin portal.

Technology Stack: - Python 3.12 - Django 4.0.4 - Django REST Framework - PostgreSQL (database) - Redis (cache & Celery broker) - Celery (async task processing)

Key Django Apps: - tickets - Core ticketing system (shows, tickets, orders) - producers - Producer/organizer management - venue - Venue information and management - performer - Performer/artist profiles - subscriber - Email subscriber management - checkin - Check-in session management - auth - Authentication & authorization - email_tracking - Email delivery tracking (AWS SES) - portal - Producer portal backend logic - knowledge - Knowledge base / help center - components - Reusable Django components - utils - Shared utilities - theme - Django admin theming (Unfold)

Key Features: - RESTful API endpoints for all frontend applications - Django Admin interface for internal operations - Stripe payment integration - AWS SES email tracking and delivery - Celery-based async task processing - Session-based check-in token management - Rich text editing with CKEditor5 - QR code generation for tickets - Image optimization (WebP conversion)

API Endpoints (examples): - /api/v1/shows/ - Show listings and details - /api/v1/tickets/ - Ticket management - /api/v1/orders/ - Order processing - /api/v1/checkout/ - Stripe checkout sessions - /api/v1/checkin/ - Check-in operations - /api/v1/producers/ - Producer management - /admin/ - Django admin portal

Default Port: 8080

2. Frontend (apps/frontend) - Consumer Application

Purpose: Public-facing website where customers discover events and purchase tickets.

Technology Stack: - Next.js 15.3.1 (App Router) - React 19 - TypeScript - TailwindCSS 4.0.9 - Deployed on Cloudflare Pages

Key Features: - Event discovery and browsing - Show detail pages with SEO optimization - Ticket purchasing and checkout - Responsive design for mobile/desktop - Social sharing integration - Structured data for search engines - Facebook Pixel tracking - Next.js Image optimization - ISR (Incremental Static Regeneration)

Pages (examples): - / - Homepage with featured shows - /shows - Show listings - /shows/[slug] - Individual show pages - /checkout - Ticket purchase flow - /order-confirmation - Order success page

Default Port: 3000

3. Producer Portal (apps/producer) - Producer Management

Purpose: Dashboard for event producers to create, manage, and analyze their shows.

Technology Stack: - Next.js 15 (App Router) - React 19 - TypeScript - TailwindCSS v4 - Shadcn UI components - Zustand (state management) - React Hook Form + Zod (form validation) - Tanstack Tables (data tables)

Key Features: - Show creation and management - Ticket type configuration - Promo code management - Sales analytics and reporting - Producer profile management - Venue management - Performer management - Financial dashboard (Stripe integration) - Knowledge base / help center - Feature flags for gradual rollout

Pages (examples): - /dashboard - Overview and analytics - /dashboard/shows - Show management - /dashboard/shows/new - Create new show - /dashboard/tickets - Ticket configuration - /dashboard/analytics - Sales reports - /dashboard/profile - Producer settings

Default Port: 3001

4. Check-in App (apps/checkin) - Event Check-in

Purpose: Lightweight mobile-optimized app for checking in attendees at events.

Technology Stack: - Vite - React - TypeScript - ZXing (QR code scanning) - React Router

Key Features: - QR code scanning via device camera - Real-time ticket validation - Recent scan history - Session token-based authentication - Offline-friendly design - Mobile-optimized UI

Authentication Flow: 1. Producer creates check-in session in portal 2. Unique session token generated 3. Check-in staff access app with token in URL: /?token=SESSION_TOKEN 4. App validates token and loads show information 5. Staff can scan QR codes on tickets to check in attendees

Default Port: 3002 (dev server: 5173)

Infrastructure Services

PostgreSQL Database

Purpose: Primary data store for all applications.

Schema Highlights: - Show-centric design (shows are the central entity) - Normalized relational structure - See Database Schema for detailed ERD diagrams

Key Tables: - tickets_show - Events/performances - tickets_ticket - Ticket types - tickets_order - Customer purchases - tickets_ticketorder - Individual tickets in orders - tickets_ticketattendee - Attendee information - producers_producer - Event organizers - venue_venue - Event locations - performer_performer - Artists/performers - subscriber_subscriber - Email subscribers - checkin_checkinsession - Check-in sessions

Connections: - All applications connect through the Django API - Direct database access only via Django ORM - Managed through Django migrations

Default Port: 5432

Redis

Purpose: Dual role as cache and message broker.

Use Cases: - Cache: Django cache backend for session storage, query results - Celery Broker: Message queue for async tasks - Celery Backend: Task result storage

Default Port: 6379

Celery Worker

Purpose: Asynchronous task processing for background jobs.

Task Types: - Email delivery (welcome emails, order confirmations, password resets) - PDF ticket generation - Image processing and optimization - Scheduled data cleanup - Analytics processing

Configuration: - Concurrency: 4 workers - Max tasks per child: 100 - Prefetch multiplier: 4

Celery Beat

Purpose: Scheduler for periodic tasks (cron-like).

Scheduled Tasks (examples): - Email delivery retries - Session cleanup - Analytics aggregation - Health checks

Scheduler: Django Celery Beat (database-backed)

Celery Flower

Purpose: Real-time monitoring and admin interface for Celery.

Features: - Task monitoring - Worker status - Task history - Performance metrics

Default Port: 5555

Data Flow

Show Creation Flow

sequenceDiagram
    participant Producer as Producer Portal
    participant API as Django API
    participant DB as PostgreSQL
    participant Worker as Celery Worker

    Producer->>API: POST /api/v1/shows/
    API->>DB: Create Show record
    API->>DB: Create related Tickets
    API->>Worker: Queue image optimization
    Worker->>DB: Update image URLs
    API-->>Producer: Return Show data

Ticket Purchase Flow

sequenceDiagram
    participant Customer as Frontend
    participant API as Django API
    participant DB as PostgreSQL
    participant Stripe as Stripe API
    participant Worker as Celery Worker
    participant Email as AWS SES

    Customer->>API: POST /api/v1/checkout/create-session/
    API->>Stripe: Create checkout session
    Stripe-->>API: Return session ID
    API-->>Customer: Redirect to Stripe
    Customer->>Stripe: Complete payment
    Stripe->>API: Webhook: payment_intent.succeeded
    API->>DB: Create Order record
    API->>DB: Create TicketAttendee records
    API->>Worker: Queue confirmation email
    Worker->>Email: Send email via SES
    Worker->>DB: Track email delivery
    API-->>Customer: Redirect to confirmation

Check-in Flow

sequenceDiagram
    participant Staff as Check-in App
    participant API as Django API
    participant DB as PostgreSQL

    Staff->>API: GET /api/v1/checkin/show?token=TOKEN
    API->>DB: Validate session token
    API-->>Staff: Return show details
    Staff->>Staff: Scan QR code
    Staff->>API: POST /api/v1/checkin/ {attendee_uuid}
    API->>DB: Update is_checked_in = True
    API-->>Staff: Return attendee details

Technology Stack Summary

Backend

  • Language: Python 3.12
  • Framework: Django 4.0.4
  • API: Django REST Framework
  • Task Queue: Celery
  • Cache/Broker: Redis
  • Database: PostgreSQL
  • Admin UI: Django Unfold

Frontend Applications

  • Framework: Next.js 15 (Frontend, Producer), Vite (Check-in)
  • UI Library: React 19
  • Language: TypeScript
  • Styling: TailwindCSS 4.0.9
  • UI Components: Shadcn UI (Producer Portal)
  • Forms: React Hook Form + Zod
  • State Management: Zustand (Producer Portal)

Infrastructure

  • Containerization: Docker + Docker Compose
  • Deployment:
  • API: Railway (or custom hosting)
  • Frontend: Cloudflare Pages
  • Database: Managed PostgreSQL
  • Redis: Managed Redis
  • Payment Processing: Stripe
  • Email: AWS SES
  • Storage: AWS S3 (images, files)
  • Monitoring: Celery Flower

Development Tools

  • Linting: ESLint (Frontend), Flake8 (Backend)
  • Formatting: Prettier (Frontend), Black (Backend)
  • Testing: Jest (Frontend), Django Test (Backend)
  • Documentation: MkDocs Material

Deployment Architecture

Local Development

All services run via Docker Compose:

docker-compose up

Services: - db - PostgreSQL database - redis - Redis cache/broker - api - Django API server - celery_worker - Celery worker - celery_beat - Celery scheduler - celery_flower - Celery monitoring

Frontend applications typically run independently:

cd apps/frontend && npm run dev
cd apps/producer && npm run dev
cd apps/checkin && npm run dev

Production Deployment

API & Services: - Deployed to Railway or similar PaaS - Managed PostgreSQL instance - Managed Redis instance - Separate containers for API, worker, beat

Frontend Applications: - Deployed to Cloudflare Pages - Edge caching via Cloudflare CDN - Serverless edge functions

DNS & Routing: - piquetickets.com → Frontend (Cloudflare Pages) - api.piquetickets.com → API (Railway) - docs.piquetickets.com → Documentation (Cloudflare Pages)

Security & Performance

Security Features

  • Django CSRF protection
  • Stripe secure payment processing
  • Session token authentication for check-in
  • CORS configuration for frontend apps
  • Environment variable configuration
  • Django security middleware

Performance Optimizations

  • Redis caching for frequently accessed data
  • Celery async processing for long-running tasks
  • Image optimization (WebP conversion)
  • Database indexing (see Database Schema)
  • Next.js ISR for fast page loads
  • Cloudflare CDN edge caching

Integration Points

External Services

  1. Stripe (Payment Processing)
  2. Checkout session creation
  3. Webhook handling for payment events

  4. Connect platform for producer payouts

  5. AWS SES (Email Delivery)

  6. Transactional emails
  7. Delivery tracking

  8. Bounce/complaint handling

  9. AWS S3 (File Storage)

  10. Event images
  11. Ticket PDFs

  12. Static assets

  13. Facebook (Analytics)

  14. Facebook Pixel tracking
  15. Conversion tracking

Development Workflow

Adding a New Feature

  1. API Changes (apps/api/)
  2. Create/modify Django models
  3. Run migrations: python manage.py makemigrations && python manage.py migrate
  4. Add API endpoints (viewsets, serializers)
  5. Write tests: python manage.py test

  6. Update fixtures if needed

  7. Frontend Changes (apps/frontend/, apps/producer/)

  8. Create/modify React components
  9. Add API client functions
  10. Update types/interfaces
  11. Test locally: npm run dev

  12. Build: npm run build

  13. Documentation (docs/)

  14. Update relevant documentation
  15. Preview: mkdocs serve
  16. Deploy: Automatically via Cloudflare Pages

Testing Strategy

  • API: Django test suite with 80% minimum code coverage
  • Frontend: Build tests in CI/CD
  • E2E: Playwright tests for critical flows (see E2E Testing Strategy)

Monitoring & Observability

  • Celery Tasks: Celery Flower dashboard (http://localhost:5555)
  • API Health: Django Health Check endpoint
  • Database: PostgreSQL monitoring (see Database Monitoring)
  • Logs: Application logs via Railway or hosting platform
  • Error Tracking: (To be implemented)

Future Architecture Considerations

Potential Enhancements

  1. GraphQL API - Consider GraphQL for more flexible frontend data fetching
  2. Event-Driven Architecture - Move to event streaming (Kafka, RabbitMQ) for better scalability
  3. Microservices - Split API into domain-specific services as scale increases
  4. CDN for Images - Dedicated CDN for static assets
  5. Real-time Updates - WebSocket support for live ticket availability
  6. Mobile Apps - Native iOS/Android apps for consumers and producers
  7. Multi-tenancy - Support for white-label solutions

Getting Help

  • Documentation: https://docs.piquetickets.com
  • Repository: https://github.com/Northern-Computing/piquetickets
  • Issues: Submit via GitHub Issues

Last Updated: 2025-01-02