Skip to content

System Context

Overview

The HNS Ticketing System operates within a complex ecosystem of external services, legacy systems, and organizational boundaries. This document describes the system context, including external dependencies, integration points, and system boundaries.

System Boundary

What's Inside the System

The HNS Ticketing System encompasses:

  • Admin Portal - Management interface for HNS staff
  • Quota Portal - Self-service interface for quota holders
  • Backend API - Core business logic, data management, and orchestration
  • Database - Primary data store for tickets, users, orders, and configuration
  • Job Scheduler - Automated tasks (cart expiration, quota expiration, notifications)

What's Outside the System

External systems and services that the ticketing system integrates with:

  • HNS Mobile App - Existing mobile application (separate codebase)
  • Payment Gateway (Stripe) - Third-party payment processing
  • Digital Wallet Services - Apple Wallet and Google Pay APIs
  • Email Service Provider - Transactional email delivery
  • Firebase - Push notifications
  • Access Control System - Venue entry validation hardware/software
  • Petrol POS System - Physical sales channel
  • Legacy Ticketing System (Dekod) - System being replaced
  • Bank Payment System - Direct IBAN payments

Context Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         External Actors                          │
├─────────────┬──────────────┬──────────────┬─────────────────────┤
│   Fans &    │    Quota     │   Agency     │   HNS Staff &       │
│   Buyers    │   Holders    │  (Petrol)    │   Support Team      │
└──────┬──────┴──────┬───────┴──────┬───────┴──────┬──────────────┘
       │             │              │              │
       ▼             ▼              ▼              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    HNS Ticketing System                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────────────┐│
│  │   Quota    │  │   Admin    │  │       Backend API          ││
│  │   Portal   │  │   Portal   │  │                            ││
│  └────────────┘  └────────────┘  └────────────────────────────┘│
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐│
│  │                      Database                              ││
│  └────────────────────────────────────────────────────────────┘│
└────────┬──────────┬───────────┬──────────┬───────────┬─────────┘
         │          │           │          │           │
         ▼          ▼           ▼          ▼           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      External Services                           │
├────────────┬────────────┬───────────┬──────────┬────────────────┤
│   Stripe   │   Apple/   │   Email   │  Access  │   HNS Mobile   │
│  Payment   │   Google   │  Service  │ Control  │      App       │
│  Gateway   │   Wallet   │           │  System  │                │
└────────────┴────────────┴───────────┴──────────┴────────────────┘

External Dependencies

Critical Dependencies

These services are essential for core functionality:

1. Payment Gateway (Stripe)

  • Purpose: Process credit card payments and refunds
  • Integration Type: REST API
  • Data Flow:
  • Outbound: Payment requests, refund requests
  • Inbound: Payment confirmations, webhook notifications
  • Criticality: High - Required for card payments (primary payment method)
  • Fallback: Deferred payment option available if Stripe is down
  • Security: PCI-DSS compliant, tokenized payments

2. Email Service Provider

  • Purpose: Send transactional emails (confirmations, tickets, notifications)
  • Integration Type: SMTP or REST API
  • Data Flow: Outbound only (email sending)
  • Criticality: High - Users need ticket confirmations
  • Fallback: Queue emails for retry, display tickets in user account
  • Volume: High during ticket release periods

3. Database

  • Purpose: Persist all system data
  • Type: Relational database (PostgreSQL recommended)
  • Criticality: Critical - System cannot operate without database
  • Backup: Regular backups, point-in-time recovery
  • Performance: Must handle concurrent transactions during peak sales

Important Dependencies

These services significantly enhance functionality:

4. Digital Wallet Services

  • Apple Wallet: iOS digital ticket storage
  • Google Pay: Android digital ticket storage
  • Integration Type: REST APIs with signed passes
  • Data Flow: Outbound (pass creation and updates)
  • Criticality: Medium - Nice to have, users can use QR from email
  • Fallback: Email QR code always available

