System Documentation

Version: 2.0.0 | Last Updated: January 2026 | Status: Production

Table of Contents

1. System Overview

JGPNR is a comprehensive ticketing and e-commerce platform designed for managing game arena sessions, product sales, and customer relationships. The system provides:

Technology Stack

Component Technology
Backend API Node.js + Express + TypeScript
Database PostgreSQL with Prisma ORM
Cache & Queues Redis + BullMQ
Admin Panel React + TypeScript + TailwindCSS
Customer Frontend React + JavaScript (Vite)
Email Nodemailer with HTML templates
Authentication JWT with refresh tokens
File Storage Local filesystem (uploads/)

Architecture Overview

NGINX
Reverse Proxy & SSL
Customer App
React + JS
Port 4000
Backend API
Node + Express
Port 5000
Admin Panel
React + TypeScript
Port 3000
PostgreSQL
Primary Database
Redis + BullMQ
Cache & Job Queues

Deployment Architecture

Production Environment
NGINX
Reverse Proxy
  • • SSL/TLS termination (Let's Encrypt)
  • • Static file serving
  • • Load balancing
  • • Gzip compression
PM2
Process Manager
  • • Cluster mode (4 instances)
  • • Auto-restart on crash
  • • Zero-downtime reload
  • • Log management
Node.js 18+
Runtime
  • • Express 5 API
  • • TypeScript compiled
  • • ES2022 features
  • • Socket.IO server
PM2 Process List
jgpnr-api
Port 5000 • Cluster x4
jgpnr-admin
Port 4173 • Static serve
jgpnr-worker
BullMQ Jobs
Domain Routing (NGINX)
Domain Upstream Type
jgpnr.com /var/www/jgpnr/my-app/dist Static
api.jgpnr.com localhost:5000 Proxy
admin.jgpnr.com localhost:4173 Proxy
securedocs.jgpnr.com /var/www/jgpnr/docs Static

Background Jobs Architecture

Scheduled Jobs (Cron)
Ticket Expiry 0 0 * * *
Session Reminders 0 * * * *
Expiry Reminders 0 9 * * *
Daily Report 0 8 * * *
Weekly Summary 0 9 * * 1
BullMQ Workers
email-queue Transactional emails
reminders Session notifications
expiry-reminders Expiry warnings
scheduled-reports Analytics reports

2. Core Concepts

Tickets

Tickets are the primary purchasable units for game sessions. Each ticket:

Ticket Categories

Category Description Use Case
SINGLE One-time use ticket Individual game session
GROUP Discounted group tickets Group bookings (4+ people)
SUBSCRIPTION Time-based pass Monthly/Quarterly/Yearly access

Ticket Lifecycle

Purchased
Order Created
Active
Valid Ticket
Scanned
Entry Used
Expired
End State

Ticket Expiry Mechanisms

Important: Tickets can expire through 3 different mechanisms. The expiry job runs daily at midnight (cron: 0 0 * * *).

Mechanism Field Applies To Logic
Date Expiry validUntil All tickets Expires when current date > validUntil
Subscription Expiry subscriptionExpiresAt Subscription tickets Expires when current date > subscriptionExpiresAt
Scan Window Expiry firstScanAt + scanWindow Multi-scan tickets Expires when current date > (firstScanAt + scanWindow days)

Reminder Schedule Processing

Scheduler
Cron Jobs
BullMQ
Queue Job
Worker
Process
Nodemailer
SMTP Send
Delivered
Email Sent

Analytics Note: Expired tickets are automatically excluded from active ticket counts and PlayStation session graphs. Only ACTIVE and PENDING tickets appear in forward-looking analytics.

Orders

Orders encapsulate purchases containing Tickets (for game sessions), Products (from the shop), or both.

Game Sessions

Game sessions occur on specific days with defined schedules:

Timezone: All session times use Africa/Lagos timezone. Subscription tickets calculate next session automatically for Tuesday (day 2) and Friday (day 5).

3. User Roles & Permissions

Authentication Flow

Login
Email + Password
Verify
Check Credentials
Issue JWT
Access + Refresh
Secure Cookie
httpOnly, Secure

Role Definitions

Action SUPER_ADMIN ADMIN STAFF
Create Users ✅ ❌ ❌
Manage Orders ✅ ✅ ❌
Scan Tickets ✅ ✅ ✅

4. Ticket Lifecycle

Purchased
Order Created
Active
Valid Ticket
Scanned
Entry Used
Expired
End State

Ticket Statuses

Status Description
PENDING Payment not yet confirmed
ACTIVE Valid and ready for use
SCANNED Has been used (max scans reached)
EXPIRED Past validity date

5. Order & Product Lifecycle

Order Statuses

Status Description
PENDING Awaiting payment
PROCESSING Paid, preparing fulfillment
COMPLETED Fully fulfilled

6. Shipment Logic

Note: Shipments apply to product orders only. Ticket orders do not generate shipments.

Shipment Statuses

Status Description Actions Available
PROCESSING Payment confirmed, preparing order Add tracking, Mark shipped
SHIPPED Order dispatched with tracking Mark delivered
DELIVERED Customer received order Mark completed
PROCESSING
Preparing order
SHIPPED
In transit
DELIVERED
Complete

7. Inventory Management

The inventory system tracks product stock levels and provides automated low-stock alerts.

Key Features

Product Data Model

Field Type Purpose
stock Integer Current quantity available
lowStockThreshold Integer (default: 5) Triggers low stock notification
trackInventory Boolean Enable/disable stock tracking
sizes JSON Array Size variants with individual pricing

8. Payment System

Checkout
Select Items
Paystack
Payment Gateway
Webhook
/api/webhooks
Order PAID
Status Updated

9. Notification & Reminder Logic

Automated emails sent via Nodemailer and BullMQ. Background jobs process scheduled reminders.

Email Types

Type Trigger Attachments
Order Confirmation Order successfully created None
Payment Receipt Payment confirmed (webhook/manual) PDF Receipt, Ticket QR Codes
Session Reminder 24h and 2h before session None
Expiry Reminder 7 days, 3 days, 1 day before expiry None
Shipping Update Order shipped or delivered None
Marketing Campaign Admin-triggered campaigns Custom (optional)

Reminder Schedule Processing

Scheduler
Cron Jobs
BullMQ
Queue Job
Worker
Process
Nodemailer
SMTP Send

10. Audit Logs & System Health

All significant actions are logged in the AuditLog table for compliance and debugging.

Logged Actions

Category Actions Logged
Authentication Login, Logout, Password Change, Failed Attempts
Orders Created, Payment Confirmed, Cancelled, Refunded
Tickets Scanned, Extended, Cancelled, Settings Changed
Users Created, Role Changed, Disabled, Deleted
Settings System Settings Updated, Email Config Changed

System Health Monitoring

Access Restricted

System health endpoints require SUPER_ADMIN role. Access via: GET /api/v1/health/detailed

11. Known Limitations

12. Glossary

Term Definition
Ticket A scannable entry pass for a game session, with unique QR code
Order A purchase transaction containing tickets and/or products
Subscription A time-based ticket allowing unlimited sessions within validity period
Session A scheduled game period on Tuesdays (18:00-20:30) or Fridays (18:00-21:30)
Scan Validation of a ticket at entry, decrementing remaining uses
Customer End-user who purchases tickets/products (separate from admin users)

13. Request Lifecycle Architecture

Every API request passes through a defined middleware chain before reaching business logic.

Client Request
HTTPS → api.jgpnr.com
NGINX
SSL Termination, Reverse Proxy
Express Middleware Stack
1 Helmet Security headers
2 CORS Origin validation
3 Rate Limiter Redis-backed (100 req/min)
4 Body Parser JSON + URL-encoded
5 Cookie Parser Signed cookies
6 Auth Middleware JWT verification
7 Zod Validation Schema validation
Controller → Service → Prisma
Business logic execution
Email Queue
Audit Log
Notifications
JSON Response
{ success: true, data: {...} }

14. Product Directory Structure

Complete directory layout for all system applications.

Backend API (/var/www/jgpnr/backend/src)

Directory Purpose Key Files
modules/ Feature modules (27 total) orders/, tickets/, email/, payment/, analytics/
jobs/ Background jobs (10 files) reminder.jobs.ts, ticketExpiry.job.ts, scheduler.jobs.ts
middleware/ Express middleware (12 files) auth.ts, validate.ts, rateLimit.ts
config/ Configuration (9 files) database.ts, queue.ts, email.ts
utils/ Utilities (21 files) ticketLifecycle.utils.ts, pdfGenerator.ts

Frontend App (/var/www/jgpnr/my-app/src)

Directory Purpose Key Files
pages/ Route pages (12 files) HomePage.jsx, BookingPage.jsx, ShopPage.jsx
components/ Reusable UI (17 files) PaymentModal.jsx, Header.jsx, SEO.jsx
api/ API client (2 files) axios.js, endpoints.js

Admin Panel (/var/www/jgpnr/admin/src)

Directory Purpose Key Files
pages/ Admin views (55 files) Dashboard/, Orders/, Tickets/, Settings/
components/ Shared components (64 files) Tables, Forms, Modals, Charts
layout/ Page layouts (4 files) AppSidebar.tsx, AppLayout.tsx
context/ React contexts (7 files) AuthContext, NotificationContext, SocketContext
hooks/ Custom hooks (8 files) useAuth, useSocket, useNotifications