# ruvnet/sparc-ide architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/sparc-ide
- Repository: https://github.com/ruvnet/sparc-ide

## Overview

##### Project Type and Purpose
- SPARC IDE is a desktop IDE distribution (Electron/VSCodium-based) customized for AI-native, prompt-driven development. It bundles:
- The VSCodium core UI
- Roo Code extension for AI workflows
- SPARC-specific extensions and themes
- Packaging for Linux, macOS, Windows
- CI/build/test infrastructure
- Secure AI service integration (MCP server & external AI APIs)

##### File Structure
- Top-level directories designate major subsystems:
- /src: extension code, configs, templates
- /scripts: build, packaging, setup, verification
- /package: final installers, manifests, security reports
- /extensions: Roo Code VSIX and signature assets
- /tests & /test-reports: automated test suites & outputs
- /.roo: rules library for the Roo Code agent framework
- Configuration files (package/manifest.json, src/config/*.json) drive packaging and runtime behavior.
- Build artifacts are produced under /dist or /package.

##### README for Additional Insights
- Architecture overview lives in docs/1_architecture_overview.md.
- SPARC methodology phases correlate to templates in src/sparc-workflow/templates.
- Dependencies: Node.js, Yarn, Electron/VSCodium, external AI endpoints, MCP server.

1. VSCodium Core (Electron UI + Editor API)
2. SPARC IDE Extension Suite:
– Roo Code Extension
– SPARC Workflow Extension (phase templates, UI commands)
– Theme & Keybindings Module
3. Configuration Manager (loads src/config/*.json)
4. AI Integration Layer:
– MCP Client (Model Context Protocol client library)
– AI Service Connectors (OpenRouter, Claude, GPT-4, Gemini)
– Secure Key Store (encrypted env var manager)
5. Packaging & Distribution:
– Build Scripts (scripts/*.sh, .ps1, .bat)
– Platform Installers (DEB, RPM, DMG, EXE, NSIS)
– Extension Verification (public key + signature)
6. CI/Test Infrastructure:
– Automated Tests (tests/*)
– Reporting (test-reports/)
7. External Services:
– MCP Server (HTTPS API)
– AI Model Endpoints

- User invokes SPARC commands in VSCode → Extension Suite
- Extension Suite reads/writes via Configuration Manager
- When AI features are used → AI Integration Layer → MCP Server → External AI Models
- Packaging Scripts consume build artifacts from Extension Suite & Branding → produce installers
- CI/Test Infrastructure triggers scripts and reports back status

c. Architectural Patterns & Principles:
- Plugin Architecture (VSCode extension host)
- Layered Separation (UI layer, Extension logic, Integration layer, Packaging layer)
- Secure-by-design (encrypted key store, signature verification)
- Cross-Platform Packaging Abstraction

d. Key Technologies & Frameworks:
- Electron / VSCodium
- Node.js & Yarn
- VSCode Extension API (TypeScript/JavaScript)
- Shell scripts, PowerShell, NSIS
- HTTPS / REST (MCP, AI services)
- JSON-based configuration & manifest files

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI & Extension Layer"
        VSC["VSCodium Core"]:::ui
        Roo["Roo Code Extension"]:::ui
        WF["SPARC Workflow Extension"]:::ui
        TH["Theme & Keybindings Module"]:::ui
        ConfigMgr["Configuration Manager"]:::config
    end

    subgraph "AI Integration Layer"
        MCP["MCP Client"]:::integration
        Connectors["AI Service Connectors"]:::integration
        KeyStore["Secure Key Store"]:::integration
    end

    subgraph "Packaging & Distribution"
        BuildScripts["Build & Packaging Scripts"]:::pack
        Installers["Platform Installers"]:::pack
        Verify["Extension Verification"]:::pack
        Manifest["Global Manifest"]:::pack
    end

    subgraph "CI/Test Infrastructure"
        Tests["Automated Tests"]:::ci
        Reports["Test Reports"]:::ci
    end

    subgraph "External Services"
        MCPServer["MCP Server"]:::external
        AIModels["External AI Model Endpoints"]:::external
    end

    User["User"]:::external --> VSC
    VSC --> Roo
    VSC --> WF
    VSC --> TH
    Roo --> ConfigMgr
    WF --> ConfigMgr
    TH --> ConfigMgr
    Roo --> MCP
    WF --> MCP
    ConfigMgr --> MCP
    MCP --> MCPServer
    MCPServer --> AIModels
    BuildScripts --> Installers
    Roo --> Verify
    Verify --> Installers
    BuildScripts --> Manifest
    Tests --> BuildScripts
    Tests --> Verify
    Tests --> Installers
    Tests --> Reports

    click VSC "https://github.com/ruvnet/sparc-ide/tree/main/vscodium/"
    click Roo "https://github.com/ruvnet/sparc-ide/blob/main/extensions/roo-code.vsix"
    click Verify "https://github.com/ruvnet/sparc-ide/blob/main/extensions/verification/verification-record.json"
    click WF "https://github.com/ruvnet/sparc-ide/tree/main/src/sparc-workflow/"
    click TH "https://github.com/ruvnet/sparc-ide/blob/main/src/themes/dracula-pro.json"
    click ConfigMgr "https://github.com/ruvnet/sparc-ide/blob/main/src/config/settings.json"
    click MCP "https://github.com/ruvnet/sparc-ide/blob/main/.roo/mcp.json"
    click KeyStore "https://github.com/ruvnet/sparc-ide/blob/main/.env.example"
    click BuildScripts "https://github.com/ruvnet/sparc-ide/blob/main/scripts/build-sparc-ide.sh"
    click Installers "https://github.com/ruvnet/sparc-ide/blob/main/package/windows/SPARC-IDE-1.0.0-windows-x64.exe"
    click Tests "https://github.com/ruvnet/sparc-ide/tree/main/tests/"
    click Reports "https://github.com/ruvnet/sparc-ide/blob/main/test-reports/test_report_1.html"

    classDef ui fill:#B3CDED,stroke:#2E6AB1,color:#000
    classDef integration fill:#CDE8CD,stroke:#2E8B57,color:#000
    classDef pack fill:#FDD9B5,stroke:#E67E22,color:#000
    classDef config fill:#FFF2B2,stroke:#D4A017,color:#000
    classDef ci fill:#E5D0F3,stroke:#8E44AD,color:#000
    classDef external fill:#D3D3D3,stroke:#696969,color:#000
```
