# kazakovdmitriy/self-host-planning-poker architecture

> Architecture diagram of the GitHub repository kazakovdmitriy/self-host-planning-poker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kazakovdmitriy/self-host-planning-poker
- Repository: https://github.com/kazakovdmitriy/self-host-planning-poker

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    User("User"):::external

    %% Docker Container node representing the containerization of the app
    DockerCont("Docker Container"):::container

    %% Front-End Components
    AFE("Angular Front-end"):::frontend
    SIT("Socket.IO Client"):::frontend

    %% Back-End Components
    FBS("Flask Back-end"):::backend
    GSM("Game State Manager"):::backendComp
    Deck("Deck Module"):::backendComp
    Player("Player Module"):::backendComp
    Models("Persistence Layer (Models)"):::backendComp
    Unit("Unit Testing (Flask)"):::test

    %% External Persistent Storage
    PS("Persistent Storage (planning-poker-data)"):::storage

    %% Relationships and Interactions
    User -->|"interacts"| AFE
    DockerCont --> AFE
    DockerCont --> FBS
    AFE -->|"initiates"| SIT
    AFE -->|"REST/WS"| FBS
    FBS -->|"handles state"| GSM
    FBS -->|"handles state"| Deck
    FBS -->|"handles state"| Player
    FBS -->|"persists data"| Models
    FBS -->|"verified by"| Unit
    FBS -->|"pushes updates"| SIT
    FBS -->|"writes to"| PS

    %% Click Events
    click DockerCont "https://github.com/kazakovdmitriy/self-host-planning-poker/tree/main/Dockerfile"
    click AFE "https://github.com/kazakovdmitriy/self-host-planning-poker/tree/main/angular/"
    click SIT "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/angular/src/app/ongoing-game/current-game.service.ts"
    click FBS "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/flask/app.py"
    click GSM "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/flask/gamestate/game_manager.py"
    click Deck "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/flask/gamestate/deck.py"
    click Player "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/flask/gamestate/player.py"
    click Models "https://github.com/kazakovdmitriy/self-host-planning-poker/blob/main/flask/gamestate/models.py"
    click Unit "https://github.com/kazakovdmitriy/self-host-planning-poker/tree/main/flask/test/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef container fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef backendComp fill:#FAD7A0,stroke:#AF601A,stroke-width:2px;
    classDef storage fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef test fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#76448A,stroke-width:2px;
```