5. HNS Mobile App

  • Purpose: Primary customer interface for ticket sales, loyalty status, waiting queue management with real-time updates
  • Integration Type: REST API and WebSocket/Firebase for real-time queue updates
  • Data Flow: Bidirectional
  • Outbound: Ticket data, loyalty points, queue positions, progressive notifications
  • Inbound: User authentication, ticket purchases, ticket claims, queue actions
  • Key Features:
  • Real-time queue position updates (30-60 second intervals)
  • Persistent queue banner across all app screens
  • Allows shopping in HNS store while maintaining queue position
  • Progressive push notifications (position updates, near-position alerts, final purchase window)
  • Criticality: High - Exclusive customer sales channel and queue management interface
  • Ownership: Separate team, separate deployment
  • Scalability: Must support 100k+ concurrent users in waiting queue

6. Access Control System

  • Purpose: Validate tickets at venue entry
  • Integration Type: Data export or REST API
  • Data Flow: Outbound (QR codes for sold tickets)
  • Criticality: High - Required for venue entry
  • Timing: Data sent before match day
  • Fallback: Manual entry validation as last resort

Supporting Dependencies

7. Push Notification Service (Firebase)

  • Purpose: Send push notifications for waiting queue (progressive alerts), loyalty sales, match reminders
  • Integration Type: Firebase Cloud Messaging (FCM)
  • Notification Types:
  • Queue Position Updates: Progress notifications when users move significantly in queue
  • Near-Position Alerts: High-priority notifications when queue position approaches front (e.g., #50)
  • Final Purchase Window: Critical notifications when user's turn arrives (10-minute window)
  • Loyalty Sales: Early access notifications for loyalty members
  • Scale: Must support 100k+ concurrent users receiving position updates
  • Performance: < 5 seconds delivery time for critical notifications
  • Criticality: Medium-High - Essential for queue UX, email provides basic alternative
  • Fallback: Email notifications (less real-time)

8. Petrol POS System

  • Purpose: Physical ticket sales at retail locations
  • Integration Type: API (custom interface for Petrol)
  • Data Flow: Bidirectional
  • Outbound: Sector availability, reservation confirmations
  • Inbound: Purchase requests with buyer details
  • Criticality: Medium - Alternative sales channel
  • Volume: Lower than online sales

9. Bank Payment System

  • Purpose: Process direct IBAN payments for deferred payments
  • Integration Type: Manual bank file processing
  • Criticality: Low - Used for special cases
  • Fallback: Manual payment matching

Integration with Legacy System

Dekod Legacy System

The existing ticketing system operated by Dekod must be integrated for data migration:

Migration Requirements

  1. Historical Orders: Import past ticket purchases for records
  2. Loyalty Points: Transfer existing loyalty point balances
  3. User Accounts: Migrate user profiles with OIB linking
  4. Match History: Import which matches users attended
  5. Exclusions: Do NOT migrate:
  6. Tickets without receipts
  7. World Cup and Euro championship data (UEFA-controlled)

Migration Approach

  • Timing: Before production launch (Q3 2026)
  • Method: One-time data export/import
  • Validation: Verify loyalty points accuracy
  • Testing: Pilot with subset of users
  • Cutover: Hard cutover on launch date

Post-Migration

  • Legacy system decommissioned
  • Historical data available read-only in new system
  • No ongoing synchronization required

External Actor Interactions

End Users (Fans)

  • Access Via: HNS mobile app only
  • Authentication: Username/password, OIB verification
  • Key Actions:
  • Browse matches, select zone and quantity to purchase tickets
  • View loyalty points and early access status
  • Join waiting queue for high-demand matches (with real-time position updates)
  • Shop in HNS store while maintaining queue position
  • Receive progressive push notifications as queue position advances
  • System Response: Ticket confirmations with automatically assigned seats, QR codes, email notifications, queue position updates

Quota Holders

  • Access Via: Quota portal (separate from public site)
  • Authentication: Username/password (provided by HNS admin)
  • Key Actions: View allocation, select seats, create sub-quotas, monitor claims
  • System Response: Email notifications, seat confirmations

Agencies (Petrol)

  • Access Via: API integration with their POS system
  • Authentication: API key
  • Key Actions: Check availability, reserve seats, submit purchases
  • System Response: Reservation confirmations, QR codes for buyers

HNS Staff

  • Access Via: Admin portal
  • Authentication: Role-based access control
  • Key Actions: Create quotas, manage matches, handle refunds, run reports
  • System Response: Confirmation of actions, audit logs

Customer Support Team

  • Access Via: Admin portal (support role)
  • Authentication: Role-based access control
  • Key Actions: Search orders, transfer tickets, process refunds, cancel tickets
  • System Response: Action confirmations, customer notifications

Data Flows

Ticket Purchase Flow

  1. User browses available matches (Mobile App → Backend)
  2. User selects zone and quantity (Mobile App → Backend)
  3. System assigns seats using snake algorithm and adds to cart (Backend reserves seats)
  4. User proceeds to checkout (Backend → Stripe for payment)
  5. Payment confirmed (Stripe → Backend via webhook)
  6. Ticket generated (Backend generates QR code)
  7. Confirmation sent (Backend → Email Service → User)
  8. Digital ticket created (Backend → Apple/Google Wallet)
  9. Ticket data sent to access control (Backend → Access Control System)

Quota Allocation Flow

  1. Admin creates quota (Admin Portal → Backend)
  2. Notification sent (Backend → Email Service → Quota Holder)
  3. Quota holder logs in (Quota Portal → Backend)
  4. Seats selected (Backend reserves specific seats)
  5. Sub-quota created (Backend → Email Service → Sub-quota Holder)
  6. Users claim tickets (Mobile App → Backend)
  7. Confirmation sent (Backend → Email Service → Users)

Physical Sales Flow

  1. Customer visits Petrol station
  2. Staff checks availability (Petrol POS → Backend API)
  3. Staff reserves seats (Backend reserves)
  4. Staff collects buyer details (OIB verification)
  5. Purchase confirmed (Petrol POS → Backend API)
  6. QR code generated (Backend)
  7. Email sent to buyer (Backend → Email Service → Buyer)

Security Boundaries

Public Internet Zone

  • Quota portal (HTTPS only)
  • API endpoints for mobile app (HTTPS, API keys)

Internal Network Zone

  • Admin portal (VPN or IP restriction recommended)
  • Database (internal only, no public access)
  • Job schedulers (internal only)

Third-Party Services

  • All external APIs accessed via HTTPS
  • API keys and secrets stored securely (encrypted)
  • Webhook endpoints validated with signatures

Operational Dependencies

Development/Staging

  • Separate environments with mock external services
  • Stripe test mode for payment testing
  • Test email service (e.g., Mailtrap)
  • Isolated database instances

Production

  • Redundant infrastructure for high availability
  • Load balancing for peak traffic
  • CDN for static assets
  • Database replication and backups
  • Monitoring and alerting (uptime, performance, errors)

Support Tools

  • Log aggregation for debugging
  • Error tracking (e.g., Sentry)
  • Performance monitoring (APM)
  • Database query analysis

Constraints and Assumptions

Constraints

  1. OIB Requirement: Croatian law requires OIB for primary buyers
  2. Stripe Availability: Limited to Stripe-supported countries for card payments
  3. Mobile App Dependency: Digital wallet features require HNS mobile app
  4. Peak Load: System must handle 10,000+ concurrent users during high-demand sales
  5. Data Retention: Must retain transaction records for accounting/audit (7 years)

Assumptions

  1. Internet Access: Users have internet access for online purchases
  2. Email Delivery: Email service maintains >99% delivery rate
  3. Mobile Adoption: Majority of users will use mobile devices
  4. Petrol Partnership: Petrol continues as physical sales partner
  5. Legacy Data Quality: Dekod data is accurate enough for migration

Future Integration Possibilities

Potential Future Integrations

  1. Accreditation System: Unified access control for media/VIP
  2. Parking Management: Extend system to handle parking allocations
  3. CRM System: Sync customer data with HNS CRM
  4. Analytics Platform: Stream data to business intelligence tools
  5. Social Media: Share ticket purchases on social platforms
  6. HNL Clubs: Expand to league-wide ticketing platform
  7. International Payment Methods: Additional payment gateways
  8. Hospitality Management: Premium packages and experiences

Last Updated: November 2025