# moonrepo/moon architecture

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

- Interactive diagram: https://gitdiagram.com/moonrepo/moon
- Repository: https://github.com/moonrepo/moon

## Overview

##### Project type and purpose
- moon is a polyglot monorepo management/orchestration CLI tool (written in Rust) with supplemental JavaScript/TypeScript packages and a documentation website.
- Its core delivers: config loading, project & task graph construction, action pipelines, remote caching, toolchain management, plugins, and notifications.

##### High-level file-structure analysis
Top-level:
- crates/… ⇢ Rust workspace of ~150 crates (config, project-graph, task-graph, action-pipeline, runner, remote, plugin host, toolchain detection, etc.).
- packages/… ⇢ npm/yarn workspaces supplying TypeScript libraries (cli wrappers, runtime, types, report, visualizer).
- website/… ⇢ React/Docusaurus/Vite/Tailwind docs site.
- moon.yml, package.json, Cargo.toml ⇢ workspace manifests.
Patterns: layered Rust libraries compose engine; a small binary crate (crates/cli and crates/app) wires together engine modules. Node packages expose JS APIs & CLI shims. The website is a standalone frontend.

##### Key README insights
- Emphasizes Rust-based performance, incremental adoption, multi-platform support.
- Features align with components: hashing (task-hasher), remote caches (crates/remote), toolchain (crates/toolchain), graphs (crates/project-graph, crates/task-graph), pipelines (crates/action-pipeline), plugins (wasm & crates/plugin), notifications (crates/notifier, git hooks).

a. Main components
– User CLI Frontend:
- Binary (‘moon’): crates/cli + crates/app
– Configuration Layer:
- Config loader & cache: crates/config
– Discovery & Modeling:
- Workspace & project discovery: crates/workspace
- Project graph builder: crates/project-graph
- Task graph builder: crates/task-graph & crates/task-builder
– Execution Orchestration:
- Action pipeline (dependencies + thread-pool): crates/action-pipeline
- Task runner (command execution, caching, hydration): crates/task-runner
– Toolchain & Environment:
- Detect & install toolchains: crates/toolchain + crates/toolchain-plugin
- Env var management: crates/env-var
– Cache & Remote Services:
- Local cache engines: crates/cache, crates/cache-item
- Remote cache client & service (HTTP/gRPC): crates/remote
– Plugin infrastructure:
- WASM plugin host & registry: crates/plugin + wasm/…
– Notifications & Git hooks:
- Notifier & webhooks: crates/notifier
- Git hooks generator: crates/vcs-hooks
– JS/TS API layer (for embedding & wrappers): packages/types, packages/runtime, packages/cli, packages/report, packages/visualizer
– Documentation Website: website/… (React + Docusaurus)

b. Relationships & data flows
1. User invokes `moon` CLI → binary loads config → builds workspace & project graph → builds task graph → action pipeline schedules jobs → task-runner executes (spawns processes with detected toolchains & environment).
2. During execution, runner consults local cache; misses trigger remote client to fetch/push via HTTP or gRPC.
3. Plugins (WASM) can be invoked by pipeline for custom steps.
4. Notifier emits terminal notifications & optional webhooks.
5. JS packages wrap the Rust CLI or expose programmatic APIs.
6. Website is independent, consumes static schemas & MDX, no direct runtime coupling.

c. Architectural patterns & principles
- Layered architecture: Config → Discovery → Graph → Pipeline → Runner
- Modular crates: Each concern (hashing, graph, runner) is its own library crate.
- Plugin architecture: WASM + extension plugin registry
- Micro-services style remote cache (HTTP/gRPC)
- Language-platform abstraction: toolchain detection, environment isolation
- Separation of concerns: Rust engine vs JS wrapper vs website

