# ruvnet/ruv-fann architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/ruv-fann
- Repository: https://github.com/ruvnet/ruv-fann

## Overview

##### Project type and purpose
- This is a multi-module, full-stack monorepo for a Rust-based neural-network foundation (ruv-FANN), an advanced forecasting library (neuro-divergent), and a multi-agent orchestration framework (ruv-swarm) with WebAssembly and JavaScript/Node.js front-ends.
- The README emphasizes:
- ruv-FANN: core Rust crate implementing FANN-compatible neural networks
- neuro-divergent: Rust forecasting library built on ruv-FANN
- ruv-swarm: multi-agent system using ruv-FANN and hosting rich CLI, WASM, and npm bindings

##### File structure
- Top-level Rust crates under `Cargo.toml`:
- src/… (core ruv-FANN code)
- neuro-divergent/…
- ruv-swarm/…
- Under `ruv-swarm/crates`: many sub-crates—for core swarm logic, transport, persistence, ML, DAA, MCP, CLI, WASM builds, benchmarks
- Under `ruv-swarm/npm`: full JS/TypeScript wrapper, tests, Dockerfiles, build scripts
- Under `claude-code-flow`, `daa-swarm`, and other plan directories: design documents and planning
- Standard CI configs, Docker compositions, tests and examples interwoven

##### README for insights
- Core architecture: layered Rust crates → WASM targets → npm package → CLI and browser examples
- Highlights dependencies: polars, serde, rayon, wasm-bindgen, Docker, Jest, CI pipelines

##### Detail
- Link CLI commands → internal core functions
- End-to-end stack: data → neural network → forecast → swarm orchestration → client
- Don’t omit the I/O subsystem (binary, JSON, FANN formats) or training algorithms (Backprop, RPROP, Cascade)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: Clients/UI
    subgraph "Clients / UI"
        direction TB
        Browser["Browser UI"]:::ext
        CLI["ruv-swarm CLI"]:::ext
    end

    %% JavaScript / Node.js Layer
    subgraph "JavaScript / npm Layer" 
        direction TB
        NPM["ruv-swarm npm package"]:::js
        WasmLoader["wasm-loader.js"]:::js
    end

    %% WebAssembly Modules
    subgraph "WebAssembly Modules"
        direction TB
        WASM_Unified["ruv-swarm-wasm-unified"]:::wasm
        WASM_Modular["ruv-swarm-wasm"]:::wasm
    end

    %% Rust Multi-Agent & Forecasting
    subgraph "Rust Multi-Agent & Forecasting"
        direction TB
        subgraph "Forecasting Layer"
            direction TB
            NeuroDivCore["neuro-divergent core"]:::rust
            NeuroDivSrc["neuro-divergent src"]:::rust
        end
        subgraph "Multi-Agent Layer"
            direction TB
            SwarmCore["ruv-swarm-core"]:::rust
            Agents["ruv-swarm-agents"]:::rust
            Transport["Transport Module"]:::rust
            PersistenceMod["Persistence Module"]:::rust
            MLHelpers["ML Helpers"]:::rust
            DAA["ruv-swarm-daa"]:::rust
            MCP["ruv-swarm-mcp"]:::rust
        end
    end

    %% Core Rust Engine
    CoreEngine["ruv-FANN Core Engine"]:::rust

    %% External Services / Data Sources
    subgraph "External Services & Data"
        direction TB
        GitHub["GitHub"]:::ext
        Prometheus["Prometheus"]:::ext
        Docker["Docker / Docker Compose"]:::ext
        DataSources["Polars / CSV Data"]:::db
        CI["CI Pipelines"]:::ext
    end

    %% Connections
    Browser -->|"invokes"| NPM
    CLI -->|"invokes"| CoreEngine
    NPM -->|"loads WASM"| WASM_Modular
    NPM -->|"loads WASM"| WASM_Unified
    WASM_Modular -->|"binds to"| SwarmCore
    WASM_Unified -->|"binds to"| SwarmCore
    SwarmCore -->|"depends on"| NeuroDivSrc
    NeuroDivSrc -->|"wraps"| CoreEngine
    NeuroDivCore -->|"builds on"| CoreEngine
    Transport -->|"used by"| SwarmCore
    PersistenceMod -->|"used by"| SwarmCore
    MLHelpers -->|"used by"| SwarmCore
    DAA -->|"plugin to"| SwarmCore
    MCP -->|"integration with"| SwarmCore
    CoreEngine -->|"provides compute"| NeuroDivCore
    DataSources -->|"feeds data"| NeuroDivCore
    GitHub -->|"API calls"| CLI
    CI -->|"runs tests"| CoreEngine
    Docker -->|"containerizes"| NPM

    %% Click Events
    click CoreEngine "https://github.com/ruvnet/ruv-fann/tree/main/src/"
    click NeuroDivSrc "https://github.com/ruvnet/ruv-fann/tree/main/neuro-divergent/src/"
    click NeuroDivCore "https://github.com/ruvnet/ruv-fann/tree/main/neuro-divergent/neuro-divergent-core/src/"
    click SwarmCore "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-core/src/"
    click Agents "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-agents/src/"
    click CLI "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-cli/src/"
    click Transport "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-transport/src/"
    click PersistenceMod "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-persistence/src/"
    click MLHelpers "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-ml/src/"
    click DAA "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-daa/src/"
    click MCP "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-mcp/src/"
    click WASM_Unified "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-wasm-unified/src/"
    click WASM_Modular "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/crates/ruv-swarm-wasm/src/"
    click NPM "https://github.com/ruvnet/ruv-fann/tree/main/ruv-swarm/npm/src/"
    click WasmLoader "https://github.com/ruvnet/ruv-fann/blob/main/ruv-swarm/npm/src/wasm-loader.js"

    %% Styles
    classDef rust fill:#D0E1F9,stroke:#4F81BD,stroke-width:1px
    classDef wasm fill:#D4EFDF,stroke:#28B463,stroke-width:1px
    classDef js fill:#FCF3CF,stroke:#F1C40F,stroke-width:1px
    classDef db fill:#FADBD8,stroke:#C0392B,stroke-width:1px,stroke-dasharray: 5 5
    classDef ext fill:#E8DAEF,stroke:#8E44AD,stroke-width:1px,stroke-dasharray: 5 5
```
