Ping Pong & Tic Tac Toe Gaming Platform

1. What is this app?

This is a full-stack web-based gaming platform that allows users to play Ping Pong and Tic Tac Toe games with real-time multiplayer functionality. The platform includes:

Core Features

• Ping Pong Game: Classic arcade-style ping pong with multiple play modes

  • Remote Multiplayer: Play against opponents across the internet in real-time
  • Local Multiplayer: Two players can play on the same device
  • Tournament Mode: Competitive tournament system for multiple players

• Tic Tac Toe Game: Strategic turn-based game with matchmaking

• Real-Time Chat: Socket.io-based chat system for player communication

• User Authentication System:

  • User registration and login
  • Two-Factor Authentication (2FA) for enhanced security
  • JWT (JSON Web Token) based session management
  • Secure logout functionality

• Matchmaking System: Automated player matching for both Ping Pong and Tic Tac Toe games

Technology Stack

Frontend

• Next.js (React framework with TypeScript)
• TypeScript for type safety
• Tailwind CSS for styling

Backend

• Fastify (high-performance Node.js web framework)
• SQLite database for data persistence
• JWT for authentication
• WebSocket for Ping Pong real-time gameplay
• Socket.io for chat functionality

Monitoring & Observability

• ELK Stack (Elasticsearch, Logstash, Kibana) for centralized logging
• Prometheus for metrics collection
• Grafana for metrics visualization and dashboards

---

2. How does it work?

Application Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │   Next.js Frontend (TypeScript + Tailwind CSS)            │   │
│  │   - Game UI (Ping Pong, Tic Tac Toe)                     │   │
│  │   - Authentication Forms (Login, Signup, 2FA)            │   │
│  │   - Chat Interface                                        │   │
│  │   - Tournament Dashboard                                  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ↓ ↑
                    HTTPS / WebSocket / Socket.io
                              ↓ ↑
┌─────────────────────────────────────────────────────────────────┐
│                         SERVER LAYER                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │   Fastify Backend Server                                  │   │
│  │   ┌──────────────┬──────────────┬──────────────────┐     │   │
│  │   │ REST API     │ WebSocket    │ Socket.io        │     │   │
│  │   │ - Auth       │ - Pong Game  │ - Chat           │     │   │
│  │   │ - Users      │ - Matchmaking│ - Notifications  │     │   │
│  │   │ - Tournaments│ - Game State │                  │     │   │
│  │   └──────────────┴──────────────┴──────────────────┘     │   │
│  └──────────────────────────────────────────────────────────┘   │
│                              ↓ ↑                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │   SQLite Database                                         │   │
│  │   - User accounts & profiles                             │   │
│  │   - Game history & statistics                            │   │
│  │   - Tournament data                                       │   │
│  │   - Chat messages                                         │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ↓ ↑
┌─────────────────────────────────────────────────────────────────┐
│                     MONITORING LAYER                             │
│  ┌─────────────────────┐  ┌──────────────────────────────┐     │
│  │   ELK Stack         │  │   Prometheus + Grafana        │     │
│  │   - Elasticsearch   │  │   - Metrics Collection        │     │
│  │   - Logstash        │  │   - Performance Dashboards    │     │
│  │   - Kibana          │  │   - Alerting                  │     │
│  └─────────────────────┘  └──────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

Application Flow

1. User Authentication Flow

User → Frontend (Login/Signup) → Backend API (JWT Generation)
                                       ↓
                              Verify Credentials (SQLite)
                                       ↓
                              Generate JWT Token + 2FA
                                       ↓
                              Return Token to Frontend
                                       ↓
                              Store Token (Client Side)

2. Ping Pong Game Flow (Remote Multiplayer)

Player 1 → Request Match → Backend Matchmaking System
                                    ↓
                          Find Available Opponent
                                    ↓
Player 2 ← Match Found ←─────────────┘
            ↓
Both Players Connect via WebSocket
            ↓
Game State Synchronized in Real-Time
            ↓
Player Input → Backend → Game Physics → Broadcast to Both Players
            ↓
Game Ends → Save Results to SQLite → Update Player Stats

3. Tic Tac Toe Game Flow

Player → Request Match → Matchmaking → Find Opponent
                              ↓
                    Create Game Session
                              ↓
                    Players Take Turns
                              ↓
            Move Validation → Update Game State
                              ↓
                    Check Win/Draw Condition
                              ↓
                    Game End → Save Results

4. Chat Flow

User → Type Message → Frontend
                         ↓
              Send via Socket.io
                         ↓
              Backend Receives
                         ↓
         Broadcast to Connected Users
                         ↓
         Save to SQLite (History)

5. Tournament Flow

Admin → Create Tournament → Register Players → Generate Brackets
                                                      ↓
                                            Schedule Matches
                                                      ↓
                                            Players Compete
                                                      ↓
                                        Track Results & Rankings
                                                      ↓
                                            Declare Winner

Component Communication

WebSocket (Ping Pong)

• Real-time bidirectional communication
• Low latency for fast-paced gameplay
• Handles paddle movements, ball physics, and score updates

