# gastrodon/eevee architecture

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

- Interactive diagram: https://gitdiagram.com/gastrodon/eevee
- Repository: https://github.com/gastrodon/eevee

## Overview

##### Project type and purpose
- It provides core APIs for genome representation, mutation, reproduction, speciation, and evaluation through user-defined scenarios.
- It also ships with example applications (e.g., XOR, sentiment analysis, NES-Tetris) and command-line utilities for benchmarking and profiling.

##### File structure
Top-level artifacts:
- Cargo.toml / Cargo.lock, src/lib.rs – Rust crate manifest and library root
- Dockerfile / .github/workflows – CI and containerization scripts
- benches/, examples/, cmp-bench, cmp-profile, profile – CLI tools for benchmarking & profiling
- src/
– genome/ (connection, recurrent)
– network/ (binary, continuous, simple, non_bias)
– population.rs, reproduce.rs, crossover.rs, random.rs, serialize.rs, scenario.rs, macros.rs
Patterns & architecture:
- Modular Rust library, organized by domain (genome, network, population, etc.)
- Separation of core library vs. example binaries vs. bench/profile tools
- Extensible “Scenario” trait for plugging in evaluation functions

##### README
- Confirms NEAT-based algorithm; core loop: score genomes via Scenario → mutate/reproduce/cull → repeat
- External dependencies: criterion.rs (benchmarking), flamegraph & perf (profiling), fastrand (RNG), CTRNN code borrowed
- Usage examples in examples/ folder

a. Main components
1. Core Library Modules
- Genome Representation (src/genome)
- Neural Network Layers (src/network)
- Evolution Operations (mutation, crossover, speciation)
- Population Management
- Scenario Trait & Evaluation Engine
- RNG & Serialization
2. CLI Tools
- benches/ + cmp-bench – Benchmark suite using criterion.rs
- profile/ + cmp-profile – Profiling harness with flamegraph/perf
3. Example Clients
- XOR, sentiment, NES-Tetris applications
4. External Dependencies/Services
- criterion.rs, flamegraph, perf, fastrand
b. Relationships & data flows
- Scenario → provides fitness scores for each Genome
- Population Manager consumes genomes + fitness → applies mutation, crossover, speciation → new generation
- RNG module is used throughout (seeding via /dev/urandom)
- Serialization module reads/writes genomes to JSON (used by examples or persisted benchmarks)
- CLI tools invoke core library API in a loop (bench, profile) and collect metrics
- Examples link to the library, instantiate Scenario implementations, and drive training
c. Architectural patterns
- Strategy Pattern: Scenario trait abstracts evaluation function
- Modular layering: separation of concerns between representation (genome/network), evolution, and orchestration
- CLI-wrapper pattern: small binaries that use the library for specialized tasks (bench, profile)
d. Key technologies
- Rust (nightly for unstable features)
- criterion.rs (benchmarking)
- flamegraph/perf (profiling)
- fastrand (WyHash RNG)
- Docker/GitHub Actions (CI)

