# ruvnet/sparc architecture

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

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

## Overview

##### Project type and purpose
- This is a multi‐component, full-stack developer toolkit.
- A Python-based CLI framework (“sparc_cli”) that implements the SPARC methodology.
- A Next.js/React web UI (“ui” folder) exposing parts of the CLI functionality via serverless API routes.
- Docker/Docker-Compose orchestrates both for development and deployment.
- Purpose: Guide AI-assisted software development through the SPARC process (Specification → Pseudocode → Architecture → Refinement → Completion), integrating LLM providers, symbolic reasoning, and optional UI interactions.

##### File structure
- Top-level directories:
- configuration, docs, specification, example, tests – project documentation, conventions, and references.
- sparc_cli – core Python package: entrypoint (`__main__.py`), modules (`agent_utils.py`, `tools/`, `console/`, `prompts.py`, etc.), docs, examples, scripts, tests.
- ui – Next.js app: `app/` pages & API routes, `components/`, `lib/` utilities, sandbox templates.
- Key files:
- `docker-compose.yml` & `Dockerfile` – container definitions for CLI and UI services.
- `pyproject.toml`, `requirements-dev.txt` – Python dependencies.
- UI config: `next.config.js`, `package.json`, Tailwind settings.
- CI workflows under `.github/workflows` for Python packaging and testing.

##### README for architecture insights
- Describes tool-system within CLI: file tools, directory tools, shell tool, memory tool, expert/research tools, web scraping (Scape).
- External dependencies: LLM providers (Anthropic, OpenAI, OpenRouter), Playwright/HTTPX for scraping.

##### Diagramming recommendations
- CLI → LLM Providers (HTTP calls)
- UI API → sparc_cli core functions or directly to Providers
- UI ← Browser (HTTPS)
- Backend modules (green), Frontend components (blue), External services (gray), Infrastructure (orange).