d. Notable technologies
– Rust (tokio, serde, prost for gRPC)
– WASM for plugins
– Node.js / TypeScript / Yarn 4 (CLI shim & runtime packages)
– React + Docusaurus + Tailwind for website
– CI workflows: GitHub Actions, Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User CLI Frontend
    CLI["User CLI Frontend (moon)"]:::rust
    CLI -->|loads config| ConfigLoader

    subgraph "Rust Engine"
        style RustEngine fill:none,stroke:none

        subgraph "Config Layer"
            ConfigLoader["Config Loader"]:::rust
            ConfigCache["Config Cache"]:::rust
        end

        subgraph "Discovery & Modeling"
            WorkspaceBuilder["Workspace Builder"]:::rust
            ProjectsLocator["Projects Locator"]:::rust
            ProjectGraph["Project Graph Builder"]:::rust
            TaskGraph["Task Graph Builder"]:::rust
            TaskDepsBuilder["Task Deps Builder"]:::rust
        end

        subgraph "Execution Orchestration"
            ActionPipeline["Action Pipeline"]:::rust
            JobDispatcher["Job Dispatcher"]:::rust
            TaskRunner["Task Runner"]:::rust
            CommandExecutor["Command Executor"]:::rust
            OutputArchiver["Output Archiver"]:::rust
            OutputHydrater["Output Hydrater"]:::rust
        end

        subgraph "Toolchain & Environment"
            ToolchainDetect["Toolchain Detect"]:::rust
            RuntimeManager["Runtime Manager"]:::rust
            EnvScanner["Env Scanner"]:::rust
            GlobalEnvBag["Global Env Bag"]:::rust
        end

        subgraph "Cache & Remote Services"
            CacheEngine["Local Cache Engine"]:::rust
            CacheItem["Cache Item"]:::rust
            HTTPRemote["HTTP Remote Client"]:::rust
            GRPCRemote["gRPC Remote Client"]:::rust
            RemoteService["Remote Service"]:::rust
        end

        subgraph "Plugin Infrastructure"
            PluginHost["WASM Plugin Host"]:::rust
            PluginRegistry["Plugin Registry"]:::rust
        end

        subgraph "Notifications & Git Hooks"
            Notifier["Notifier"]:::rust
            Webhooks["Webhooks"]:::rust
            HooksGenerator["Git Hooks Generator"]:::rust
        end
    end

    %% JS/TS Packages
    subgraph "JS/TS API Layer" 
        style JSLayer fill:none,stroke:none
        JSPkgCLI["packages/cli"]:::js
        JSPkgRuntime["packages/runtime"]:::js
        JSPkgTypes["packages/types"]:::js
        JSPkgReport["packages/report"]:::js
        JSPkgVisualizer["packages/visualizer"]:::js
    end

    %% Documentation Website
    subgraph "Documentation Website"
        DocsSite["Docs Website"]:::web
    end

    %% Flows
    ConfigLoader -->|discovers| WorkspaceBuilder
    WorkspaceBuilder --> ProjectsLocator
    ProjectsLocator --> ProjectGraph
    ProjectGraph --> TaskGraph
    TaskGraph --> TaskDepsBuilder
    TaskDepsBuilder --> ActionPipeline
    ActionPipeline --> JobDispatcher
    JobDispatcher --> TaskRunner
    TaskRunner --> CommandExecutor
    CommandExecutor -->|executes external| ExecProc["External Process"]:::ext
    TaskRunner --> OutputArchiver
    TaskRunner --> OutputHydrater
    ActionPipeline --> PluginHost
    PluginHost --> PluginRegistry
    TaskRunner -->|checks| CacheEngine
    CacheEngine --> CacheItem
    TaskRunner -->|fetch/push| HTTPRemote
    TaskRunner -->|fetch/push| GRPCRemote
    HTTPRemote --> RemoteService
    GRPCRemote --> RemoteService
    ActionPipeline --> Notifier
    TaskRunner --> Notifier
    Notifier --> Webhooks
    Webhooks --> HooksGenerator

    CLI -->|uses| JSPkgCLI
    CLI -->|uses| JSPkgRuntime
    CLI -->|uses| JSPkgTypes
    CLI -->|uses| JSPkgReport
    CLI -->|uses| JSPkgVisualizer

    %% Click Events
    click CLI "https://github.com/moonrepo/moon/blob/master/crates/cli/src/main.rs"
    click CLI "https://github.com/moonrepo/moon/blob/master/crates/app/src/app.rs"
    click ConfigLoader "https://github.com/moonrepo/moon/blob/master/crates/config/src/config_loader.rs"
    click ConfigCache "https://github.com/moonrepo/moon/blob/master/crates/config/src/config_cache.rs"
    click WorkspaceBuilder "https://github.com/moonrepo/moon/blob/master/crates/workspace/src/workspace_builder.rs"
    click ProjectsLocator "https://github.com/moonrepo/moon/blob/master/crates/workspace/src/projects_locator.rs"
    click ProjectGraph "https://github.com/moonrepo/moon/blob/master/crates/project-graph/src/project_graph.rs"
    click TaskGraph "https://github.com/moonrepo/moon/blob/master/crates/task-graph/src/task_graph.rs"
    click TaskDepsBuilder "https://github.com/moonrepo/moon/blob/master/crates/task-builder/src/task_deps_builder.rs"
    click TaskDepsBuilder "https://github.com/moonrepo/moon/blob/master/crates/task-builder/src/tasks_builder.rs"
    click ActionPipeline "https://github.com/moonrepo/moon/blob/master/crates/action-pipeline/src/action_pipeline.rs"
    click JobDispatcher "https://github.com/moonrepo/moon/blob/master/crates/action-pipeline/src/job_dispatcher.rs"
    click Notifier "https://github.com/moonrepo/moon/blob/master/crates/action-pipeline/src/subscribers/notifications_subscriber.rs"
    click TaskRunner "https://github.com/moonrepo/moon/blob/master/crates/task-runner/src/task_runner.rs"
    click CommandExecutor "https://github.com/moonrepo/moon/blob/master/crates/task-runner/src/command_executor.rs"
    click OutputArchiver "https://github.com/moonrepo/moon/blob/master/crates/task-runner/src/output_archiver.rs"
    click OutputHydrater "https://github.com/moonrepo/moon/blob/master/crates/task-runner/src/output_hydrater.rs"
    click ToolchainDetect "https://github.com/moonrepo/moon/blob/master/crates/toolchain/src/detect/project_toolchain.rs"
    click RuntimeManager "https://github.com/moonrepo/moon/blob/master/crates/toolchain/src/runtime.rs"
    click PluginHost "https://github.com/moonrepo/moon/blob/master/crates/plugin/src/host.rs"
    click PluginRegistry "https://github.com/moonrepo/moon/blob/master/crates/plugin/src/plugin_registry.rs"
    click HTTPRemote "https://github.com/moonrepo/moon/blob/master/crates/remote/src/http_remote_client.rs"
    click GRPCRemote "https://github.com/moonrepo/moon/blob/master/crates/remote/src/grpc_remote_client.rs"
    click RemoteService "https://github.com/moonrepo/moon/blob/master/crates/remote/src/remote_service.rs"
    click EnvScanner "https://github.com/moonrepo/moon/blob/master/crates/env-var/src/env_scanner.rs"
    click GlobalEnvBag "https://github.com/moonrepo/moon/blob/master/crates/env-var/src/global_bag.rs"
    click CacheEngine "https://github.com/moonrepo/moon/blob/master/crates/cache/src/cache_engine.rs"
    click CacheItem "https://github.com/moonrepo/moon/blob/master/crates/cache-item/src/cache_item.rs"
    click Webhooks "https://github.com/moonrepo/moon/blob/master/crates/notifier/src/webhooks.rs"
    click Notifier "https://github.com/moonrepo/moon/blob/master/crates/notifier/src/notifications.rs"
    click HooksGenerator "https://github.com/moonrepo/moon/blob/master/crates/vcs-hooks/src/hooks_generator.rs"
    click JSPkgCLI "https://github.com/moonrepo/moon/blob/master/packages/cli/moon.js"
    click JSPkgRuntime "https://github.com/moonrepo/moon/blob/master/packages/runtime/src/index.ts"
    click JSPkgTypes "https://github.com/moonrepo/moon/blob/master/packages/types/src/index.ts"
    click JSPkgReport "https://github.com/moonrepo/moon/blob/master/packages/report/src/report.ts"
    click JSPkgVisualizer "https://github.com/moonrepo/moon/blob/master/packages/visualizer/src/app.tsx"
    click DocsSite "https://github.com/moonrepo/moon/tree/master/website/src/components/Docs/"

    %% Styles
    classDef rust fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef js fill:#90EE90,stroke:#000,stroke-width:1px
    classDef web fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#000,stroke-width:1px
```
