# nianzu/scylla architecture

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

- Interactive diagram: https://gitdiagram.com/nianzu/scylla
- Repository: https://github.com/nianzu/scylla

## Overview

##### Project Type & Purpose
- Scylla is an open-source, Rust-based command-line chess engine that uses a multi-agent neural network architecture.
- In “inference mode” it loads seven pre-trained models (one piece-selector + six piece-specific move selectors) to pick and execute chess moves.
- In “training mode” it ingests pre-processed game data (the MNIST-style datasets generated by the companion Scylla_preprocessor tool), trains or retrains any subset of the seven networks, and writes updated binaries to the trained_network directory.

##### File Structure Analysis
- Cargo.toml / Cargo.lock – Rust project manifest and locked dependency versions.
- src/
– main.rs: CLI entry point, argument parsing (play vs train), game loop, I/O.
– neural_network.rs: abstraction for loading, invoking, and (re)training a single network.
- datasets/mnist/ – input feature/label files for training (generated externally).
- trained_network/ – output .bin model files, one per network agent.
- readme.md – high-level overview, usage, training instructions, methodology.

##### Key Insights from README
- Seven independent neural agents collaborate each turn:
- Piece Selector: chooses which piece to move.
- Six Move Selectors: one for pawn, knight, bishop, rook, queen, king.
- Composition rule: piece selector’s probabilities combine with the relevant move selector’s outputs to form the final move choice.
- Two modes of operation:
- Inference: load .bin models → run game loop.
- Training: load datasets → train specified networks → overwrite .bin files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Game Logic
    subgraph "CLI & Game Logic"
        CLI["CLI Frontend / User Interface"]:::green
        GameLoop["Game Loop & Board State Manager"]:::green
    end

    %% Neural Components
    subgraph "Neural Network Coordinator"
        PieceSel["Piece Selector Agent"]:::blue
        PawnSel["Pawn Move Selector Agent"]:::blue
        KnightSel["Knight Move Selector Agent"]:::blue
        BishopSel["Bishop Move Selector Agent"]:::blue
        RookSel["Rook Move Selector Agent"]:::blue
        QueenSel["Queen Move Selector Agent"]:::blue
        KingSel["King Move Selector Agent"]:::blue
    end

    %% I/O Components
    subgraph "I/O Services"
        ModelIO["Model Loader / Saver"]:::orange
        DatasetIO["Dataset Loader"]:::orange
    end

    %% External Service
    Preproc["Scylla_preprocessor Service"]:::external

    %% Documentation and Manifest
    Manifest["Project Manifest & Dependencies"]:::grey
    Readme["High-level Documentation & Usage Instructions"]:::grey

    %% Relationships & Data Flows
    CLI -->|"play/train"| GameLoop
    GameLoop -->|"init board, mode"| GameLoop
    GameLoop -->|"board features"| PieceSel
    GameLoop -->|"board features"| PawnSel
    GameLoop -->|"board features"| KnightSel
    GameLoop -->|"board features"| BishopSel
    GameLoop -->|"board features"| RookSel
    GameLoop -->|"board features"| QueenSel
    GameLoop -->|"board features"| KingSel

    PieceSel -->|"probabilities"| GameLoop
    PawnSel -->|"probabilities"| GameLoop
    KnightSel -->|"probabilities"| GameLoop
    BishopSel -->|"probabilities"| GameLoop
    RookSel -->|"probabilities"| GameLoop
    QueenSel -->|"probabilities"| GameLoop
    KingSel -->|"probabilities"| GameLoop

    %% Model Load on Startup
    PieceSel -->|"load .bin weights"| ModelIO
    PawnSel -->|"load .bin weights"| ModelIO
    KnightSel -->|"load .bin weights"| ModelIO
    BishopSel -->|"load .bin weights"| ModelIO
    RookSel -->|"load .bin weights"| ModelIO
    QueenSel -->|"load .bin weights"| ModelIO
    KingSel -->|"load .bin weights"| ModelIO

    %% Training Mode Data Flow
    DatasetIO -->|"feature/label batch (IDX format)"| PieceSel
    DatasetIO -->|"feature/label batch (IDX format)"| PawnSel
    DatasetIO -->|"feature/label batch (IDX format)"| KnightSel
    DatasetIO -->|"feature/label batch (IDX format)"| BishopSel
    DatasetIO -->|"feature/label batch (IDX format)"| RookSel
    DatasetIO -->|"feature/label batch (IDX format)"| QueenSel
    DatasetIO -->|"feature/label batch (IDX format)"| KingSel

    PieceSel -->|"save .bin weights"| ModelIO
    PawnSel -->|"save .bin weights"| ModelIO
    KnightSel -->|"save .bin weights"| ModelIO
    BishopSel -->|"save .bin weights"| ModelIO
    RookSel -->|"save .bin weights"| ModelIO
    QueenSel -->|"save .bin weights"| ModelIO
    KingSel -->|"save .bin weights"| ModelIO

    %% External Preprocessor to Dataset Loader
    Preproc -->|"generate IDX files"| DatasetIO

    %% Manifest and Documentation
    Manifest --> Readme

    %% Click Events
    click CLI "https://github.com/nianzu/scylla/blob/master/src/main.rs"
    click GameLoop "https://github.com/nianzu/scylla/blob/master/src/main.rs"
    click PieceSel "https://github.com/nianzu/scylla/blob/master/trained_network/piece_selector.bin"
    click PawnSel "https://github.com/nianzu/scylla/blob/master/trained_network/pawn.bin"
    click KnightSel "https://github.com/nianzu/scylla/blob/master/trained_network/knight.bin"
    click BishopSel "https://github.com/nianzu/scylla/blob/master/trained_network/bishop.bin"
    click RookSel "https://github.com/nianzu/scylla/blob/master/trained_network/rook.bin"
    click QueenSel "https://github.com/nianzu/scylla/blob/master/trained_network/queen.bin"
    click KingSel "https://github.com/nianzu/scylla/blob/master/trained_network/king.bin"
    click ModelIO "https://github.com/nianzu/scylla/blob/master/src/neural_network.rs"
    click DatasetIO "https://github.com/nianzu/scylla/blob/master/datasets/mnist/*.idx*"
    click Manifest "https://github.com/nianzu/scylla/blob/master/Cargo.toml"
    click Readme "https://github.com/nianzu/scylla/blob/master/readme.md"

    %% Styles
    classDef green fill:#e0f7e9,stroke:#2d7a37,stroke-width:2px
    classDef blue fill:#e0ebff,stroke:#1f4287,stroke-width:2px
    classDef orange fill:#fff4e5,stroke:#d9822b,stroke-width:2px
    classDef grey fill:#f0f0f0,stroke:#888888,stroke-width:1px
    classDef external fill:#ffffff,stroke:#ff0000,stroke-dasharray:5 5,stroke-width:2px

    %% Legend
    subgraph "Legend"
        A["CLI & Game Logic"]:::green
        B["Neural Components"]:::blue
        C["I/O Services"]:::orange
        D["External Service"]:::external
        E["Docs & Manifest"]:::grey
    end
```