Socket.io (Chat)

• Event-based communication
• Automatic reconnection
• Room-based messaging

REST API

• User authentication endpoints
• Game history and statistics
• Tournament management
• Profile updates

Monitoring & Logging Flow

Application Logs → Logstash → Elasticsearch → Kibana (Visualization)

Application Metrics → Prometheus → Grafana (Dashboards)
                                        ↓
                                   Alerts & Notifications

---

3. How do I run it?

Prerequisites

Ensure you have the following installed:

• Docker and Docker Compose
• Make (for running Makefile commands)
• Node.js (for local development)

Environment Configuration

Backend Environment Variables

Create a .env file in the ./backend directory:

PORT=8080
COOKIE_SECRET="your_cookie_secret"
ACCESS_TOKEN_SECRET="your_access_token_secre"
REFRESH_TOKEN_SECRET="your_refresh_token_secre"
SMTP_FROM="marouanegaming3@gmail.com"
SMTP_PASS="yxvg lhpn lymj kjau"
SMTP_USER="marouanegaming3@gmail.com"
SMTP_PORT="587"
SMTP_HOST="smtp.gmail.com"
IP_ADDRESS="IPADDRESS"

Important:

• Replace your_cookie_secret, your_access_token_secret, and your_refresh_token_secret with strong random strings
• For Gmail SMTP, generate an App Password
• Replace YOUR_SERVER_IP with your actual server IP address

Frontend Environment Variables

Create a .env.local file in the ./frontend/source directory:

NEXT_PUBLIC_BACKEND_URL=https://YOUR_IP:8443
NEXT_PUBLIC_WSS_URL=wss://YOUR_IP:8443/ws

Replace YOUR_IP with your server's IP address.

Running the Application

Option 1: Run Everything (Recommended)

This will start the entire stack including backend, frontend, and monitoring services:

make all

This command will:

1. Create a Docker network (devops-net)
2. Build and start the backend service
3. Build and start the frontend service
4. Start the ELK stack (Elasticsearch, Logstash, Kibana)
5. Start Prometheus and Grafana

Option 2: Run Components Individually

Start Backend Only:

make backend

Start Frontend Only:

make frontend

Start ELK Stack:

make elk

Start Prometheus & Grafana:

make prometheus grafana

Stop All Services

make down

Rebuild and Restart Everything

make re

Accessing the Application

Once running, you can access:

Service	URL	Default Credentials
Frontend	http://localhost:3000	N/A
Backend API	https://YOUR_IP:8443	N/A
Kibana (Logs)	http://localhost:5601	N/A
Grafana (Metrics)	http://localhost:3000	admin / admin
Prometheus	http://localhost:9090	N/A

Monitoring Setup

ELK Stack (Logging)

The ELK stack is automatically configured when you run make elk. It includes:

Elasticsearch

• Stores and indexes application logs
• Accessible at http://localhost:9200

Logstash

• Collects logs from the application
• Processes and forwards to Elasticsearch

Kibana

• Web interface for viewing and analyzing logs
• Access at http://localhost:5601
• Create dashboards to visualize log patterns
• Set up alerts for error conditions

How to use:

1. Navigate to Kibana at http://localhost:5601
2. Go to "Discover" to view real-time logs
3. Create visualizations and dashboards for monitoring
4. Set up alerts for critical errors

Prometheus & Grafana (Metrics)

Prometheus and Grafana are started with make prometheus grafana.

Prometheus

• Scrapes metrics from backend and frontend
• Stores time-series data
• Access at http://localhost:9090

Grafana

• Visualizes metrics in beautiful dashboards
• Access at http://localhost:3000
• Default login: admin / admin

How to use:

1. Access Grafana at http://localhost:3000
2. Log in with default credentials (admin/admin)
3. Add Prometheus as a data source:
   • Go to Configuration → Data Sources
   • Add Prometheus
   • URL: http://prometheus:9090
4. Import or create dashboards to monitor:
   • Active users and game sessions
   • API response times
   • WebSocket connections
   • Database queries
   • System resources (CPU, memory)

Troubleshooting

Docker Network Error: If you see "network exists" warning, this is normal and can be ignored.

Port Conflicts: Ensure ports 3000, 8080, 8443, 5601, 9090 are not in use by other applications.

ELK Stack Permissions: The Makefile automatically sets up permissions for Elasticsearch data directories.

Services Not Starting: Check Docker logs:

docker-compose logs -f

Clean Start: To completely reset and restart:

make down
make all

---

Project Structure

.
├── backend/                    # Fastify backend
│   ├── .env                   # Backend environment variables
│   └── ...
├── frontend/                   # Next.js frontend
│   └── source/
│       ├── .env.local         # Frontend environment variables
│       └── ...
├── elk-stack/                 # ELK configuration
│   └── docker-compose.yaml
├── prometheus-grafana/        # Monitoring configuration
│   └── docker-compose.yml
├── docker-compose.yaml        # Main services
├── Makefile                   # Build and run commands
└── README.md                  # This file

---

Happy Gaming! 🎮🏓