##### Summary of steps for the principal software engineer
4. Use clear labels and arrowheads to represent data and control flows in the neuroevolution loop.
8. Iterate with the team to refine clarity and completeness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Eevee Core Library"
        direction TB
        GR["Genome Representation"]:::lib
        CN["Connection Genome"]:::lib
        RR["Recurrent Genome"]:::lib
        NL["Neural Network Layers"]:::lib
        BN["Binary Layer"]:::lib
        CN2["Continuous Layer"]:::lib
        SN["Simple Layer"]:::lib
        NB["Non-bias Layer"]:::lib
        Evo["Evolution Operations"]:::lib
        Crossover["Crossover Operator"]:::lib
        Mutation["Mutation / RNG"]:::lib
        Reprod["Reproduction Logic"]:::lib
        Pop["Population Management"]:::lib
        Scenario["Scenario Trait & Evaluation Engine"]:::lib
        Ser["Genome Serialization"]:::lib
        API["Library Root & Public API"]:::lib
        Mac["Helper Macros"]:::lib
    end

    subgraph "Example Clients"
        direction TB
        XOR["XOR Example"]:::client
        Sent["Sentiment Example"]:::client
        NES["NES-Tetris Example"]:::client
    end

    subgraph "CLI Tools"
        direction TB
        Bench["Benchmark CLI Suite"]:::cli
        CBench["Benchmark Comparison Wrapper"]:::cli
        Profile["Profiling Harness"]:::cli
        CProfile["Profiling Comparison Wrapper"]:::cli
    end

    subgraph "External Dependencies"
        direction TB
        CR["criterion.rs"]:::ext
        FG["flamegraph"]:::ext
        PF["perf"]:::ext
        RNGdep["fastrand"]:::ext
        CI["GitHub Actions CI"]:::ext
        DOCK["Docker"]:::ext
    end

    %% Data Flow within Core
    Scenario -->|"scores genomes"| Pop
    Pop -->|"applies ops"| Evo
    Evo -->|"generates new genomes"| GR
    GR -->|"represents new generation"| Scenario

    %% Core API exposure
    API --> GR
    API --> CN
    API --> RR
    API --> NL
    API --> Evo
    API --> Pop
    API --> Scenario
    API --> Ser
    API --> Mutation
    API --> Reprod
    API --> Mac

    %% Examples and CLI usage
    XOR -->|uses API| API
    Sent -->|uses API| API
    NES -->|uses API| API

    Bench -->|imports library| API
    CBench -->|wraps Bench| API
    Profile -->|imports library| API
    CProfile -->|wraps Profile| API

    %% External deps
    CR -->|benchmarking| Bench
    FG -->|profiling| Profile
    PF -->|profiling| Profile
    RNGdep -->|RNG| Mutation
    CI -->|CI/CD| API
    DOCK -->|container| API

    %% Click Events
    click GR "https://github.com/gastrodon/eevee/blob/main/src/genome/mod.rs"
    click CN "https://github.com/gastrodon/eevee/blob/main/src/genome/connection.rs"
    click RR "https://github.com/gastrodon/eevee/blob/main/src/genome/recurrent.rs"
    click NL "https://github.com/gastrodon/eevee/blob/main/src/network/mod.rs"
    click BN "https://github.com/gastrodon/eevee/blob/main/src/network/binary.rs"
    click CN2 "https://github.com/gastrodon/eevee/blob/main/src/network/continuous.rs"
    click SN "https://github.com/gastrodon/eevee/blob/main/src/network/simple.rs"
    click NB "https://github.com/gastrodon/eevee/blob/main/src/network/non_bias.rs"
    click Crossover "https://github.com/gastrodon/eevee/blob/main/src/crossover.rs"
    click Mutation "https://github.com/gastrodon/eevee/blob/main/src/random.rs"
    click Reprod "https://github.com/gastrodon/eevee/blob/main/src/reproduce.rs"
    click Pop "https://github.com/gastrodon/eevee/blob/main/src/population.rs"
    click Scenario "https://github.com/gastrodon/eevee/blob/main/src/scenario.rs"
    click Ser "https://github.com/gastrodon/eevee/blob/main/src/serialize.rs"
    click API "https://github.com/gastrodon/eevee/blob/main/src/lib.rs"
    click Mac "https://github.com/gastrodon/eevee/blob/main/src/macros.rs"
    click Bench "https://github.com/gastrodon/eevee/tree/main/benches/"
    click CBench "https://github.com/gastrodon/eevee/tree/main/cmp-bench"
    click Profile "https://github.com/gastrodon/eevee/tree/main/profile/"
    click CProfile "https://github.com/gastrodon/eevee/tree/main/cmp-profile"
    click XOR "https://github.com/gastrodon/eevee/blob/main/examples/xor.rs"
    click Sent "https://github.com/gastrodon/eevee/blob/main/examples/sentiment/main.rs"
    click NES "https://github.com/gastrodon/eevee/blob/main/examples/nes-tetris/main.rs"
    click CI "https://github.com/gastrodon/eevee/blob/main/.github/workflows/ci.yml"
    click DOCK "https://github.com/gastrodon/eevee/tree/main/Dockerfile"

    %% Styles
    classDef lib fill:#D6EAF8,stroke:#3498DB
    classDef client fill:#D5F5E3,stroke:#27AE60
    classDef cli fill:#FCF3CF,stroke:#F1C40F
    classDef ext fill:#F5EEF8,stroke:#8E44AD,stroke-dasharray:5 5
```
