# bstaber/rustineers architecture

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

- Interactive diagram: https://gitdiagram.com/bstaber/rustineers
- Repository: https://github.com/bstaber/rustineers

## Overview

##### Project type and purpose
- This is an open-source, educational monorepo that teaches Rust via applied-science examples. It combines:
- A multi-chapter MDBook (in the `book/` folder)
- A set of standalone Rust library crates (in `crates/…`)
- A root Cargo workspace (root `Cargo.toml`)
- GitHub Actions workflows to lint, test, build & deploy the book

##### File structure
- Top-level:
- `.github/workflows/` – CI jobs (`lint.yml`, `tests.yml`, `.deploy-book.yml`)
- `book/` – MDBook source (chapters in Markdown; `book.toml` config)
- `crates/` – N independent Rust libraries (e.g. `krr_ndarray`, `poisson_2d`, `ridge_1d_fn`, `simple_optimizers_traits`, etc.), each with its own `Cargo.toml` and `src/`
- `src/lib.rs` – the root workspace’s “virtual” crate (likely only for workspace-level tooling)
- `Justfile` – convenience tasks
- CI config and workspace Cargo files

##### README

a. Main components
1) Developer workstation (writes code & docs)
2) GitHub repository
3) Rust toolchain (cargo build/test, mdbook build)
4) CI/CD (GitHub Actions)
5) MDBook site (static site)
6) Crates.io (optional publish target for libraries)
b. Relationships & interactions
- Developer → Git push → GitHub repo
- GitHub → CI workflows (lint, test crates, build & deploy book)
- CI → Rust toolchain:
– cargo test on each crate
– mdbook build/book → static HTML
- Deploy-book workflow → GitHub Pages (book site)
- (Optionally) crates published to crates.io via cargo publish
c. Architectural patterns & principles
– Monorepo Cargo workspace for versioned crates
– MDBook-driven documentation site co-located with code
– GitHub Actions for automated CI/CD
– Clear separation: one folder per crate, one folder for docs
d. Key technologies/frameworks
– Rust & Cargo (workspace)
– mdBook (Rust-based book generator)
– GitHub Actions (YAML workflows)
– Just (task runner)

