Football Booking Backend System

A comprehensive microservices-based backend system for football field booking, built with NX monorepo, NestJS, and modern infrastructure tools.

🏗️ Architecture

┌─────────────────┐
│   API Gateway   │ (Port 3000)
│  (Keycloak Auth)│
└────────┬────────┘
         │
    ┌────┴────┬──────────┬──────────┬──────────┬──────────┐
    │         │          │          │          │          │
┌───▼───┐ ┌──▼───┐ ┌────▼────┐ ┌───▼────┐ ┌───▼────┐ ┌─────▼─────┐
│ User  │ │Field │ │ Booking │ │Payment │ │Notify │ │  (Future) │
│Service│ │Service│ │ Service │ │Service │ │Service│ │  Services │
│ :3001 │ │ :3002│ │  :3003  │ │ :3004  │ │ :3005 │ │           │
└───┬───┘ └───┬──┘ └────┬────┘ └───┬────┘ └───┬───┘ └───────────┘
    │         │          │          │          │
    └─────────┴──────────┴──────────┴──────────┘
              │
    ┌─────────┴──────────┐
    │   Infrastructure   │
    │  (Docker Compose)   │
    └─────────────────────┘

🛠️ Tech Stack

Core

Monorepo: NX 18.x
Framework: NestJS 10.x
Language: TypeScript 5.x
Package Manager: Yarn

Databases

PostgreSQL 15: 5 instances (user, field, booking, payment, keycloak)
MongoDB 7: Notification logs
Redis 7: Caching and distributed locks

Messaging

Kafka: Event-driven communication
BullMQ: Background job processing

Authentication & Authorization

Keycloak 24: Identity and access management

Observability

OpenTelemetry: Distributed tracing
Signoz: Metrics, traces, and logs
ClickHouse: Time-series data storage

Development Tools

Docker Compose: Local development environment
Swagger/OpenAPI: API documentation
PgAdmin: PostgreSQL management
Mongo Express: MongoDB management
Redis Commander: Redis management
Kafka UI: Kafka topic management

📋 Prerequisites

Node.js: >= 20.x
Yarn: >= 1.22.x
Docker: >= 20.x
Docker Compose: >= 2.x

🚀 Quick Start

1. Clone and Install

# Clone the repository
git clone <repository-url>
cd football-booking-backend-boilerplate

# Install dependencies
yarn install

2. Environment Setup

# Create local dev env file for docker compose
# (This repo uses .env.development for infra scripts)
cp env.development.example .env.development

# Edit .env.development to avoid port conflicts

Windows PowerShell:

Copy-Item env.development.example .env.development

3. Start Infrastructure

# Start all infrastructure services (PostgreSQL, MongoDB, Redis, Kafka, Keycloak, Signoz)
# Recommended (loads .env.development):
yarn dev:infra

# Or run docker compose directly:
docker compose --env-file .env.development -f docker-compose.dev.yml up -d

# Wait for all services to be healthy (check with docker-compose ps)

4. Build Services

# Build all services
yarn nx run-many --target=build --all

# Or build individual service
yarn nx build api-gateway

5. Run Services

# Terminal 1: API Gateway
yarn nx serve api-gateway

# Terminal 2: User Service
yarn nx serve user-service

# Terminal 3: Field Service
yarn nx serve field-service

# Terminal 4: Booking Service
yarn nx serve booking-service

# Terminal 5: Payment Service
yarn nx serve payment-service

# Terminal 6: Notification Service
yarn nx serve notification-service

6. Verify Services

# Check health endpoints
curl http://localhost:3000/health  # API Gateway
curl http://localhost:3001/health  # User Service
curl http://localhost:3002/health  # Field Service
curl http://localhost:3003/health  # Booking Service
curl http://localhost:3004/health  # Payment Service
curl http://localhost:3005/health  # Notification Service

📚 Service Ports

Service	Port	Description
API Gateway	3000	Main entry point
User Service	3001	User management
Field Service	3002	Field management
Booking Service	3003	Booking management
Payment Service	3004	Payment processing
Notification Service	3005	Notifications

🗄️ Database Ports

Database	Port	Service
PostgreSQL (User)	5432	User Service
PostgreSQL (Field)	5433	Field Service
PostgreSQL (Booking)	5434	Booking Service
PostgreSQL (Payment)	5435	Payment Service
PostgreSQL (Keycloak)	5436	Keycloak
MongoDB	27017	Notification Service
Redis	6379	Cache & Locks

Note: host ports are configurable via .env.development (see env.development.example) to avoid conflicts when you run multiple stacks.

🔧 Infrastructure Ports

Service	Port	URL
Keycloak	8090	http://localhost:8090
Signoz Frontend	3301	http://localhost:3301
Kafka UI	8080	http://localhost:8080
PgAdmin	5050	http://localhost:5050
Mongo Express	8081	http://localhost:8081
Redis Commander	8082	http://localhost:8082
Kafka	9092	localhost:9092
Zookeeper	2181	localhost:2181

🔐 Keycloak Setup

Default Credentials

Admin Console: http://localhost:8090
Username: admin
Password: admin123

Default Realm

Realm: football-booking
Clients: api-gateway, frontend-web, mobile-app

Sample Users

Admin: admin / admin123
Field Owner: fieldowner1 / owner123
Customer: customer1 / customer123

📖 API Documentation

Each service exposes Swagger documentation:

API Gateway: http://localhost:3000/api/docs
User Service: http://localhost:3001/api/docs
Field Service: http://localhost:3002/api/docs
Booking Service: http://localhost:3003/api/docs
Payment Service: http://localhost:3004/api/docs
Notification Service: http://localhost:3005/api/docs

📚 Project Documentation

