# schell/moongraph architecture

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

- Interactive diagram: https://gitdiagram.com/schell/moongraph
- Repository: https://github.com/schell/moongraph

## Overview

##### Project Type and Purpose
- Project Type: A Rust library (monorepo) consisting of three interrelated crates for building and scheduling directed acyclic graphs (DAGs).
- Purpose:
- Expose a procedural‐macro API so users write normal Rust functions as graph nodes.
- Automatically construct the DAG by inspecting function inputs/outputs.
- Schedule and run the graph, using the dagga scheduler and broomdog resource manager.
- Optionally parallelize execution with Rayon.

##### File Structure
- Top‐level:
- Cargo.toml, rustfmt.toml, README.md, .github workflows (CI).
- crates/ directory: three crates:
1. moongraph-macros-syntax (procedural‐macro syntax parsing)
2. moongraph-macros (user‐facing derive macros & glue to core)
3. moongraph (core library: DAG builder, scheduler integration, runtime modules)
- Inside core:
- src/lib.rs – high-level API and registration logic
- rayon_impl.rs – parallel execution implementation behind the “parallel” feature
- tutorial_impl.rs – example/tutorial code paths
- CI: GitHub Actions for building/testing on each push.

##### README for Additional Insights
- Two main sub‐systems:
- Scheduler: dagga (external)
- Resource manager: broomdog (external)
- Features:
- “parallel” → turns on Rayon for concurrent node execution.
- Usage: crates are intended to be consumed by other Rust projects (renderling, apecs, etc.).

##### Main Components and Their Relationships
1. moongraph-macros-syntax
2. moongraph-macros
3. moongraph (core library)
4. External dependencies: dagga (scheduler), broomdog (resource manager), rayon (optional parallel engine)
5. CI Workflow (GitHub Actions) – optional, shows build/test pipeline
b. Interactions:
- macros-syntax → produces parsing helpers consumed by macros
- macros → emit registration code that calls into moongraph core API
- moongraph core → builds DAG, invokes dagga & broomdog, optionally rayon_impl
- dagga & broomdog → plugged into core for scheduling & resource management
- rayon_impl (feature gate “parallel”) → provides parallel executor backend to core
c. Architectural Patterns
- Procedural‐macro pipeline: syntax‐crate → macro‐crate → core library
- Plugin‐style dependency injection: external scheduler/resource manager behind traits
- Feature‐flag toggle for parallel execution
d. Key Technologies
- Rust procedural macros (`proc_macro`)
- dagga (DAG scheduler)
- broomdog (resource manager)
- rayon (thread‐parallelism)
- GitHub Actions (CI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1
    Syntax["moongraph-macros-syntax"]:::internal
    %% Layer 2
    Macros["moongraph-macros"]:::internal
    %% Layer 3
    subgraph "moongraph (core library)"
        Core["moongraph"]:::internal
        CoreLib["src/lib.rs"]:::internal
        RayonImpl["rayon_impl.rs"]:::optional
        TutorialImpl["tutorial_impl.rs"]:::internal
        Core --> CoreLib
        Core -->|"[parallel]"| RayonImpl
        Core --> TutorialImpl
    end
    %% Layer 4
    Dagga["dagga (scheduler)"]:::external
    Broomdog["broomdog (resource manager)"]:::external
    RayonDep["rayon (optional engine)"]:::external
    %% Layer 5
    CI["GitHub Actions (CI)"]:::ci

    %% Connections
    Syntax -->|"parses"| Macros
    Macros -->|"generates code"| Core
    Core -->|"invokes scheduler"| Dagga
    Core -->|"uses resource manager"| Broomdog
    Core -->|"[parallel]"| RayonDep
    CI -->|"build/test"| Syntax
    CI -->|"build/test"| Macros
    CI -->|"build/test"| Core

    %% Click Events
    click Syntax "https://github.com/schell/moongraph/tree/main/crates/moongraph-macros-syntax"
    click Syntax "https://github.com/schell/moongraph/blob/main/crates/moongraph-macros-syntax/Cargo.toml"
    click SyntaxLib "https://github.com/schell/moongraph/blob/main/crates/moongraph-macros-syntax/src/lib.rs"
    click Macros "https://github.com/schell/moongraph/tree/main/crates/moongraph-macros"
    click Macros "https://github.com/schell/moongraph/blob/main/crates/moongraph-macros/Cargo.toml"
    click Macros "https://github.com/schell/moongraph/blob/main/crates/moongraph-macros/src/lib.rs"
    click Core "https://github.com/schell/moongraph/tree/main/crates/moongraph"
    click Core "https://github.com/schell/moongraph/blob/main/crates/moongraph/Cargo.toml"
    click CoreLib "https://github.com/schell/moongraph/blob/main/crates/moongraph/src/lib.rs"
    click RayonImpl "https://github.com/schell/moongraph/blob/main/crates/moongraph/src/rayon_impl.rs"
    click TutorialImpl "https://github.com/schell/moongraph/blob/main/crates/moongraph/src/tutorial_impl.rs"
    click CI "https://github.com/schell/moongraph/blob/main/.github/workflows/rust.yml"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef ci fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef optional stroke-dasharray: 5 5,fill:none,stroke:#856404,color:#856404
```
