# dragonfly-ai/slash architecture

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

- Interactive diagram: https://gitdiagram.com/dragonfly-ai/slash
- Repository: https://github.com/dragonfly-ai/slash

## Overview

##### Project Type and Purpose
- This is a multi‐module, cross‐platform Scala library (S.L.A.S.H: Scala Linear Algebra & Statistics Hacks).
- It provides high‐performance vector, matrix, and statistical/distribution APIs, compiling to three targets: JVM, Native, and JavaScript.

##### File‐Structure Analysis
- Top‐level modules:
- slash/shared – core implementation (vector, matrix, stats, distributions, geometry, etc.)
- slash/js – Scala.js platform adapter (compiles shared → JS)
- slash/jvm-native – JVM & Native adapter (compiles shared → JVM/Native)
- Supporting modules:
- tests/shared – unit tests against shared code
- verification – fidelity‐checking subproject comparing with JAMA implementation
- jsdocs/livechart – interactive JS demo of charting APIs
- docs & docs/js – Markdown and a small JS frontend for documentation website
- project & build.sbt – sbt build definitions & plugins
- .github/workflows – CI/CD pipelines (ci.yml, clean.yml)
- Other files: configuration (.gitignore, .scalafmt.conf), license, logo, verification spreadsheet.

##### Key Insights from README
- Design goals emphasize cross‐compilation, performance, minimal footprint, seamless interop.
- Uses Scala 3 features: opaque types, dependent types, extension methods.
- Relies on external NArr library for native arrays (Float64Array in JS; Array[Double] on JVM/Native).
- Has a rich feature set: vector/matrix ops with compile‐time dimension checks; parametric and streaming distributions; geometry; logarithm macros; histograms; bijections.

a. Main Components
1. Core Module (slash/shared): implements all algorithms, types, and common logic
2. Platform Adapters:
– JS Adapter (slash/js) → compiles core to Scala.js/JavaScript
– JVM/Native Adapter (slash/jvm-native) → compiles core to JVM and Scala Native
3. Build & Packaging (sbt): orchestrates compilation, testing, publishing to Maven/JS artifact repository
4. Testing & Verification:
– Unit Test Suite (tests/shared)
– Verification Subproject (verification) comparing against JAMA
5. Documentation & Demos:
– Markdown docs (docs/)
– jsdocs/livechart demo (interactive web chart)
6. CI/CD Pipeline (GitHub Actions): runs build, test, formatting, site deployment
7. External Dependencies: NArr library; sbt plugins; Scala.js, Scala Native, sbt‐bundler, etc.

b. Relationships & Data Flows
- The Build System (sbt) sits at the center, taking slash/shared and producing platform‐specific artifacts via slash/js and slash/jvm-native.
- The Core Module exports APIs consumed by both adapters.
- Tests and verification depend on the Core Module artifact (pre‐publish, local build).
- Documentation pipeline reads source and jsdocs to generate site.
- CI/CD pulls code, invokes sbt tasks, and publishes artifacts and doc site.

c. Architectural Patterns & Principles
- Multi‐module monorepo with clear separation of core logic and platform bindings.
- Code‐reuse by centralizing algorithms in slash/shared.
- Cross-compilation pattern: single codebase → multiple targets.
- Compile‐time safety: opaque & dependent types to enforce dimensional correctness.
- Extension methods to augment core types.

d. Key Technologies & Frameworks
- Scala 3 (opaque types, macros, dependent types)
- sbt (multi‐project build, cross‐compilation)
- Scala.js & Scala Native
- NArr (native array abstraction)
- GitHub Actions (ci.yml, clean.yml)
- jsdocs & a minimal JS frontend for interactive documentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Library Code Modules
    subgraph "Library Code"
        core["slash/shared\n(Core Module)"]:::core
        jsAdapter["slash/js\n(JS Adapter)"]:::adapter
        jvmAdapter["slash/jvm-native\n(JVM & Native Adapter)"]:::adapter
    end

    %% Build & Release
    subgraph "Build & Release"
        actions["GitHub Actions\n(CI/CD)"]:::ci
        sbt["sbt Build System\n(build.sbt, plugins.sbt, build.properties)"]:::build
    end

    %% Testing & Verification
    subgraph "Testing & Verification"
        tests["tests/shared\n(Unit Tests)"]:::tests
        verif["verification\n(Verification Subproject)"]:::tests
    end

    %% Documentation & Demos
    subgraph "Documentation & Demos"
        md["docs\n(Markdown Docs)"]:::docs
        docjs["docs/js\n(JS Frontend)"]:::docs
        live["jsdocs/livechart\n(Interactive Demo)"]:::docs
    end

    %% Build Flow Connections
    actions -->|"triggers sbt tasks"| sbt
    sbt -->|"compiles core"| core
    core -->|"feeds"| jsAdapter
    core -->|"feeds"| jvmAdapter
    sbt -->|"cross-compiles"| jsAdapter
    sbt -->|"cross-compiles"| jvmAdapter
    sbt -->|"runs tests"| tests
    sbt -->|"runs verification"| verif
    sbt -->|"generates docs"| md
    sbt -->|"builds doc frontend"| docjs
    sbt -->|"packages demo"| live

    %% Module Dependencies
    core -->|"APIs consumed by"| jsAdapter
    core -->|"APIs consumed by"| jvmAdapter
    core -->|"core library for"| tests
    core -->|"core library for"| verif

    %% Documentation Flow
    md -->|"used by"| docjs
    docjs -->|"integrated into"| md
    md -->|"drives"| live

    %% Click Events
    click core "https://github.com/dragonfly-ai/slash/tree/main/slash/shared/src/main/scala/slash"
    click jsAdapter "https://github.com/dragonfly-ai/slash/tree/main/slash/js/src/main/scala/slash"
    click jvmAdapter "https://github.com/dragonfly-ai/slash/tree/main/slash/jvm-native/src/main/scala/slash"
    click sbt "https://github.com/dragonfly-ai/slash/blob/main/build.sbt"
    click sbt "https://github.com/dragonfly-ai/slash/blob/main/project/plugins.sbt"
    click sbt "https://github.com/dragonfly-ai/slash/blob/main/project/build.properties"
    click tests "https://github.com/dragonfly-ai/slash/tree/main/tests/shared/src/test/scala"
    click verif "https://github.com/dragonfly-ai/slash/tree/main/verification/src/main/scala/verification"
    click md "https://github.com/dragonfly-ai/slash/tree/main/docs"
    click docjs "https://github.com/dragonfly-ai/slash/blob/main/docs/js/main.js"
    click live "https://github.com/dragonfly-ai/slash/blob/main/jsdocs/livechart/index.html"
    click actions "https://github.com/dragonfly-ai/slash/blob/main/.github/workflows/ci.yml"
    click actions "https://github.com/dragonfly-ai/slash/blob/main/.github/workflows/clean.yml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef adapter fill:#90EE90,stroke:#000,stroke-width:1px
    classDef tests fill:#FFA500,stroke:#000,stroke-width:1px
    classDef docs fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ci fill:#C0C0C0,stroke:#000,stroke-width:1px
```
