Developer Guide

Comprehensive technical documentation for the JGPNR System.

1. Introduction to the System

The JGPNR system is a high-performance, monolithic application designed for managing ticket sales, user sessions, and customer relationships for a gaming/event arena. It follows a rigorous minimalist design philosophy, prioritizing speed, clean code, and zero-downtime reliability.

Core Goals

• Reliability: Robust handling of payments and ticket states.
• Performance: Lightweight frontends using Vite and optimized Backend.
• Maintainability: Strongly typed (TypeScript) codebase with shared conventions.

2. Technology Stack Overview

Frontend (Customer App) Libraries

Admin Panel Libraries

Backend Libraries

Infrastructure

3. Frontend Architecture (Customer App)

Located in /my-app.

Directory Structure

/src
  ├── assets/          # Static assets (images, fonts)
  ├── components/      # Reusable UI components (Buttons, Inputs)
  ├── context/         # React Context (CartContext, AuthContext)
  ├── pages/           # Route components (Home, Checkout, Login)
  ├── hooks/           # Custom React Hooks
  └── utils/           # Helper functions (Currency formatting, dates)

Key Patterns

• Context API: Used for global state like CartContext (managing the shopping cart across pages) and AuthContext.
• GSAP Animations: Used for high-performance, complex animations (Hero sections, interactions).
• Responsive Mobile-First: All components built with Tailwind's mobile-first breakpoints.

4. Admin Panel Architecture

Located in /admin. Designed for data density and quick actions.

UI Philosophy

• Dashboard First: Immediate view of key metrics (Sales, Active Sessions, Ticket Counts).
• Data Tables: High-density tables with filtering, sorting, and pagination for Orders and Customers.
• Forms: Uses react-hook-form with yup validation for robust input handling (e.g., Creating Sessions, Editing Users).

Scanner Module

The Admin panel includes a dedicated Ticket Scanner module (/pages/Scanner/TicketScanner.tsx) that interfaces with the Backend API to validate tickets in real-time. It handles:

• QR Code input/decoding.
• Real-time validation against TicketStatus.
• Preventing double-use or specific day restriction violations.

5. Backend / API Architecture

Located in /backend. The core business logic layer.

Layered Architecture

Key Modules

• Modules/Auth: Handles Login, Registration, Password Reset, and Token Management.
• Modules/Order: Manages Cart checkout, Payment Intent creation, and Order Fulfillment.
• Modules/Ticket: Generates unique ticket codes, handles Validation logic, and transfers.
• Jobs/: Background tasks defined here (Reminder Jobs, Expiry Jobs).

6. Database & Data Modeling

The data model (Prisma Schema) is complex and interconnected.

Key Entities

• User: Admin/Staff users with RBAC (Super Admin, Admin, Staff).
• Customer: End-users purchasing tickets. Tracking total spent, order history.
• Order: Central entity linking Customers to Tickets and Payments.
• Ticket: The core product. Contains ticketCode, status (ACTIVE, SCANNED), and validity dates.
• Campaigns & Subscribers: Email marketing system built directly into the database.

7. Authentication & Authorization

Authentication Flow

Uses JWT (JSON Web Tokens) for stateless authentication.

• Access Token: Short-lived, used for API requests.
• Refresh Token: Secure HTTP-only cookie used to obtain new access tokens.
• Blacklist: BlacklistedToken table prevents usage of compromised or logged-out tokens.

RBAC (Role-Based Access Control)

Middleware allowRoles('SUPER_ADMIN', 'ADMIN') protects sensitive routes.

CSRF Protection

Implemented via csurf with stateless double-submit cookie pattern.

• Middleware: autoCSRFProtection automatically enforces checks on state-changing methods (POST, PUT, DELETE).
• Exemptions: Public endpoints (e.g., Webhooks, Login, Cart) are explicitly whitelisted.
• Cookie: HTTP-Only, Secure, `SameSite=Strict`.

8. Payments & Financial Flows

Integrated Gateways

• Paystack: Primary gateway for Nigerian markets.
• Flutterwave: Secondary/Backup support.

Payment Flow

1. Initiation: User checks out -> Backend creates pending Order -> Returns Gateway URL.
2. Processing: User pays on Gateway.
3. Webhook: Gateway calls /api/webhooks -> Backend verifies signature -> Updates Order to PAID -> Generates Tickets.

9. Notifications System

Architecture

Notifications are decoupled from the request cycle using BullMQ.

• Trigger: Event occurs (e.g. OrderCreated).
• Queue: Metadata added to email-queue in Redis.
• Worker: Separate process picks up job, compiles HTML from /templates, and sends via Nodemailer (SMTP).

10. Analytics & Reporting

Real-Time Aggregation

Analytics are calculated in real-time via AnalyticsService using Prisma Aggregates.

• Dashboard: Fetches consolidated metrics (Revenue, Active Tickets, Scan Success Rate).
• Trends: Revenue grouped by Day/Week/Month.
• Export: Data can be exported to CSV using `json2csv` for:
  • Orders (Financial reconciliation)
  • Tickets (Validity checks)
  • Customers (CRM data)
  • Scans (Security audit)

11. Performance & Security

Performance

• Caching: Redis used to cache heavy Analytics queries (AnalyticsCache model).
• Indexing: Heavy use of @@index on foreign keys and frequently searched fields (email, status, dates) in PostgreSQL.
• Lazy Loading: React routes loaded lazily to reduce initial bundle size.

Security Checklist

• Helmet: HTTP Header security.
• Rate Limiting: express-rate-limit on Auth routes to prevent brute force.
• Input Validation: Yup and Zod used to strictly validate all incoming API payloads.

12. Developer Workflow

Setup & Run

# Backend
cd backend
cp .env.example .env
npm install
npx prisma generate
npm run dev

# Frontend
cd my-app
npm install
npm run dev

# Admin
cd admin
npm install
npm run dev

Testing

Standard testing command in Backend:

npm run test      # Unit tests
npm run test:e2e  # Integration tests

13. Deployment

Build Commands

# Backend
cd backend && npm run build

# Frontend
cd my-app && npm run build

# Admin
cd admin && npm run build

PM2 Configuration

# Start services
pm2 start ecosystem.config.js

# Restart after deploy
pm2 reload all

14. Environment Variables

15. Change-Impact Mapping

Use this guide to identify all files that need modification when changing a feature.

Modifying Ticket Settings

Modifying Email Templates

16. Background Jobs