How ruvnet/sparc works
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.