Cards Game

⚠️ WARNING - Lab Project Only
This project uses self-signed certificates and includes sensitive environment variables directly in the docker-compose.yaml file. This approach is NOT suitable for production environments. In real-world projects, use trusted Certificate Authorities (CA) and Key Management Systems (KMS) for secrets management. This configuration is permitted only for educational/lab purposes.

Table of Contents

• About
• Architecture
• Project Structure
• Running the Backend
  • Prerequisites
  • Start All Services
  • Verify Services
  • Stop Services and Remove Volumes
• Running Tests
  • Unit Tests (Isolation)
  • Integration Tests
  • Performance Tests
• API Access

About

This is a microservices-based elemental card game system developed as a lab project for the Advanced Software Engineering course in the Master's in Computer Science program at the University of Pisa.

The game allows players to collect and battle with elemental cards (Fire, Water, Earth) in a turn-based combat system. The architecture demonstrates modern software engineering practices including microservices, API gateways, containerization, and distributed systems design.

Architecture

Project Structure

cards-game/
├── services/          # Microservices for game logic, authentication, player management, etc.
├── gateway/           # API Gateway (Nginx) for routing and load balancing
├── docs/              # Documentation including OpenAPI specs, Postman collections, and workflows
└── docker-compose.yaml # Docker Compose configuration for multi-service orchestration

Running the Backend

Prerequisites

• Docker and Docker Compose installed
• Port 80 available

Start All Services

docker-compose up --build

All services will start automatically with self-signed certificates generated on first run.

Verify Services

# Check all services are running
docker-compose ps

# Test gateway health
curl -k https://localhost/health

Note: All microservices are internal and accessible only through the API Gateway at https://localhost. Individual services are not directly exposed.

Stop Services and Remove Volumes

docker-compose down -v

Running Tests

Unit Tests (Isolation)

Unit tests for individual microservices use Postman collections located in docs/postman/:

# Using Newman (Postman CLI)
npm install -g newman

# Auth Service tests
newman run docs/postman/auth/Auth-Service-Gateway.postman_collection.json \
  -e docs/postman/auth/Auth-Service-Gateway.postman_environment.json

# Cards Service tests
newman run docs/postman/cards/Cards-Service-Gateway.postman_collection.json \
  -e docs/postman/cards/Cards-Service-Gateway.postman_environment.json

# Player Service tests
newman run docs/postman/player/Player-Service-Gateway.postman_collection.json \
  -e docs/postman/player/Player-Service-Gateway.postman_environment.json

Or import the individual service collections into Postman Desktop and run them interactively.

Integration Tests

Integration tests validate the complete game workflow using the full game flow collection:

Workflow tested:

1. Create and authenticate 2 users
2. Create a lobby and join it
3. Start the draft process
4. Play a full match
5. Retrieve match history
6. Check leaderboard status

# Run complete workflow integration test
newman run docs/postman/card_game_gameflow_collection.json \
  -e docs/postman/card_game_environment.json

Or import card_game_gameflow_collection.json into Postman Desktop for interactive testing.

Performance Tests

📊 Note: Performance testing with Locust is currently limited due to rate limiting implemented on the API Gateway (to prevent DoS and brute force attacks). For performance test results, see the pre-rate-limiting test run available in docs/performance/.

Performance tests use Locust for load testing:

cd docs/performance

# Install Locust
pip install locust

# Run performance tests (limited by rate limiting)
locust -f locustfile.py --host=https://localhost

# Access Locust web interface at http://localhost:8089

Note: The gateway now implements rate limiting for security. See docs/performance/README.md for detailed performance test results from before rate limiting was enabled.

API Access

All services are accessible through the API Gateway only:

• Gateway Endpoint - https://localhost

Individual microservices are not directly exposed and communicate internally within the Docker network.