Tài liệu project được tổ chức trong thư mục docs/:

📘 Guides & Quick Start

docs/guides/ - Hướng dẫn bắt đầu, contributing guidelines, code quality standards
Quick Start Guide
Contributing Guidelines
Code Quality Standards

🐛 Troubleshooting

docs/troubleshooting/ - Giải quyết các vấn đề kỹ thuật
Build & Compilation Issues
TypeScript & TypeORM Fixes
Authentication Issues
Linting & Code Quality Fixes

🚀 Implementation

docs/implementation/ - Tóm tắt implementation và các phase
Phase Implementation Summaries
Service-specific Implementation Docs

📋 Requirements

docs/requirements/ - Requirements và specifications
Functional & Non-functional Requirements
API Specifications
Database Schema
System Design

🔧 Scripts

scripts/ - Utility scripts cho development và maintenance
Infrastructure Management (start/stop/reset)
Development Tools
Code Quality Setup

📁 Service Documentation

apps/booking-service/docs/ - Booking Service documentation
apps/payment-service/docs/ - Payment Service documentation
apps/field-service/docs/ - Field Service documentation

Xem docs/README.md để biết thêm chi tiết về cấu trúc documentation.

🏗️ Project Structure

football-booking-backend/
├── apps/                    # Microservices
│   ├── api-gateway/        # API Gateway with Keycloak auth
│   ├── user-service/       # User management
│   ├── field-service/      # Field management
│   │   └── docs/          # Field service documentation
│   ├── booking-service/    # Booking management
│   │   └── docs/          # Booking service documentation
│   ├── payment-service/    # Payment processing
│   │   └── docs/          # Payment service documentation
│   └── notification-service/ # Notifications
├── libs/                    # Shared libraries
│   ├── shared/            # Common DTOs, enums, utils
│   ├── database/          # Database configuration
│   ├── messaging/         # Kafka & BullMQ
│   ├── cache/             # Redis caching
│   └── observability/      # OpenTelemetry & logging
├── docs/                   # Project documentation
│   ├── guides/            # Quick start guides & development guidelines
│   ├── troubleshooting/   # Troubleshooting & bug fixes
│   ├── implementation/    # Implementation summaries & phase docs
│   ├── requirements/      # Requirements & specifications
│   └── *.md               # Main documentation files
├── scripts/                # Utility scripts
│   ├── *.sh               # Shell scripts (infra, setup, etc.)
│   └── *.js               # Node.js utility scripts
├── config/                 # Configuration files
│   ├── keycloak/          # Keycloak realm config
│   └── signoz/            # Signoz config
├── docker-compose.yml      # Production compose
├── docker-compose.dev.yml  # Development compose
└── README.md

🧪 Testing

# Run all tests
yarn nx run-many --target=test --all

# Run tests for specific service
yarn nx test user-service

# Run with coverage
yarn nx test user-service --coverage

🧹 Linting & Formatting

# Lint all projects
yarn nx run-many --target=lint --all

# Format code
yarn format

# Check formatting
yarn format:check

🐳 Docker

Build Individual Service

# Build service image
docker build -f apps/api-gateway/Dockerfile -t api-gateway:latest .

Run with Docker Compose

# Development
docker-compose -f docker-compose.dev.yml up -d

# Production
docker-compose up -d

# Stop services
docker-compose -f docker-compose.dev.yml down

# View logs
docker-compose -f docker-compose.dev.yml logs -f api-gateway

📊 Observability

Signoz Dashboard

URL: http://localhost:3301
Features: Traces, Metrics, Logs

OpenTelemetry

All services are instrumented with OpenTelemetry. Traces are automatically sent to Signoz collector.

🔄 Development Workflow

Start Infrastructure: docker-compose -f docker-compose.dev.yml up -d
Install Dependencies: yarn install
Build Services: yarn nx run-many --target=build --all
Run Services: yarn nx serve <service-name>
Make Changes: Edit code in apps/<service-name>/src
Test: yarn nx test <service-name>
Lint: yarn nx lint <service-name>

🐛 Troubleshooting

Port Already in Use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

Docker Services Not Starting

# Check logs
docker-compose -f docker-compose.dev.yml logs

# Restart services
docker-compose -f docker-compose.dev.yml restart

Database Connection Issues

Verify database is running: docker-compose -f docker-compose.dev.yml ps
Check connection string in .env
Verify database credentials

Keycloak Not Accessible

Wait for Keycloak to fully start (may take 1-2 minutes)
Check logs: docker-compose -f docker-compose.dev.yml logs keycloak
Verify port 8090 is not in use

📝 Environment Variables

Key environment variables (see .env.example for full list):

Service Ports: API_GATEWAY_PORT, USER_SERVICE_PORT, etc.
Database: DB_USER_HOST, DB_USER_PORT, etc.
Keycloak: KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID
Kafka: KAFKA_BROKERS
Redis: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
OpenTelemetry: OTEL_EXPORTER_OTLP_ENDPOINT

🚧 TODO / Future Enhancements

[ ] Complete business logic implementation
[ ] Add comprehensive test coverage
[ ] Implement Kafka event consumers
[ ] Add BullMQ job processors
[ ] Implement email templates
[ ] Add payment gateway integrations (Stripe, VNPay)
[ ] Add SMS notification support
[ ] Implement distributed locking for bookings
[ ] Add rate limiting
[ ] Implement saga pattern for distributed transactions
[ ] Add CI/CD pipeline
[ ] Kubernetes deployment manifests

📄 License

MIT

👥 Contributing

Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

📞 Support

For issues and questions, please open an issue in the repository.

Note: This is a skeleton/structure setup. Business logic implementation is pending and should be added according to specific requirements.