SquidPong Backend 🏓

A microservices-based backend system for the SquidPong application, built with Node.js, TypeScript, and Fastify.

📋 Table of Contents

• Architecture
• Services
• Prerequisites
• Quick Start
• Development
• API Documentation
• Database
• Message Queue & Caching
• File Uploads
• Environment Variables
• Docker
• Contributing

🏗️ Architecture

SquidPong Backend follows a microservices architecture with the following components:

┌─────────────────┐    ┌─────────────┐
│     Frontend    │────│    Caddy    │
│   (React/Vue)   │    │ (Reverse    │
└─────────────────┘    │   Proxy)    │
                       └─────────────┘
                              │
                       ┌─────────────┐
                       │   Gateway   │
                       │  (Fastify)  │
                       └─────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   ┌─────────┐         ┌─────────────┐       ┌─────────────┐
   │   Auth  │         │    User     │       │    Chat     │
   │Service  │         │   Service   │       │   Service   │
   └─────────┘         └─────────────┘       └─────────────┘
        │                     │                     │
   ┌─────────┐         ┌─────────────┐       ┌─────────────┐
   │Tournament│        │   Notify    │       │    Game     │
   │Service  │         │   Service   │       │   Service   │
   └─────────┘         └─────────────┘       └─────────────┘
        │                     │                     │
   ┌─────────────────────────────────────────────────────┐
   │                  Shared Services                    │
   │  ┌─────────┐  ┌─────────┐  ┌─────────────────────┐ │
   │  │  Redis  │  │RabbitMQ │  │     SQLite DBs      │ │
   │  │(Cache)  │  │ (Queue) │  │(Auth/User/Chat/etc) │ │
   │  └─────────┘  └─────────┘  └─────────────────────┘ │
   └─────────────────────────────────────────────────────┘

🚀 Services

Gateway Service

• Port: 4000
• Role: API Gateway, routing, authentication, and request proxying
• Tech Stack: Fastify, TypeScript
• Features:
  • Request routing to microservices
  • Authentication middleware
  • WebSocket support
  • CORS handling

Auth Service

• Port: 5001 (Prisma Studio)
• Role: User authentication and authorization
• Features:
  • JWT token management
  • OAuth2 integration
  • 2FA support (TOTP)
  • Session management

User Service

• Port: 5002 (Prisma Studio)
• Role: User profile and account management
• Features:
  • User profile CRUD operations
  • Avatar uploads
  • User preferences

Chat Service

• Port: 5004 (Prisma Studio)
• Role: Real-time messaging
• Features:
  • Direct messaging
  • Group chat
  • File sharing
  • Message history

Notification Service

• Port: 5003 (Prisma Studio)
• Role: Push notifications and alerts
• Features:
  • Real-time notifications
  • Email notifications
  • Push notifications

Tournament Service

• Role: Tournament and competition management
• Features:
  • Tournament creation and management
  • Bracket generation
  • Scoring system

Game Service

• Port: 3000 (Game Server), 5005 (Prisma Studio)
• Role: Real-time game logic and state management
• Tech Stack: Colyseus (Real-time multiplayer framework)
• Features:
  • Game room management
  • Real-time game state synchronization
  • Player matchmaking

📋 Prerequisites

• Docker (v20.10+)
• Docker Compose (v2.0+)
• Make (usually pre-installed on Linux/macOS)

That's it! 🎉 No need to install Node.js, npm, databases, or any other dependencies - everything runs in Docker containers.

Note: Node.js (v18+) and npm are only needed if you want to develop outside of Docker containers.

🚀 Quick Start

1. Clone the repository

   git clone https://github.com/TRAN5PONG/SquidPong-Backend.git
   cd SquidPong-Backend

2. Set up environment variables (optional - services work with defaults)

   # Copy example env files if you need custom configuration
   cp backend/gateway/.env.example backend/gateway/.env
   cp backend/services/auth/.env.example backend/services/auth/.env
   # ... other services if needed

3. Start everything with one command ⚡

   make up

   That's it! This single command will:

   • Build all Docker images
   • Start all microservices
   • Initialize databases with migrations
   • Set up Redis and RabbitMQ
   • Configure the Gateway and Caddy proxy

4. Access the application

   • Frontend: http://localhost:8080
   • API Gateway: http://localhost:4000
   • Prisma Studio (Auth): http://localhost:5001
   • Prisma Studio (User): http://localhost:5002
   • Prisma Studio (Chat): http://localhost:5004
   • Prisma Studio (Notify): http://localhost:5003

🎯 Essential Make Commands

make up      # 🚀 Start everything (the only command you usually need!)
make down    # 🛑 Stop all services  
make fclean  # 🧹 Complete cleanup (removes all data)
make re      # 🔄 Full restart (clean + start)

💻 Development

Quick Development Start

For most developers, you only need:

# Clone and start everything
git clone https://github.com/TRAN5PONG/SquidPong-Backend.git
cd SquidPong-Backend
make up

That's it! The Makefile handles everything automatically:

• 🏗️ Building all Docker images
• 🗄️ Database migrations for all services
• 🚀 Starting all microservices
• 🔧 Setting up Redis and RabbitMQ
• 🌐 Configuring reverse proxy

Advanced Development (Optional)

Only needed if you want to develop outside Docker or debug individual services:

1. Install dependencies (for each service)

   cd backend/gateway && npm install
   cd ../services/auth && npm install
   cd ../user && npm install
   cd ../chat && npm install
   cd ../notify && npm install
   cd ../tournament && npm install
   cd ../game && npm install

