# joshuadam/neat-javascript architecture

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

- Interactive diagram: https://gitdiagram.com/joshuadam/neat-javascript
- Repository: https://github.com/joshuadam/neat-javascript

## Overview

##### Project type and purpose
- NEAT-JavaScript is an open-source library implementing the NEAT (Neuroevolution of Augmenting Topologies) algorithm in JavaScript.
- Its purpose is to provide a reusable, extensible engine for evolving neural networks (weights and topology) in both Node.js and browser environments.

##### File structure
- Top‐level:
- dist/ — compiled bundle for browser.
- src/ — source code organized by responsibility.
- webpack.config.js — build configuration.
- src subdirectories:
- activationfunction/ — strategy objects for neural activation (Sigmoid, ReLU, Tanh, etc.).
- weightinitialization/ — strategies for initial weight assignment.
- core/
– genome/ — defines Genome class, subpackages for ConnectionGene, NodeGene, and supporting genetic-encoding data structures.
– population/ — Population and Species classes to manage speciation and generation lifecycle.
- algorithm/ — the NEAT orchestrator (speciation, crossover, mutation loop).
- config/ — Config object for global parameters (mutation rates, population size).
- fitnessfunction/ — plugin/factory for user‐defined fitness evaluations (e.g., XOR).
- util/ — helpers: GenomeBuilder, StaticManager, and trackers (InnovationTracker, NodeTracker, etc.).
- package.json & README.md describe usage, examples, and build.

##### README for additional insights
- Confirms core components: speciation, crossover, structural mutation.
- Describes usage in Node.js and browser; links to demos.

##### Main components & relationships
- Config Module → holds algorithm parameters, passed to Algorithm.
- Algorithm Engine → central controller:
- initializes Population from GenomeBuilder + Config
- for each generation: evaluates fitness via FitnessFunction plugins, applies Speciation (Species class), Crossover & Mutation (connection and node mutations)
- Core Data Structures:
- Genome ← composed of NodeGenes + ConnectionGenes
- GeneticEncoding metadata to persist innovation numbers
- Utility Trackers ← global singletons capturing innovation count, node IDs, species IDs
- Strategy Modules (ActivationFunction, WeightInitialization) ← injected into Network evaluation
- Dist Bundle ← exposes public API (Algorithm, Config, GenomeBuilder, fitness templates)

##### Architectural patterns & design principles
- Strategy pattern for activation & weight initialization.
- Factory for GenomeBuilder and FitnessFunction.
- Singleton trackers for global innovation management.
- Modular layering: Core data models → Algorithm orchestration → User plugins → I/O (Node.js or browser bundle).

##### Components
- Population & Species (subcomponent under Algorithm)
- ActivationFunction & WeightInitialization strategies (parallel modules)
- FitnessFunction plugin (user‐provided)
- Utility Trackers (InnovationTracker, NodeTracker)
- Dist Bundle / Public API layer

