How kazakovdmitriy/self-host-planning-poker works
Project Type and Purpose
• This is a full-stack web application designed to offer a self-hostable Planning Poker tool.
• It provides both a rich, responsive front-end (developed in Angular) and a back-end (developed using Flask, Flask-SocketIO, and peewee) that manages game logic and state.
• The application is packaged as a Docker container for easy deployment on a NAS, featuring persistent storage for game settings.
Analyzing the File Structure
• Two major directories represent the core components:
• "angular": Contains the entire front-end source code, modularized by features (e.g., navigation bar, game pages, shared components). It follows Angular’s typical structure with configuration, assets (including internationalization files), and testing files.
• "flask": Contains the back-end code in Python. It includes the main application (app.py), modules for game state management (e.g., game_manager.py, deck.py, models.py), testing modules, and templates. It also incorporates Socket.IO functionalities.
• Other files (like Dockerfile, Crowdin configs, GitHub workflows) indicate integration/debugging, CI/CD pipelines, and deployment configuration.
• Presence of Docker-related files suggests that the entire application (both parts) is assembled into a single self-contained container.
Key Components to Capture
a. Front-End (Angular):
• Angular Application: Represented as a container comprising component-based UI design (navigation-bar, new-game page, ongoing game views, etc.), internationalization assets, and shared services (toast notifications, user info, etc.).
• Socket.IO Client: Indicates real-time communication with the back-end.
b. Back-End (Flask):
• Flask Application: Implements the API endpoints along with game logic using Flask-SocketIO for real-time updates.
• Game State Management: Modules like game_manager.py, deck.py, player.py, and models (in gamestate/ folder) that handle game sessions and logic.
• Persistence Layer: Although no external database server is explicitly referenced, peewee ORM suggests that there is at least an SQLite (or similar) persistence, with game settings volume (“planning-poker-data”) used in Docker deployment.
• Unit Tests: Located under flask/test to ensure back-end reliability.
c. Docker Container:
• A single Docker container is used to encapsulate the entire application, with instructions to persist game settings via a designated volume.
Relationships and Interactions
• That user interactions on the front-end (voting, game state changes) trigger signals/requests to the Flask API.
• The Flask back-end then processes game state changes and, via Socket.IO, sends updates back to the client.
• Persistent storage volume attached to the container (for game configuration data) as an external storage component linked to the flask service.
Architectural Patterns and Design Principles
• Separation of Concerns: The system is split into a dedicated front-end and back-end.
• Real-time Communication: Emphasize the use of Socket.IO for live updates.
• MVC (in a broad sense): Angular’s component-based approach for view management, and the Flask back-end handles business logic.
• Deployment via Docker ensures portability and simplified configuration management (including environment variables like APP_ROOT).
Technologies and Frameworks to Highlight
• Front-End: Angular, Node.js, and Socket.IO client.
• Back-End: Python, Flask, Flask-SocketIO, and peewee ORM.
• Deployment: Docker (Dockerfile, docker-compose setups), with CI/CD integrations via GitHub Actions.