# sweepai/sweep architecture

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

- Interactive diagram: https://gitdiagram.com/sweepai/sweep
- Repository: https://github.com/sweepai/sweep

## Overview

##### Project Type and Purpose
- Sweep is a multi-component AI coding assistant. It provides:
- A core Python library (`sweepai/`) implementing agents, handlers, CLI commands, and a lightweight web API for GitHub events and health checks.
- A Next.js-based frontend (`sweep_chat/`) for interactive chat in the browser.
- A published JetBrains plugin that wraps these services for in-IDE assistance.
- Documentation and SDK layers under `docs/` and `docs/sdk/`.

##### Top-Level Architecture Components
a. Core Python Service
- `sweepai/cli.py`: Command-line interface entry point.
- `sweepai/web/health.py`, `sweepai/web/events.py`: FastAPI (or similar) endpoints for GitHub webhooks and health checks.
- `sweepai/handlers/`: Event handlers for GitHub events (PR comments, merges, checks).
- `sweepai/core/`, `sweepai/agents/`: Agent logic, prompt orchestration, context pruning, vector DB integration (`sweepai/core/vector_db.py`).
- `sweepai/utils/`: Shared utilities (OpenAI, Anthropic, GitHub clients, streaming, logging).
- External dependencies: OpenAI API, Anthropic API, Cohere, JIRA, Redis vector store.

b. Frontend Chat UI
- `sweep_chat/`: Next.js app
- `app/` folder: Routes for chat pages and API proxies (`app/api/auth`, etc.).
- `components/`: UI primitives, chat components, code editors, loaders.
- `lib/`: Shared authentication, streaming helpers, constants.
- `public/`: Static assets.
- E2E test harness: Cypress configuration under `sweep_chat/cypress/`.
- Authentication: NextAuth integration for user sessions.

c. Documentation and SDK
- `docs/`: Static site files (MDX) and React components to power the documentation portal.
- `docs/sdk/`: A Python SDK publishing wrapper over core services (PyPI packaging).

d. Deployment and Operations
- Dockerfile + docker-compose.yml
- `bin/` scripts for install, deploy, redeploy on server.
- GitHub Actions workflows for testing, linting, and PyPI publishing.

##### Relationships & Data Flow
- The JetBrains plugin and CLI both call the core Python service (via HTTP or direct imports) to process requests.
- The core service:
1. Receives a request (CLI command or GitHub webhook).
2. The handler selects an agent, constructs prompts, consults the vector DB, and invokes LLM APIs.
3. Returns suggestions or posts comments back to GitHub via its API.
- The Next.js frontend communicates with the core service through REST or WebSocket endpoints (streaming code suggestions).
- Redis (vector_db) sits alongside the core service for embedding storage and retrieval.

##### Architectural Patterns & Principles
- Modular layering: CLI, handlers, core logic, utilities all separated by responsibility.
- Event-driven design: GitHub webhooks → handlers → agents.
- Adapter pattern for LLM providers (`openai_proxy`, `anthropic_client`, `cohere_utils`).
- Single-page application for UI, decoupled from backend.
- Dockerized micro-deployments.

- Rounded rectangles for services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Python Service
    subgraph "Core Python Service"
        direction TB
        CLI["CLI Tool"]:::internal
        Health["Health Endpoint"]:::internal
        Events["Events Endpoint"]:::internal
        Handlers["GitHub Event Handlers"]:::internal
        Agents["Agent Logic"]:::internal
        CoreLogic["Core Logic"]:::internal
        Utils["Shared Utilities"]:::internal
    end

    %% Frontend Chat UI
    subgraph "Next.js Frontend"
        direction TB
        FrontendApp["Chat UI"]:::ui
        Routes["Routes & API Proxies"]:::ui
        UIComponents["UI Components"]:::ui
        Lib["Frontend Helpers"]:::ui
        Public["Static Assets"]:::ui
        Cypress["E2E Test Harness"]:::ui
    end

    %% Documentation and SDK
    subgraph "Documentation & SDK"
        direction TB
        DocsPortal["Documentation Portal"]:::ui
        PythonSDK["Python SDK Package"]:::internal
    end

    %% Deployment and Operations
    subgraph "Deployment & Operations"
        direction TB
        Docker["Docker Config"]:::infra
        Scripts["Deploy & Install Scripts"]:::infra
        CI["CI/CD Workflows"]:::infra
    end

    %% Storage
    Redis["Redis Vector DB"]:::storage

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub API"]:::external
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
        Cohere["Cohere API"]:::external
        JIRA["JIRA API"]:::external
        JetPlugin["JetBrains Plugin"]:::external
    end

    %% Data Flows
    JetPlugin -->|HTTP/CLI| CLI
    CLI -->|invoke| CoreLogic
    GitHubAPI -->|webhook| Events
    Events -->|dispatch| Handlers
    Handlers -->|select agent| Agents
    Agents -->|orchestrate| CoreLogic
    CoreLogic -->|store/retrieve embeddings| Redis
    CoreLogic -->|call| OpenAI
    CoreLogic -->|call| Anthropic
    CoreLogic -->|call| Cohere
    CoreLogic -->|call| JIRA
    FrontendApp -->|REST/WebSocket| Events

    %% Click Events
    click CLI "https://github.com/sweepai/sweep/blob/main/sweepai/cli.py"
    click Health "https://github.com/sweepai/sweep/blob/main/sweepai/web/health.py"
    click Events "https://github.com/sweepai/sweep/blob/main/sweepai/web/events.py"
    click Handlers "https://github.com/sweepai/sweep/tree/main/sweepai/handlers/"
    click Agents "https://github.com/sweepai/sweep/tree/main/sweepai/agents/"
    click CoreLogic "https://github.com/sweepai/sweep/tree/main/sweepai/core/"
    click Utils "https://github.com/sweepai/sweep/tree/main/sweepai/utils/"
    click FrontendApp "https://github.com/sweepai/sweep/tree/main/sweep_chat/"
    click Routes "https://github.com/sweepai/sweep/tree/main/sweep_chat/app/"
    click UIComponents "https://github.com/sweepai/sweep/tree/main/sweep_chat/components/"
    click Lib "https://github.com/sweepai/sweep/tree/main/sweep_chat/lib/"
    click Public "https://github.com/sweepai/sweep/tree/main/sweep_chat/public/"
    click Cypress "https://github.com/sweepai/sweep/tree/main/sweep_chat/cypress/"
    click DocsPortal "https://github.com/sweepai/sweep/tree/main/docs/"
    click PythonSDK "https://github.com/sweepai/sweep/tree/main/docs/sdk/"
    click Docker "https://github.com/sweepai/sweep/tree/main/Dockerfile"
    click Scripts "https://github.com/sweepai/sweep/tree/main/bin/"
    click CI "https://github.com/sweepai/sweep/tree/main/.github/workflows/"
    click Redis "https://github.com/sweepai/sweep/blob/main/redis.conf"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#005B96,color:#003F6B
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef storage fill:#FFF2CC,stroke:#BF9000,color:#BF6E00
    classDef ui fill:#F3D1F4,stroke:#8A2BE2,color:#5D0077
    classDef infra fill:#FFE5D4,stroke:#FF8C00,color:#A64B00
```
