# ruvnet/ruv-dev architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source, Node.js-based CLI scaffolding tool.
- It generates SPARC-methodology projects, AIGI frameworks, or minimal Roo-mode frameworks.
- It also provides an interactive “MCP Wizard” for configuring external services.

1. User → CLI Entry Point (“runs `npx create-sparc ...`”)
2. CLI Entry → Command Parser → Selected Command Module
3. Command Module → Core Modules (ProjectGenerator, MCPWizard, etc.)
4. Core Modules ↔ Template Store (read templates)
5. Core Modules → FileManager → Output Files & `.roo` / `.roomodes`
6. MCPWizard → RegistryClient → External MCP Registry API
7. MCPWizard → External MCP Servers (via shell commands and environment variables)

##### Architectural Patterns & Design Principles
- Layered Architecture: Presentation (CLI), Application (commands), Domain (core modules), Infrastructure (FS, network).
- Command Pattern: each CLI command encapsulated in its own handler.
- Adapter/Client Pattern: RegistryClient adapts calls to external MCP registry.
- Template-Driven Scaffolding: separation of templates from code logic.
- Single Responsibility & Separation of Concerns: each core module has a distinct role.
- Configuration-as-Data: all service integrations driven by JSON (`mcp.json`, `roomodes`).

##### Technologies & Frameworks to Annotate
- Node.js + JavaScript (TypeScript optional)
- CLI parsing library (e.g., yargs or commander)
- Jest for tests (`__tests__` folder)
- JSON schemas for config validation
- Symlink support via Node’s `fs` module
- Shell invocation (`child_process`) for MCP servers
- Templates managed in plain Markdown / code files

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    User(["User / Developer"]):::actor
    CLIEntry["CLI Entry Point\nbin/index.js"]:::cli
    CommandParser["Command Parser\nsrc/cli/index.js"]:::cli

    User -->|"runs npx create-sparc"| CLIEntry
    CLIEntry -->|"parses commands"| CommandParser

    subgraph "CLI Commands"
        direction TB
        InitCommand["init Command\nsrc/cli/commands/init.js"]:::cliCmd
        AigiCommand["aigi init Command\nsrc/cli/commands/aigi.js"]:::cliCmd
        MinimalCommand["minimal init Command\nsrc/cli/commands/minimal.js"]:::cliCmd
        ConfigMCP["configure-mcp Command\nsrc/cli/commands/configure-mcp.js"]:::cliCmd
        WizardCmd["wizard Command\nsrc/cli/commands/wizard.js"]:::cliCmd
        HelpCmd["help Command\nsrc/cli/commands/help.js"]:::cliCmd
    end

    CommandParser --> InitCommand
    CommandParser --> AigiCommand
    CommandParser --> MinimalCommand
    CommandParser --> ConfigMCP
    CommandParser --> WizardCmd
    CommandParser --> HelpCmd

    %% Domain Services
    subgraph "Core Modules"
        direction TB
        ProjectGenerator["ProjectGenerator\nsrc/core/project-generator/index.js"]:::core
        MCPWizard["MCPWizard\nsrc/core/mcp-wizard/index.js"]:::core
        subgraph "Config Generator"
            ConfigGen["ConfigGenerator\nsrc/core/mcp-wizard/config-generator/index.js"]:::core
            MCPTemplates["MCP Templates\nsrc/core/mcp-wizard/config-generator/templates.js"]:::infra
        end
        WizardCore["WizardCore Logic\nsrc/core/mcp-wizard/wizard-core.js"]:::core
        MCPValidation["MCP Validation\nsrc/core/mcp-wizard/validation.js"]:::core
        MCPSecurity["MCP Security\nsrc/core/mcp-wizard/security.js"]:::core
        RegistryClient["RegistryClient\nsrc/core/registry-client/registry-client.js"]:::core
        MockRegistry["Mock RegistryClient\nsrc/core/registry-client/mock-registry-client.js"]:::core
        RegistryModels["Registry Models\nsrc/core/registry-client/models.js"]:::core
        RegistryError["Registry Errors\nsrc/core/registry-client/registry-error.js"]:::core
        ConfigManager["ConfigManager\nsrc/core/config-manager/index.js"]:::core
        ConfigSchema["Config Schema\nsrc/core/config-manager/schema.js"]:::core
        FileManager["FileManager\nsrc/core/file-manager/index.js"]:::core
        Symlink["SymlinkManager\nsrc/core/file-manager/symlink.js"]:::core
        SecurityModule["SecurityModule\naudit-security.js"]:::core
    end

    InitCommand --> ProjectGenerator
    AigiCommand --> ProjectGenerator
    MinimalCommand --> ProjectGenerator
    ConfigMCP --> MCPWizard
    WizardCmd --> MCPWizard
    HelpCmd --> ConfigManager

    MCPWizard --> ConfigGen
    ConfigGen --> MCPTemplates
    MCPWizard --> WizardCore
    MCPWizard --> MCPValidation
    MCPWizard --> MCPSecurity
    MCPWizard --> RegistryClient
    RegistryClient --> RegistryModels
    RegistryClient --> RegistryError
    MCPWizard --->|"optional verify"| MockRegistry

    ProjectGenerator --- TemplatesDir
    MCPTemplates --- TemplatesDir

    ProjectGenerator --> FileManager
    FileManager --> Symlink
    FileManager -->|"writes"| RooConfig
    FileManager -->|"writes"| RooList
    FileManager -->|"writes"| Roomodes
    MCPSecurity -.-> ConfigGen
    MCPValidation -.-> ConfigGen

    %% Template Store
    subgraph "Template Store"
        TemplatesDir["templates/"]:::infra
        MinimalTemplates["templates/minimal-roo/"]:::infra
    end

    %% Outputs
    subgraph "Output & Config Files"
        RooConfig[".roo/mcp.json"]:::data
        RooList[".roo/mcp-list.txt"]:::data
        Roomodes[".roomodes"]:::data
    end

    %% External Systems
    subgraph "External MCP Services"
        direction TB
        MCPServers["MCP Servers\n(supabase, openai, aws, etc.)"]:::external
        Shell["Shell/NPM\ngit init, npx"]:::external
        Secrets["Env Vars / Secrets"]:::external
    end

    MCPWizard -->|"queries"| MCPServers
    MCPWizard -->|"shell cmd"| Shell
    MCPWizard -->|"uses"| Secrets

    %% Click events
    click CLIEntry "https://github.com/ruvnet/ruv-dev/blob/main/bin/index.js"
    click CommandParser "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/index.js"
    click InitCommand "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/init.js"
    click AigiCommand "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/aigi.js"
    click MinimalCommand "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/minimal.js"
    click ConfigMCP "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/configure-mcp.js"
    click WizardCmd "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/wizard.js"
    click HelpCmd "https://github.com/ruvnet/ruv-dev/blob/main/src/cli/commands/help.js"
    click ProjectGenerator "https://github.com/ruvnet/ruv-dev/blob/main/src/core/project-generator/index.js"
    click MCPWizard "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/index.js"
    click ConfigGen "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/config-generator/index.js"
    click MCPTemplates "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/config-generator/templates.js"
    click WizardCore "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/wizard-core.js"
    click MCPValidation "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/validation.js"
    click MCPSecurity "https://github.com/ruvnet/ruv-dev/blob/main/src/core/mcp-wizard/security.js"
    click RegistryClient "https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/registry-client.js"
    click MockRegistry "https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/mock-registry-client.js"
    click RegistryModels "https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/models.js"
    click RegistryError "https://github.com/ruvnet/ruv-dev/blob/main/src/core/registry-client/registry-error.js"
    click ConfigManager "https://github.com/ruvnet/ruv-dev/blob/main/src/core/config-manager/index.js"
    click ConfigSchema "https://github.com/ruvnet/ruv-dev/blob/main/src/core/config-manager/schema.js"
    click FileManager "https://github.com/ruvnet/ruv-dev/blob/main/src/core/file-manager/index.js"
    click Symlink "https://github.com/ruvnet/ruv-dev/blob/main/src/core/file-manager/symlink.js"
    click TemplatesDir "https://github.com/ruvnet/ruv-dev/tree/main/templates/"
    click MinimalTemplates "https://github.com/ruvnet/ruv-dev/tree/main/templates/minimal-roo/"
    click RooConfig "https://github.com/ruvnet/ruv-dev/blob/main/.roo/mcp.json"
    click RooList "https://github.com/ruvnet/ruv-dev/blob/main/.roo/mcp-list.txt"
    click Roomodes "https://github.com/ruvnet/ruv-dev/blob/main/.roomodes"

    %% Styles
    classDef actor fill:#eef,stroke:#333,stroke-width:1px
    classDef cli fill:#cce5ff,stroke:#2a6496,stroke-width:1px
    classDef cliCmd fill:#99ccff,stroke:#2a6496,stroke-width:1px,stroke-dasharray: 5 5
    classDef core fill:#d4edda,stroke:#3c763d,stroke-width:1px
    classDef infra fill:#fff3cd,stroke:#8a6d3b,stroke-width:1px
    classDef data fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
