A high-performance, real-time chess ecosystem engineered with a focus on Domain-Driven Design (DDD), Clean Architecture, and Enterprise-Grade Infrastructure.
Operational Status: The core chess engine is 100% operational, strictly adhering to FIDE rules.
Latest Milestone: Successfully completed Phase 11, implementing the LGTM (Loki, Grafana, Tempo, Prometheus) Stack. The system now features real-time performance monitoring, centralized logging, and distributed tracing, providing deep visibility into the system's internal state through OpenTelemetry.
Backend & Infrastructure:
Observability & Monitoring:
Frontend:
This project is architected as a high-cohesion monorepo. Operational processes and architectural decisions are managed through the following modules:
| Module / Document | Purpose & Brief | Location |
|---|---|---|
| ⚙️ Backend | Core Chess Engine, API endpoints & Move validation logic | ./chess-backend |
| 🎨 Frontend | Reactive UI components & Real-time board state management | ./chess-frontend |
| 🏗️ Architecture | High-level design choices (Hexagonal, DDD) & Tech patterns | ./docs/ARCHITECTURE.md |
| 🚀 Setup Guide | Comprehensive local environment & Dependency installation | ./docs/DEVELOPMENT.md |
| 📝 Git Flow | Contribution workflow, Branching strategy & Commit standards | ./.github/GIT_GUIDE.md |
| 📜 Changelog | Daily Evolution, version tracking & project milestones | ./docs/CHANGELOG.md |
| 🛡️ Security | Security policies, safety disclosure & best practices | ./docs/SECURITY.md |
| 🤝 Contributing | Coding standards, PR guidelines & collaboration rules | ./docs/CONTRIBUTING.md |
- The Challenge: Relying on Hibernate's
ddl-auto: updatein a containerized environment is risky. Schema changes must be traceable, reversible, and consistent across all environments. - The Solution: Integrated Liquibase to manage database migrations through versioned SQL changelogs.
- The Result: Professional, auditable database evolution. Guaranteed 1:1 schema parity between local development and Dockerized production environments.
- The Challenge: In Docker Compose, services starting simultaneously can lead to "Connection Refused" errors if the backend tries to connect before the DB or Redis is ready.
- The Solution: Implemented custom Docker Health-Checks and
depends_on: service_healthyconditions. - The Result: The backend initializes only after PostgreSQL and Redis are fully "Healthy," ensuring a resilient, zero-fail deployment flow.
- The Challenge: Validating King safety (check detection) requires executing a move. This poses a risk of corrupting the live game state during the validation process.
- The Solution: Developed a Simulation & Rollback mechanism using Java Records. The engine clones the state, simulates the move on a virtual board, and discards it after safety verification.
- The Result: 100% side-effect-free move validation, ensuring total state integrity.
The core chess logic is encapsulated in a Pure Java domain layer.
- Zero Infrastructure Leakage: Move validation is entirely decoupled from Spring Boot, ensuring 100% unit testability.
- Polymorphic Validation: Each piece (
Rook,Bishop, etc.) encapsulates its own logic, eliminating high-cyclomatic complexity fromswitch-caseblocks.
- FIDE Compliance: Full support for Castling, En Passant, and Pawn Promotion.
- King Safety Simulation: Dry-run execution to detect Check, Checkmate, and Stalemate.
- Efficient Pathfinding: Optimized vector-based collision detection for sliding pieces to maintain high engine throughput.
- Modern React (v19): Utilizing custom hooks and Tailwind CSS for a high-performance, responsive Board UI.
- Lobby & Social: Sophisticated Lobby System and persistent User Statistics against players or the Training Bot.
Current Status: 📈 Phase 12: Quality Assurance & Code Integrity
- ✅ Phase 1: Foundation 🏗️ - Monorepo scaffolding, environment setup, and Spring Boot/React initialization.
- ✅ Phase 2: Domain Modeling ♟️ - Piece-specific logic, board initialization, and DDD-based movement rules.
- ✅ Phase 3: Rule Engine ⚖️ - Legal move validation (King safety, check/mate detection) and FIDE standards.
- ✅ Phase 4: Communication Layer 📡 - WebSocket infrastructure using STOMP protocol and real-time event mapping.
- ✅ Phase 5: UI Integration & Local Play 🖥️ - Interactive React 19 board, Pawn Promotion, and Castling UI.
- ✅ Phase 6: Visual Polish & UX 🎨 - Dark/Light mode, theme support (Classic, Modern, Emerald), and Drag & Drop (
dnd-kit). - ✅ Phase 7: Identity & Persistence 🔐 - Implemented Spring Security + JWT, User profiles, and PostgreSQL integration.
- ✅ Phase 8: Server-Side Authority 🛡️ - Hardened backend validation for all moves and anti-cheat state management.
- ✅ Phase 9: Remote Multiplayer & Matchmaking 🤝 - Global session management and real-time player pairing via WebSockets.
- ✅ Phase 10: Infrastructure & Containerization 🐳 - Orchestrating services with Docker & Docker Compose and implementing Liquibase for DB versioning.
- ✅ Phase 11: Full-Stack Observability (LGTM) 📈 - Implementing Grafana, Loki, and Prometheus for real-time logs, metrics, and system health.
- ⏳ Phase 12: Quality Assurance & Code Integrity 🏆 - Expanding JUnit 5/Mockito coverage and integrating SonarQube for automated "Zero Technical Debt" reporting.
- 📅 Phase 13: Scalability & Resilience ⚡ - Implementing Resilience4j (Circuit Breaker) and Distributed Locking with Redis.
- 📅 Phase 14: Messaging & Async Logic ✉️ - Integration of RabbitMQ/Kafka for background processing, notifications, and analytics.
- 📅 Phase 15: Advanced Analytics & AI 🧠 - Integration of Stockfish via UCI protocol for move analysis and "Hint" system.
The entire application ecosystem is managed using Docker Compose to ensure absolute consistency between development and production environments.
Infrastructure Note: All services (PostgreSQL, Redis, Spring Boot, and React) include health-check protocols to ensure reliable inter-service communication and deterministic container startup sequences.
Batuhan Baysal - Software Engineer Scalable Software Design, Modern Java, and Backend Architectures.