2. Run database migrations (only if developing locally)

   # Each service with Prisma needs its own migration
   cd backend/services/auth && npx prisma migrate dev --name init
   cd ../user && npx prisma migrate dev --name init  
   cd ../chat && npx prisma migrate dev --name init
   cd ../notify && npx prisma migrate dev --name init
   cd ../tournament && npx prisma migrate dev --name init
   cd ../game && npx prisma migrate dev --name init

3. Start services individually (for debugging)

   # Gateway
   cd backend/gateway && npm run dev
   
   # Auth Service
   cd backend/services/auth && npm run dev
   
   # Other services...

Available Make Commands

💡 TL;DR: Just use make up to start everything!

make up      # 🚀 Start everything (builds images, runs migrations, starts all services)
make down    # 🛑 Stop all services gracefully
make fclean  # 🧹 Complete cleanup (⚠️ deletes all data)
make re      # 🔄 Full restart (fclean + up)

Detailed Command Breakdown:

• make up - The main command you'll use ⭐

  • Automatically builds all Docker images
  • Starts Redis, RabbitMQ, and all databases
  • Runs Prisma migrations for each service
  • Launches all microservices with hot reload
  • Sets up Caddy reverse proxy
  • No manual setup required!

• make down - Clean shutdown

  • Stops all running containers
  • Removes created Docker images to free space
  • Keeps database data intact

• make fclean - Nuclear option (use carefully)

  • Stops all containers
  • Removes all volumes ⚠️ deletes all SQLite databases
  • Removes all images
  • Use when you want a completely fresh start

• make re - Complete reset

  • Equivalent to make fclean && make up
  • Fresh installation from scratch

📖 API Documentation

API documentation is available via Swagger UI:

• Auth Service: http://localhost:4000/api/auth/docs
• User Service: http://localhost:4000/api/user/docs
• Chat Service: http://localhost:4000/api/chat/docs
• Other services follow the same pattern

🗄️ Database

Each microservice maintains its own SQLite database with Prisma ORM for data isolation and service independence:

Service-Specific Databases

• Auth Service: backend/services/auth/prisma/auth.db - User authentication, tokens, sessions
• User Service: backend/services/user/prisma/user.db - User profiles, preferences, avatars
• Chat Service: backend/services/chat/prisma/chat.db - Messages, conversations, chat groups
• Notification Service: backend/services/notify/prisma/notify.db - Notifications, alerts, push settings
• Tournament Service: backend/services/tournament/prisma/tournament.db - Tournament data, brackets
• Game Service: backend/services/game/prisma/game.db - Game states, matches, scores

Database Management

Each service manages its own database independently:

# Navigate to specific service directory
cd backend/services/[service-name]

# Generate Prisma client for the service
npx prisma generate

# Run migrations for the service
npx prisma migrate dev

# Access Prisma Studio for the service (runs on service-specific port)
npx prisma studio

Service-specific Prisma Studio ports:

• Auth: http://localhost:5001
• User: http://localhost:5002
• Notify: http://localhost:5003
• Chat: http://localhost:5004
• Game: http://localhost:5005

📨 Message Queue & Caching

Redis

• Usage: Caching, session storage, real-time data
• Container: redis
• Image: redis/redis-stack-server:latest

RabbitMQ

• Usage: Asynchronous message processing between services
• Container: rabbitmq
• Image: rabbitmq:latest

📁 File Uploads

File uploads are organized in the uploads/ directory:

uploads/
├── user/
│   └── avatar/          # User avatars
│       ├── default.png
│       └── [user-files]
└── chat/
    └── group/           # Group chat files
        ├── default.png
        └── [group-files]

⚙️ Environment Variables

Create .env files for each service with the following variables:

Gateway Service

PORT=4000
JWT_SECRET=your-jwt-secret
REDIS_URL=redis://redis:6379
RABBITMQ_URL=amqp://rabbitmq:5672

Auth Service

PORT=3000
DATABASE_URL="file:./auth.db"
JWT_SECRET=your-jwt-secret
OAUTH_CLIENT_ID=your-oauth-client-id
OAUTH_CLIENT_SECRET=your-oauth-client-secret

Other Services

Similar pattern with service-specific configurations.

🐳 Docker

Simple Usage (Recommended)

make up    # Start everything
make down  # Stop everything  

Direct Docker Commands (Advanced)

If you prefer using Docker directly instead of Make:

# Development
docker compose up --build

# Production
docker compose -f docker-compose.prod.yml up --build

Why use Make instead?

• ✅ Shorter commands (make up vs docker compose up --build)
• ✅ Consistent across different environments
• ✅ Built-in cleanup and restart options
• ✅ Handles complex Docker operations automatically

🛠️ Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript
• Web Framework: Fastify
• Database: SQLite with Prisma ORM
• Cache: Redis
• Message Queue: RabbitMQ
• Authentication: JWT, OAuth2, TOTP (2FA)
• Real-time: WebSockets, Colyseus (for games)
• Reverse Proxy: Caddy
• Containerization: Docker & Docker Compose

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the ISC License.

🔧 Troubleshooting

Common Issues

1. Port conflicts: Make sure ports 8080, 4000, 5001-5005 are available
2. Database migrations: Each service has its own SQLite database - run migrations individually:

   cd backend/services/[service-name] && npx prisma migrate dev --name init

3. Permission issues: Ensure Docker has proper permissions for volume mounts and SQLite files
4. Service startup order: Services wait 6 seconds before starting to ensure dependencies are ready
5. Database reset: Use make fclean carefully - it will delete all SQLite database files
6. Individual service debugging: Check specific service logs:

   docker compose logs -f [service-name]

Logs

View service logs:

docker compose logs -f [service-name]
# Example: docker compose logs -f gateway

📧 Support

For support, please open an issue on the GitHub repository or contact the development team.