##### Detail
- Subcomponents, especially the trackers and genetic encoding classes.
- Extension points: fitnessfunction, activationfunction, weightinitialization.
- Don’t omit the build step (webpack) and the dual runtime (Node/browser).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "src"
        subgraph "config"
            Config["Config Module"]:::api
        end
        subgraph "algorithm"
            Algorithm["Algorithm Engine"]:::coreEngine
        end
        subgraph "core"
            subgraph "population"
                Population["Population"]:::dataModel
                Species["Species"]:::dataModel
            end
            subgraph "genome"
                Genome["Genome"]:::dataModel
                ConnectionGene["ConnectionGene"]:::dataModel
                NodeGene["NodeGene"]:::dataModel
                subgraph "geneticencoding"
                    GeneticEncoding["GeneticEncoding"]:::dataModel
                    ConnectionGeneData["ConnectionGeneData"]:::dataModel
                    NodeGeneData["NodeGeneData"]:::dataModel
                end
            end
        end
        subgraph "activationfunction"
            AFBase["ActivationFunction"]:::strategy
            Sigmoid["Sigmoid"]:::strategy
            NEATSigmoid["NEATSigmoid"]:::strategy
            ReLU["ReLU"]:::strategy
            LeakyReLU["LeakyReLU"]:::strategy
            Tanh["Tanh"]:::strategy
            SELU["SELU"]:::strategy
            Gaussian["Gaussian"]:::strategy
        end
        subgraph "weightinitialization"
            WInitBase["WeightInitialization"]:::strategy
            RandomWInit["RandomWeightInitialization"]:::strategy
        end
        subgraph "fitnessfunction"
            FFBase["FitnessFunction"]:::strategy
            XOR["XOR"]:::strategy
        end
        subgraph "util"
            GenomeBuilder["GenomeBuilder"]:::utility
            StaticManager["StaticManager"]:::utility
            subgraph "trackers"
                ConfigTracker["ConfigTracker"]:::utility
                InnovationTracker["InnovationTracker"]:::utility
                NodeTracker["NodeTracker"]:::utility
                GenomeTracker["GenomeTracker"]:::utility
                PopulationTracker["PopulationTracker"]:::utility
            end
        end
        Index["Public API"]:::api
    end

    subgraph "dist"
        Dist["Dist Bundle"]:::api
    end

    Webpack["Webpack"]:::utility
    ExternalNode["Node.js"]:::external
    ExternalBrowser["Browser"]:::external

    Config --> Algorithm
    Algorithm --> Population
    Algorithm --> Species
    Population --> Genome
    Genome --> NodeGene
    Genome --> ConnectionGene
    Genome --> GeneticEncoding
    GeneticEncoding --> ConnectionGeneData
    GeneticEncoding --> NodeGeneData

    Algorithm --> AFBase
    Algorithm --> WInitBase
    Algorithm --> FFBase

    GenomeBuilder --> Population
    StaticManager --> Algorithm
    ConfigTracker --> Algorithm
    InnovationTracker --> Algorithm
    NodeTracker --> Algorithm
    GenomeTracker --> Algorithm
    PopulationTracker --> Algorithm

    Index --> Algorithm
    Index --> Config
    Index --> GenomeBuilder

    Index --> Dist
    Webpack --> Dist
    Dist --> ExternalNode
    Dist --> ExternalBrowser

    click Config "https://github.com/joshuadam/neat-javascript/blob/main/src/config/Config.js"
    click Algorithm "https://github.com/joshuadam/neat-javascript/blob/main/src/algorithm/Algorithm.js"
    click Population "https://github.com/joshuadam/neat-javascript/blob/main/src/core/population/Population.js"
    click Species "https://github.com/joshuadam/neat-javascript/blob/main/src/core/population/Species.js"
    click Genome "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/Genome.js"
    click ConnectionGene "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/genes/connectiongene/ConnectionGene.js"
    click NodeGene "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/genes/nodegene/NodeGene.js"
    click GeneticEncoding "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/genes/geneticencoding/GeneticEncoding.js"
    click ConnectionGeneData "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/genes/geneticencoding/ConnectionGeneData.js"
    click NodeGeneData "https://github.com/joshuadam/neat-javascript/blob/main/src/core/genome/genes/geneticencoding/NodeGeneData.js"
    click AFBase "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/ActivationFunction.js"
    click Sigmoid "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/Sigmoid.js"
    click NEATSigmoid "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/NEATSigmoid.js"
    click ReLU "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/ReLU.js"
    click LeakyReLU "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/LeakyReLU.js"
    click Tanh "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/Tanh.js"
    click SELU "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/SELU.js"
    click Gaussian "https://github.com/joshuadam/neat-javascript/blob/main/src/activationfunction/Gaussian.js"
    click WInitBase "https://github.com/joshuadam/neat-javascript/blob/main/src/weightinitialization/WeightInitialization.js"
    click RandomWInit "https://github.com/joshuadam/neat-javascript/blob/main/src/weightinitialization/RandomWeightInitialization.js"
    click FFBase "https://github.com/joshuadam/neat-javascript/blob/main/src/fitnessfunction/FitnessFunction.js"
    click XOR "https://github.com/joshuadam/neat-javascript/blob/main/src/fitnessfunction/XOR.js"
    click GenomeBuilder "https://github.com/joshuadam/neat-javascript/blob/main/src/util/GenomeBuilder.js"
    click StaticManager "https://github.com/joshuadam/neat-javascript/blob/main/src/util/StaticManager.js"
    click ConfigTracker "https://github.com/joshuadam/neat-javascript/blob/main/src/util/trackers/ConfigTracker.js"
    click InnovationTracker "https://github.com/joshuadam/neat-javascript/blob/main/src/util/trackers/InnovationTracker.js"
    click NodeTracker "https://github.com/joshuadam/neat-javascript/blob/main/src/util/trackers/NodeTracker.js"
    click GenomeTracker "https://github.com/joshuadam/neat-javascript/blob/main/src/util/trackers/GenomeTracker.js"
    click PopulationTracker "https://github.com/joshuadam/neat-javascript/blob/main/src/util/trackers/PopulationTracker.js"
    click Index "https://github.com/joshuadam/neat-javascript/blob/main/src/index.js"
    click Dist "https://github.com/joshuadam/neat-javascript/blob/main/dist/NEAT-JavaScript.js"
    click Webpack "https://github.com/joshuadam/neat-javascript/blob/main/webpack.config.js"

    classDef coreEngine fill:#b3e2b3,stroke:#333
    classDef dataModel fill:#fdb462,stroke:#333
    classDef strategy fill:#c28fd3,stroke:#333
    classDef utility fill:#d9d9d9,stroke:#333
    classDef api fill:#80b1d3,stroke:#333
    classDef external fill:#ffffff,stroke:#333,stroke-dasharray: 2 2
```