##### Capturing essential elements
- Don’t omit the tool registry inside CLI or API route layer in UI.
- Orchestration (Docker-Compose) and CI pipelines as part of ops overview.
- Detail environment/config component to show where API keys and configurations flow in.
- Example DB usage only if illustrating demo or sandbox workflows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Environment Configuration
    Env["Configuration & Environment (.env)"]:::infra

    %% Orchestration
    DockerCompose["Docker-Compose Orchestrator"]:::infra
    DockerCompose -->|manages| CLI
    DockerCompose -->|manages| UI

    %% CLI Backend Service
    subgraph "CLI Backend Service" 
        CLI["sparc_cli Python Service"]:::backend
        CLI --> CoreModules
        CLI --> ToolRegistry
        CLI --> ConsoleOutput
        CLI --> ConfigEnv
    end

    subgraph "Core SPARC Engine Modules" 
        CoreModules["Core Modules"]:::backend
        CoreModules --> AgentUtils
        CoreModules --> LLMModule
        CoreModules --> ConfigModule
        CoreModules --> PromptsModule
        CoreModules --> NonInteractive
        CoreModules --> Polaris
    end

    subgraph "Tool Registry" 
        ToolRegistry["sparc_cli/tools"]:::backend
        ToolRegistry --> AgentTool
        ToolRegistry --> ReadFile
        ToolRegistry --> WriteFile
        ToolRegistry --> FuzzyFind
        ToolRegistry --> ShellTool
        ToolRegistry --> MemoryTool
        ToolRegistry --> ExpertTool
        ToolRegistry --> ResearchTool
        ToolRegistry --> ScapeTool
        ToolRegistry --> MathTools
    end

    subgraph "Console Output" 
        ConsoleOutput["sparc_cli/console"]:::backend
    end

    ConfigEnv["Configuration Modules"]:::backend

    %% UI Frontend Service
    subgraph "Web Frontend Service" 
        UI["Next.js UI Service"]:::frontend
        UI --> UI_App
        UI --> UI_API
        UI --> UI_Components
        UI --> UI_Lib
        UI --> UI_Sandbox
    end

    subgraph "App Router" 
        UI_App["ui/app"]:::frontend
        UI_App --> Layout
        UI_App --> Page
        UI_App --> Providers
    end

    subgraph "API Routes" 
        UI_API["ui/app/api"]:::frontend
        UI_API --> ChatRoute
        UI_API --> ResearchRoute
        UI_API --> SandboxRoute
        UI_API --> ChatDirect
        UI_API --> ChatO1
        UI_API --> ResearchChat
        UI_API --> AnthropicRoute
        ChatRoute -->|invokes| CLI
        ResearchRoute -->|invokes| CLI
        SandboxRoute -->|invokes| CLI
    end

    subgraph "React Components" 
        UI_Components["ui/components"]:::frontend
    end

    subgraph "Client Utilities" 
        UI_Lib["ui/lib"]:::frontend
    end

    subgraph "Sandbox Templates" 
        UI_Sandbox["ui/sandbox-templates"]:::frontend
    end

    Browser["User Browser"]:::external
    Browser -->|HTTPS| UI_App

    %% External Services
    subgraph "External Services" 
        LLM["LLM Providers"]:::external
        Scraping["Web Scraping Engines"]:::external
        DB["Optional SQLite DB"]:::external
    end

    CLI -->|HTTP| LLM
    CLI -->|uses| Scraping
    UI -->|HTTP| LLM

    %% Shared File System
    CLI -.->|Shared FS| UI

    %% CI/CD & DevOps
    CI_CD["CI/CD Pipelines"]:::ops
    CI_CD -->|triggers| DockerCompose
    CI_CD --> CLI
    CI_CD --> UI

    %% Environment connections
    Env --> CLI
    Env --> UI

    %% Click Events for CLI
    click sparc_cli_dir "https://github.com/ruvnet/sparc/tree/main/sparc_cli/"
    click cli_entrypoint "https://github.com/ruvnet/sparc/blob/main/sparc_cli/__main__.py"
    click AgentUtils "https://github.com/ruvnet/sparc/blob/main/sparc_cli/agent_utils.py"
    click LLMModule "https://github.com/ruvnet/sparc/blob/main/sparc_cli/llm.py"
    click ConfigModule "https://github.com/ruvnet/sparc/blob/main/sparc_cli/config.py"
    click PromptsModule "https://github.com/ruvnet/sparc/blob/main/sparc_cli/prompts.py"
    click NonInteractive "https://github.com/ruvnet/sparc/blob/main/sparc_cli/non_interactive.py"
    click Polaris "https://github.com/ruvnet/sparc/blob/main/sparc_cli/polaris.py"
    click ToolRegistry "https://github.com/ruvnet/sparc/tree/main/sparc_cli/tools/"
    click AgentTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/agent.py"
    click ReadFile "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/read_file.py"
    click WriteFile "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/write_file.py"
    click FuzzyFind "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/fuzzy_find.py"
    click ShellTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/shell.py"
    click MemoryTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/memory.py"
    click ExpertTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/expert.py"
    click ResearchTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/research.py"
    click ScapeTool "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tools/scape.py"
    click MathTools "https://github.com/ruvnet/sparc/tree/main/sparc_cli/tools/math/"
    click ConsoleOutput "https://github.com/ruvnet/sparc/tree/main/sparc_cli/console/"
    click ConfigEnv "https://github.com/ruvnet/sparc/blob/main/sparc_cli/env.py"
    click ToolConfigs "https://github.com/ruvnet/sparc/blob/main/sparc_cli/tool_configs.py"

    %% Click Events for UI
    click ui_dir "https://github.com/ruvnet/sparc/tree/main/ui/"
    click Layout "https://github.com/ruvnet/sparc/blob/main/ui/app/layout.tsx"
    click Page "https://github.com/ruvnet/sparc/blob/main/ui/app/page.tsx"
    click Providers "https://github.com/ruvnet/sparc/blob/main/ui/app/providers.tsx"
    click ChatRoute "https://github.com/ruvnet/sparc/blob/main/ui/app/api/chat/route.ts"
    click ResearchRoute "https://github.com/ruvnet/sparc/blob/main/ui/app/api/research/route.ts"
    click SandboxRoute "https://github.com/ruvnet/sparc/blob/main/ui/app/api/sandbox/route.ts"
    click ChatDirect "https://github.com/ruvnet/sparc/blob/main/ui/app/api/chat-direct/route.ts"
    click ChatO1 "https://github.com/ruvnet/sparc/blob/main/ui/app/api/chat-o1/route.ts"
    click ResearchChat "https://github.com/ruvnet/sparc/blob/main/ui/app/api/research-chat/route.ts"
    click AnthropicRoute "https://github.com/ruvnet/sparc/blob/main/ui/app/api/anthropic/route.ts"
    click UI_Components "https://github.com/ruvnet/sparc/tree/main/ui/components/"
    click UI_Lib "https://github.com/ruvnet/sparc/tree/main/ui/lib/"
    click UI_Sandbox "https://github.com/ruvnet/sparc/tree/main/ui/sandbox-templates/"

    %% Click Events for Orchestration
    click DockerCompose "https://github.com/ruvnet/sparc/blob/main/docker-compose.yml"
    click RootDockerfile "https://github.com/ruvnet/sparc/tree/main/Dockerfile"
    click CLIDockerfile "https://github.com/ruvnet/sparc/tree/main/sparc_cli/Dockerfile"
    click EnvTemplate "https://github.com/ruvnet/sparc/blob/main/ui/.env.template"
    click SampleEnv "https://github.com/ruvnet/sparc/blob/main/sample.env"

    %% Click Events for CI/CD
    click CI_workflow "https://github.com/ruvnet/sparc/blob/main/ .github/workflows/ci.yml"
    click PythonPkg "https://github.com/ruvnet/sparc/blob/main/ .github/workflows/python-package.yml"
    click CLI_Pkg "https://github.com/ruvnet/sparc/blob/main/sparc_cli/.github/workflows/python-package.yml"

    %% Styles
    classDef backend fill:#e0f7e9,stroke:#3ba776,color:#034d29;
    classDef frontend fill:#e3f2fd,stroke:#1e88e5,color:#0d47a1;
    classDef infra fill:#fff3e0,stroke:#fb8c00,color:#e65100;
    classDef external fill:#eceff1,stroke:#607d8b,color:#263238;
    classDef ops fill:#f3e5f5,stroke:#ab47bc,color:#4a148c;
```
