# parisasokuti/ds_project architecture

> Architecture diagram of the GitHub repository parisasokuti/ds_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parisasokuti/ds_project
- Repository: https://github.com/parisasokuti/ds_project

## Overview

##### Project Type and Purpose
- This is a **backend-centric**, **distributed**, **real-time WebSocket game server** with dual persistence (Redis + PostgreSQL), built in Python asyncio.
- Primary goals: horizontal scaling, fault tolerance (circuit breakers, auto-failover), session persistence, and enterprise monitoring.

##### File Structure for Architectural Clues
- **backend/** – core server code: WebSocket handling, game logic, auth, data layer, fault-tolerance modules.
- **docker-compose.yml / k8s-deployment.yml** – container orchestration, multi-instance scaling.
- **scripts/** – deployment, backup, failover automation.
- **examples_archive/** & **docs/** – sample infra (PostgreSQL HA, Redis clusters), monitoring configs, load-balancer examples.
- **tests/** – comprehensive coverage indicating key integration points (DB, Redis, network, auth, fault-tolerance).

##### README for Additional Insights
- Main components called out: **Backend Server**, **Database Layer**, **Authentication**, **Load Balancing**, **Monitoring**.
- Tech stack: Python asyncio, Redis, PostgreSQL, JWT, HAProxy, Docker Compose, Kubernetes.

##### Main Components and Their Relationships
a. **Clients**
- Web or CLI clients (e.g. `backend/client.py`) connect via **WebSocket**.
- Could be browser JS front-ends or custom Python clients.
b. **Load Balancer**
- HAProxy (configured for WebSocket sticky sessions).
- Sits in front of multiple game-server instances.
c. **Game Server Instances** (`backend/server.py`)
- Stateless WebSocket handlers that implement game logic (`game_board.py`, `game_states.py`).
- Fault-tolerance modules: `circuit_breaker.py`, `auto_scaler.py`, `circuit_breaker_monitor.py`.
- Authentication routes (`auth_routes.py`, `auth_service.py`).
d. **Data Layer**
- **Redis Cluster**: real-time game state and session storage
- Managers & integrations: `redis_manager.py`, `redis_cluster_manager.py`, `hybrid_data_layer.py`.
- **PostgreSQL**: persistent storage of users, game history
- Handled via SQLAlchemy wrappers (`backend/database/*.py`, `postgresql_persistence.py`).
- **Circuit Breaker Integration** around both Redis and PostgreSQL (see `backend/database/circuit_breaker_integration.py`).
e. **Monitoring & Health**
- HTTP `/health` endpoint in server.
- Prometheus exporters (in `examples_archive`), Grafana dashboards.
- Health checks & backup monitors (`scripts/backup_health_monitor.sh`, `backend/circuit_breaker_monitor.py`).
f. **Infrastructure & Orchestration**
- Docker Compose (`docker-compose.yml`, `docker-compose.scaling.yml`).
- Kubernetes spec (`k8s-deployment.yml`).
- Auto-scaling logic in `backend/auto_scaler.py`.
g. **Backup & Failover**
- Backup server manager (`backend/ha_server_manager.py`).
- DNS failover scripts (`scripts/update_dns.sh`, `scripts/dns_failover_monitor.sh`).
- PostgreSQL and Redis replication examples in `examples_archive`.

##### Architectural Patterns & Design Principles
- **Micro-instance** pattern: multiple identical game-server containers behind a load balancer.
- **Circuit Breaker**: isolate failures to Redis or PostgreSQL, auto-recovery.
- **Hybrid Data Layer**: real-time (Redis) + durable (PostgreSQL).
- **Auto-scaling**: dynamically adjust server count based on load.
- **High Availability**: HAProxy + Keepalived for LB, Patroni or streaming replication for Postgres.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        CLI["Python CLI/WebSocket Client"]:::external
    end

    %% Edge Layer
    subgraph "Edge"
        direction TB
        LB["HAProxy Load Balancer"]:::stateless
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        AppEntry["App Entry (backend/app.py)"]:::stateless
        Server["Game Server (backend/server.py)"]:::stateless
        subgraph "Authentication"
            direction TB
            AuthRoutes["Auth Routes (auth_routes.py)"]:::stateless
            AuthService["Auth Service (auth_service.py)"]:::stateless
        end
        subgraph "Game Logic"
            direction TB
            GameBoard["Game Board (game_board.py)"]:::stateless
            GameStates["Game States (game_states.py)"]:::stateless
            GameBoardDelta["Board Delta (game_board_delta.py)"]:::stateless
            GameStateDelta["State Delta (game_state_delta.py)"]:::stateless
        end
        subgraph "Fault Tolerance"
            direction TB
            CircuitBreaker["Circuit Breaker (circuit_breaker.py)"]:::fault
            CBMonitor["CB Monitor (circuit_breaker_monitor.py)"]:::fault
            AutoScaler["Auto-Scaler (auto_scaler.py)"]:::fault
            HABackupMgr["HA Backup Manager (ha_server_manager.py)"]:::fault
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        subgraph "Redis Cluster"
            direction TB
            RedisCluster["Redis Cluster"]:::db
            AsyncRedisMgr["Async Redis Manager (async_redis_manager.py)"]:::db
            RedisClusterMgr["Redis Cluster Manager (redis_cluster_manager.py)"]:::db
            HybridLayer["Hybrid Data Layer (hybrid_data_layer.py)"]:::db
        end
        subgraph "PostgreSQL Cluster"
            direction TB
            PostgresCluster["PostgreSQL Cluster"]:::db
            PostgresPersist["PostgreSQL Persistence (postgresql_persistence.py)"]:::db
            DBConnection["DB Connection (db_connection.py)"]:::db
            DatabaseMgr["Database Manager (database_manager.py)"]:::db
        end
    end

    %% Infrastructure & Services
    subgraph "Infrastructure & Services"
        direction TB
        Compose["Docker Compose"]:::infra
        K8s["Kubernetes Deployment"]:::infra
        subgraph "Monitoring & Health"
            direction TB
            HealthEndpt["HTTP /health Endpoint"]:::infra
            RedisMonitor["Redis Cluster Monitor"]:::infra
            BackupHealth["Backup Health Script"]:::infra
        end
        subgraph "Backup & Failover"
            direction TB
            DNSFailover["DNS Failover Script"]:::infra
            BackupScript["Backup Scripts"]:::infra
        end
        subgraph "Examples & Configs"
            direction TB
            PGHAExamples["Postgres HA & Prometheus Configs"]:::infra
        end
    end

    %% Connections
    CLI -->|"WS"| LB
    LB -->|"WS"| AppEntry
    AppEntry -->|"routes"| AuthRoutes
    AuthRoutes -->|"calls"| AuthService
    AppEntry -->|"spawns"| Server
    Server -->|"uses"| GameBoard
    Server -->|"uses"| GameStates
    Server -->|"updates"| GameBoardDelta
    Server -->|"updates"| GameStateDelta
    Server -->|"wraps"| CircuitBreaker
    CircuitBreaker -->|"monitored by"| CBMonitor
    Server -->|"scaling via"| AutoScaler
    Server -->|"fails over via"| HABackupMgr
    Server -->|"reads/writes"| RedisCluster
    RedisCluster -->|"managed by"| AsyncRedisMgr
    RedisCluster -->|"cluster mgmt"| RedisClusterMgr
    Server -->|"fallback writes"| HybridLayer
    Server -->|"reads/writes"| PostgresCluster
    PostgresCluster -->|"persist via"| PostgresPersist
    PostgresCluster -->|"connect via"| DBConnection
    PostgresCluster -->|"managed by"| DatabaseMgr
    AppEntry -->|"exposes"| HealthEndpt
    CBMonitor -->|"feeds metrics to"| RedisMonitor
    BackupHealth -->|"checks"| PostgresCluster
    DNSFailover -->|"switches"| HABackupMgr
    Compose -->|"orchestrates"| Server
    K8s -->|"deploys"| Server
    PGHAExamples -->|"demo infra"| Compose

    %% Click Events
    click CLI "https://github.com/parisasokuti/ds_project/blob/main/backend/client.py"
    click LB "https://github.com/parisasokuti/ds_project/blob/main/backend/load_balancer.py"
    click AppEntry "https://github.com/parisasokuti/ds_project/blob/main/backend/app.py"
    click Server "https://github.com/parisasokuti/ds_project/blob/main/backend/server.py"
    click AuthRoutes "https://github.com/parisasokuti/ds_project/blob/main/backend/auth_routes.py"
    click AuthService "https://github.com/parisasokuti/ds_project/blob/main/backend/auth_service.py"
    click GameBoard "https://github.com/parisasokuti/ds_project/blob/main/backend/game_board.py"
    click GameStates "https://github.com/parisasokuti/ds_project/blob/main/backend/game_states.py"
    click GameBoardDelta "https://github.com/parisasokuti/ds_project/blob/main/backend/game_board_delta.py"
    click GameStateDelta "https://github.com/parisasokuti/ds_project/blob/main/backend/game_state_delta.py"
    click CircuitBreaker "https://github.com/parisasokuti/ds_project/blob/main/backend/circuit_breaker.py"
    click CBMonitor "https://github.com/parisasokuti/ds_project/blob/main/backend/circuit_breaker_monitor.py"
    click AutoScaler "https://github.com/parisasokuti/ds_project/blob/main/backend/auto_scaler.py"
    click HABackupMgr "https://github.com/parisasokuti/ds_project/blob/main/backend/ha_server_manager.py"
    click AsyncRedisMgr "https://github.com/parisasokuti/ds_project/blob/main/backend/async_redis_manager.py"
    click RedisClusterMgr "https://github.com/parisasokuti/ds_project/blob/main/backend/redis_cluster_manager.py"
    click HybridLayer "https://github.com/parisasokuti/ds_project/blob/main/backend/hybrid_data_layer.py"
    click PostgresPersist "https://github.com/parisasokuti/ds_project/blob/main/backend/postgresql_persistence.py"
    click DBConnection "https://github.com/parisasokuti/ds_project/blob/main/backend/db_connection.py"
    click DatabaseMgr "https://github.com/parisasokuti/ds_project/blob/main/backend/database_manager.py"
    click HealthEndpt "https://github.com/parisasokuti/ds_project/blob/main/backend/app.py"
    click RedisMonitor "https://github.com/parisasokuti/ds_project/blob/main/backend/redis_cluster_monitor.py"
    click BackupHealth "https://github.com/parisasokuti/ds_project/blob/main/scripts/backup_health_monitor.sh"

    %% Styles
    classDef stateless fill:#D0E8FF,stroke:#0B69A3,stroke-width:2px
    classDef db fill:#DFFFE0,stroke:#2D8A00,stroke-width:2px
    classDef fault fill:#FFE8CC,stroke:#D97104,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#757575,stroke-width:2px
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,stroke-width:2px
```