##### Detailed guidance
- Crates into a “Rust Libraries” cluster.
- MDBook in a separate “Documentation” cluster.
- CI workflows as three sequential stages (lint → test → build & deploy).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Zone
    subgraph "Developer Workstation" 
        direction TB
        Dev["Developer"]:::dev
    end

    %% Repository Zone
    subgraph "GitHub Repository"
        direction TB
        Repo["GitHub Repo"]:::repo
        README["README.md"]:::metadata
        Contrib["CONTRIBUTING.md"]:::metadata
    end

    %% CI/CD Zone
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        Lint["Lint Workflow"]:::ci
        TestWF["Test Workflow"]:::ci
        DeployBook["Deploy Book Workflow"]:::ci
    end

    %% Toolchain Zone
    subgraph "Rust Toolchain"
        direction TB
        CargoBuild["cargo build/test"]:::tool
        MdbookBuild["mdbook build"]:::tool
        Publish["cargo publish"]:::tool
    end

    %% Crates Cluster
    subgraph "Rust Libraries (crates/)" 
        direction TB
        KN["krr_ndarray"]:::crate
        P2["poisson_2d"]:::crate
        R1F["ridge_1d_fn"]:::crate
        R1G["ridge_1d_generic"]:::crate
        R1N["ridge_1d_ndarray"]:::crate
        R1S["ridge_1d_struct"]:::crate
        SOE["simple_optimizers_enums"]:::crate
        SON["simple_optimizers_ndarray"]:::crate
        SOT["simple_optimizers_traits"]:::crate
    end

    %% Documentation Cluster
    subgraph "Documentation (MDBook)"
        direction TB
        BookCfg["book/book.toml"]:::doc
        BookSrc["book/src/"]:::doc
    end

    %% External Services
    subgraph "Hosting & Registry"
        direction TB
        GHPages["GitHub Pages"]:::external
        CratesIO["crates.io"]:::external
    end

    %% Cargo Workspace Root & Tasks
    subgraph "Workspace Root"
        direction TB
        WS_Cargo["Cargo.toml"]:::tool
        WS_Lib["src/lib.rs"]:::tool
        JustFile["Justfile"]:::tool
    end

    %% Connections
    Dev -->|push| Repo
    Repo -->|trigger| Lint
    Repo -->|trigger| TestWF
    Repo -->|trigger| DeployBook

    Lint -->|runs| CargoBuild
    TestWF -->|runs| CargoBuild
    DeployBook -->|runs| MdbookBuild
    DeployBook -->|runs| Publish

    CargoBuild -->|tests crates| KN
    CargoBuild -->|tests crates| P2
    CargoBuild -->|tests crates| R1F
    CargoBuild -->|tests crates| R1G
    CargoBuild -->|tests crates| R1N
    CargoBuild -->|tests crates| R1S
    CargoBuild -->|tests crates| SOE
    CargoBuild -->|tests crates| SON
    CargoBuild -->|tests crates| SOT

    MdbookBuild -->|build docs| BookCfg
    MdbookBuild -->|build docs| BookSrc

    DeployBook -->|deploy| GHPages
    Publish -->|publish crates| CratesIO

    %% Click Events
    click Lint "https://github.com/bstaber/rustineers/blob/main/.github/workflows/lint.yml"
    click TestWF "https://github.com/bstaber/rustineers/blob/main/.github/workflows/tests.yml"
    click DeployBook "https://github.com/bstaber/rustineers/blob/main/.github/workflows/.deploy-book.yml"
    click BookCfg "https://github.com/bstaber/rustineers/blob/main/book/book.toml"
    click BookSrc "https://github.com/bstaber/rustineers/tree/main/book/src/"
    click KN "https://github.com/bstaber/rustineers/tree/main/crates/krr_ndarray/"
    click P2 "https://github.com/bstaber/rustineers/tree/main/crates/poisson_2d/"
    click R1F "https://github.com/bstaber/rustineers/tree/main/crates/ridge_1d_fn/"
    click R1G "https://github.com/bstaber/rustineers/tree/main/crates/ridge_1d_generic/"
    click R1N "https://github.com/bstaber/rustineers/tree/main/crates/ridge_1d_ndarray/"
    click R1S "https://github.com/bstaber/rustineers/tree/main/crates/ridge_1d_struct/"
    click SOE "https://github.com/bstaber/rustineers/tree/main/crates/simple_optimizers_enums/"
    click SON "https://github.com/bstaber/rustineers/tree/main/crates/simple_optimizers_ndarray/"
    click SOT "https://github.com/bstaber/rustineers/tree/main/crates/simple_optimizers_traits/"
    click WS_Cargo "https://github.com/bstaber/rustineers/blob/main/Cargo.toml"
    click WS_Lib "https://github.com/bstaber/rustineers/blob/main/src/lib.rs"
    click JustFile "https://github.com/bstaber/rustineers/tree/main/Justfile"
    click README "https://github.com/bstaber/rustineers/blob/main/README.md"
    click Contrib "https://github.com/bstaber/rustineers/blob/main/CONTRIBUTING.md"

    %% Styles
    classDef dev fill:#D8BFD8,stroke:#8A2BE2,stroke-width:1px
    classDef repo fill:#E0FFFF,stroke:#00CED1,stroke-width:1px
    classDef metadata fill:#F5F5DC,stroke:#DAA520,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#FF8C00,stroke-width:1px
    classDef tool fill:#ADD8E6,stroke:#1E90FF,stroke-width:1px
    classDef crate fill:#87CEFA,stroke:#4682B4,stroke-width:1px
    classDef doc fill:#90EE90,stroke:#32CD32,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:1px
```
