funcode2.0/README.md

Why this project exists

Funcode.hu is a terrible website that handles queuing systems poorly. Their queue implementation is unreliable, crashes frequently, and provides a frustrating user experience during high-traffic events. This project demonstrates how to properly implement a robust, real-time queue system that can handle concurrent users efficiently.

How it works

Core Architecture:

• When an event reaches a concurrency threshold (configurable, default 100 users), the server enables a queue for that event
• Users connect via WebSocket (Socket.IO) for real-time communication
• When queueing is active, users are placed in a FIFO (First In, First Out) queue
• The server grants access (issues a signed JWT token) to up to CONCURRENT_ACTIVE users (default 50) at a time
• JWT tokens are valid for a short period (default 15 minutes). When expired, the server revokes access and grants tokens to the next users in queue
• Users must authenticate with their JWT token to make purchase API calls

Socket.IO Implementation Details:

1. Connection Flow:

   Client connects → Socket.IO handshake → emit 'join_event' → Server adds to queue/grants access
   

2. Event Types:

   • join_event: Client joins an event queue
   • queue_update: Server sends position, wait time, active user count
   • granted: Server grants access with JWT token
   • revoked: Server revokes access (token expired)
   • disconnect: Client leaves, removed from all queues

3. Queue Management:

   • In-memory queue per event ID for fast access
   • MySQL persistence for queue positions and active sessions
   • Automatic queue activation when threshold reached
   • Real-time updates to all connected clients

4. Token Management:

   • JWT tokens signed with server secret
   • Tokens include socket ID and event ID
   • Database tracking of active sessions with expiration times
   • Automatic cleanup of expired tokens

Technical Flow Diagram:

┌─────────────┐    WebSocket     ┌──────────────┐    MySQL     ┌─────────────┐
│   Browser   │ ◄──────────────► │  Socket.IO   │ ◄──────────► │   Database  │
│             │                  │   Server     │              │             │
│ • Queue UI  │                  │ • Queue Mgmt │              │ • Events    │
│ • Token     │                  │ • JWT Issue  │              │ • Tickets   │
│ • Purchase  │                  │ • Real-time  │              │ • Orders    │
└─────────────┘                  └──────────────┘              └─────────────┘
       │                                │
       │         HTTP API               │
       └────────────────────────────────┘
              Purchase Requests

Why it's better than Funcode.hu:

• ✅ Real-time updates vs. page refreshes
• ✅ Persistent queue positions in database vs. memory-only
• ✅ JWT-based authentication vs. unreliable session management
• ✅ Graceful handling of disconnections vs. losing queue position
• ✅ Configurable thresholds vs. hard-coded limits
• ✅ Modern, responsive UI vs. outdated interface
• ✅ Transparent queue position and wait times vs. vague "please wait"

Production Considerations:

• Use Redis for distributed queue state across multiple server instances
• Implement proper user authentication and rate limiting
• Add comprehensive logging and monitoring
• Set up load balancing for Socket.IO with sticky sessions
• Add automated cleanup of stale connections and expired tokens