# dhakalnirajan/stockzero architecture

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

- Interactive diagram: https://gitdiagram.com/dhakalnirajan/stockzero
- Repository: https://github.com/dhakalnirajan/stockzero

## Overview

##### Main components
- Backend/Django Infrastructure:
- Core project configuration under the "stockzero" directory (settings, URLs, ASGI/WGSI).
- REST API components as part of the "webapp/chessgame" Django app (models, serializers, views) for game logging and communication.
- Frontend serving via the "webapp/frontend" app; includes HTML templates, static CSS/JS assets (chess_gui.js, styles.css).
- AI Engine Components:
- Chess engine modules in the "engine" directory (MCTS implementation, policy/value network in model.py, RL agent in rl_agent.py, and traditional engine).
- Inference layer in the "inference" directory which optimizes move generation using GPU and Redis caching.
- Training Infrastructure:
- Training scripts and utilities in the "training" directory for self-play, data handling, and neural network training.
- Django management command for training (located in "management/commands/train_model.py") to trigger model training.
- Model Management:
- Storage of versioned model weights within the "models" directory.
- Logging & Deployment:
- Logging directories ("logs") for both engine and webapp events.
- Supporting deployment scripts (manage.sh, setup_server.sh) and documentation files.

##### Relationships and interactions
- The Frontend (in "webapp/frontend") communicates with the Django backend API (in "webapp/chessgame") to facilitate real-time game play and log PGN game data.
- The Django backend interacts with the RL chess engine:
- It calls services in the "engine" to compute moves (via RL agent, MCTS, etc.) when a game is in session.
- When a move requires inference, the call goes to the "inference" module which uses Redis for caching and leverages GPU acceleration.
- The training module regularly updates model weights which are stored in the "models" directory. There is a feedback loop where post-training, the engine loads the new model for gameplay.
- External systems like PostgreSQL (for game logging) and Redis (for caching inference results) are critical external dependencies.

##### Key architectural patterns and design principles
- Layered Architecture: Clear separation between the presentation (frontend), application logic (Django REST API), business logic (engine & inference modules), training routines, and persistent storage.
- Modular design: Distinct modules for inference, training, and game execution allow independent scalability and maintenance.
- Separation of Concerns:
- UI rendering vs. API logic.
- Real-time game interaction vs. background training.
- Static asset management and backend processing are separated.
- Use of management commands and scripts facilitates clear CI/CD and deployment practices.

##### Relevant technologies, frameworks, and libraries
- Backend: Django (including Django REST Framework), Gunicorn (for production deployment), PostgreSQL, and Redis.
- AI/ML Components: TensorFlow/Keras for neural network implementations.
- Frontend: HTML/CSS/JavaScript.
- Auxiliary Tools: Scripts for management and deployment (Bash scripts like manage.sh, setup_server.sh), Docker or similar containerization (if applicable based on deployment docs).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External User
    U(["User"]):::external

    %% Backend Layer
    subgraph "Backend Layer"
        DC["Django Core Project Configuration"]:::backend
        DA["Webapp - API (Chess Game)"]:::backend
        FE["Webapp - Frontend"]:::frontend
    end

    %% AI Engine Layer
    subgraph "AI Engine Layer"
        CE["AI Chess Engine (RL Agent, MCTS, Traditional)"]:::ai
        IE["Inference Engine (GPU & Redis)"]:::ai
    end

    %% Training & Model Layer
    subgraph "Training & Model"
        TR["Training Module"]:::training
        TC["Model Training Command"]:::training
        MM["Model Management"]:::model
    end

    %% External Services
    subgraph "External Services"
        PG["Database: PostgreSQL"]:::db
        RD["Cache: Redis"]:::cache
        GPU["GPU Acceleration"]:::gpu
    end

    %% Supporting Services
    subgraph "Supporting Services"
        LG["Logging (Engine & Webapp)"]:::logging
        DS["Deployment Scripts"]:::deploy
    end

    %% Data flow arrows
    U -->|"initiates"| FE
    FE -->|"RESTcall"| DA
    DA -->|"configLookup"| DC
    DA -->|"moveRequest"| CE
    CE -->|"callsInference"| IE
    IE -->|"utilizes"| GPU
    IE -->|"cachesWith"| RD
    DA -->|"logsPGN"| PG
    DA -->|"sendsLog"| LG
    CE -->|"sendsLog"| LG
    TR -->|"updates"| MM
    MM -->|"reloadWeights"| CE
    TC -->|"triggers"| TR

    %% Class definitions for styling
    classDef backend fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef ai fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef training fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef model fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef db fill:#D2B4DE,stroke:#333,stroke-width:2px;
    classDef cache fill:#FADBD8,stroke:#333,stroke-width:2px;
    classDef gpu fill:#D6EAF8,stroke:#333,stroke-width:2px;
    classDef logging fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FDF2E9,stroke:#333,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#333,stroke-width:2px;
    
    %% Click Events
    click DC "https://github.com/dhakalnirajan/stockzero/blob/main/stockzero/settings.py"
    click DA "https://github.com/dhakalnirajan/stockzero/blob/main/webapp/chessgame/models.py"
    click FE "https://github.com/dhakalnirajan/stockzero/blob/main/webapp/frontend/templates/frontend/game.html"
    click CE "https://github.com/dhakalnirajan/stockzero/blob/main/engine/mcts.py"
    click IE "https://github.com/dhakalnirajan/stockzero/blob/main/inference/inference_engine.py"
    click TR "https://github.com/dhakalnirajan/stockzero/blob/main/training/self_play.py"
    click TC "https://github.com/dhakalnirajan/stockzero/blob/main/management/commands/train_model.py"
    click MM "https://github.com/dhakalnirajan/stockzero/blob/main/models/StockZero-v1-2025-03-24.weights.h5"
    click LG "https://github.com/dhakalnirajan/stockzero/blob/main/logs/engine.log"
    click DS "https://github.com/dhakalnirajan/stockzero/blob/main/manage.sh"
```
