### Why this project exists

[Funcode.hu](https://funcode.hu/en) 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