Skip to content

Architecture

This section provides the technical specifications required for implementing the HNS Ticketing System backend.

Overview

The HNS Ticketing System uses a hybrid modular monolith architecture with selective service extraction:

  • Core Backend: PHP/Symfony monolith handling most business logic
  • Queue Service: Extracted Node.js/Go service for 100k+ WebSocket connections
  • Notification Workers: PHP workers for async email/push delivery
  • Data Layer: PostgreSQL (system of record) + Redis (caching, queues, reservations) + Grafana Loki (audit logs) + Grafana (dashboards)
┌─────────────────────────────────────────────────────────────────────────┐
│                     Mobile App / Admin Portal / Quota Portal            │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Ticketing Backend (Symfony)                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Bounded Contexts: User/Profile, Match/Stadium, Inventory, Orders, │  │
│  │ Tickets, Quotas, Payments, Loyalty, Blacklist, Support, Petrol    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└────────────┬────────────────────────────────────────────┬───────────────┘
             │                                            │
      ┌──────▼──────┐                            ┌────────▼────────┐
      │ Queue Svc   │                            │ Notification    │
      │ (Node/Go)   │                            │ Workers (PHP)   │
      │ WebSocket   │                            │ Email, Push     │
      └──────┬──────┘                            └────────┬────────┘
             │                                            │
             └──────────────────┬─────────────────────────┘
                                │
                    ┌───────────▼───────────────────────────────┐
                    │ PostgreSQL │ Redis │ Loki │ Grafana       │
                    │ (txn data) │(cache)│(audit)│(dashboards)  │
                    └─────────────────────────────────────────┘

Documentation Index

Core Technical Specifications

Document Description Use Case
Architecture Overview High-level system architecture, component responsibilities, integration patterns Understanding the big picture
Microservices Strategy Service boundaries, extraction rationale, communication patterns Understanding deployment decisions
Data Model Complete database schema with all tables, columns, types, constraints, indexes, and relationships Database design and implementation
Audit Logging Infrastructure Grafana Loki audit log architecture, ingestion, retention, dashboards Audit log implementation
API Specification OpenAPI 3.0 specification for all REST endpoints API implementation and integration

Supporting Documentation

Document Description
Architecture-Features Mapping How epics/features map to architectural components
Stadium Design Tool Tech Technical specification for stadium design component

Quick Reference

Technology Stack

Component Technology Purpose
Backend PHP 8.2+ / Symfony 7.x Core business logic
Queue Service Node.js or Go WebSocket connections
Database PostgreSQL 15+ System of record
Cache/Queue Redis 7+ Reservations, sessions, job queue
Payment Stripe Card processing
Email Mailgun Transactional email
Push Firebase FCM Mobile notifications
Accounting e-racuni.com Invoicing/fiscalization
Audit Logs Grafana Loki Centralized audit log aggregation
Audit Dashboards Grafana Audit visualization and alerting

Key Design Decisions

  1. Modular Monolith First: Single deployable with clear module boundaries, extractable later
  2. PostgreSQL Optimistic Locking: FOR UPDATE SKIP LOCKED for concurrent seat allocation
  3. Redis TTL-based Reservations: 20-minute cart hold with automatic release
  4. FIFO Queue with WebSocket: Real-time position updates for 100k+ users
  5. Event-Driven Notifications: Redis pub/sub for cross-service events
  6. Centralized Audit Logging: All audit logs stored in Grafana Loki, keeping PostgreSQL focused on transactional data

API Base URLs

Environment URL
Production https://api.ulaznice.hns.family/api/v1
Staging https://api.staging.ulaznice.hns.family/api/v1

Authentication

All authenticated endpoints require a Bearer token:

Authorization: Bearer <jwt_token>

Tokens are obtained via Drupal SSO integration. See API Specification for details.

For Backend Developers

If you're implementing the backend, start with these documents in order:

  1. Architecture Overview - Understand component responsibilities
  2. Data Model - Set up database schema
  3. API Specification - Implement endpoints
  4. Audit Logging Infrastructure - Configure Loki audit log pipeline

Each endpoint in the API spec references related: - Epic (E1-E15) - Feature files - Business rules

For Frontend Developers

The API Specification provides everything needed for frontend integration:

  • All REST endpoints with request/response schemas
  • Authentication requirements
  • Error response formats
  • WebSocket protocol for queue (see E5 section)

Key Business Rules Summary

Rule Value Reference
Max tickets per purchase 4 E4-F5
Cart reservation timeout 20 minutes E4-F4
Queue purchase window 20 minutes E5-F4
Self-service transfer cutoff 48 hours E9-F5
Loyalty point expiration 5 years E6-F1
OIB validation ISO 7064 MOD 11-10 E1-F5
Home ticket VAT 5% E8-F2
Away ticket VAT 0% E8-F2
Service fee 6% (configurable) E8-F2

Last Updated: February 2026