# stacklok/codegate architecture

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

- Interactive diagram: https://gitdiagram.com/stacklok/codegate
- Repository: https://github.com/stacklok/codegate

## Overview

##### Project Type and Purpose
- CodeGate is an all-in-one agent for managing AI coding assistants, providing security reviews, workspace management, prompt muxing, and model routing. It centralizes configuration for multiple AI providers, handles security analysis (like secrets & PII redaction), dependency risk awareness, and securely mediates interactions with AI models.
- It is packaged as a Docker container with a web dashboard (accessible on port 9090) and command-line tools, all orchestrated by a monolithic Python backend organized into multiple functional modules.

##### Analyzing the File Structure
- Top-Level Layers:
- Core directories include “src” (primary Python code), “api” (OpenAPI specification), “migrations” (database schema changes), “docs” (documentation including setup and usage), and “tests” (unit, integration, and pipeline tests).
- Configuration files (config.yaml, alembic.ini) and a Dockerfile indicate containerized deployment.
- Within “src/codegate”:
- API: The “api” subfolder contains versioned API endpoints and models (e.g., v1.py, v1_models.py, v1_processing.py).
- Core Business Logic: Modules for the CLI, logging, configuration, and error handling.
- Database and Persistence: The “db” subfolder includes the database connection, models, and token usage tracking.
- Inference and Muxing: The “inference” module (inference_engine.py) and “muxing” module (including adapters, mappers, rule matchers, and persona routing) show how prompts are dynamically routed.
- Pipelines: The “pipeline” directory illustrates different processing steps—context retrieval, comment management, PII analysis, secrets scanning, suspicious command detection, and system prompt handling.
- Providers: The “providers” directory integrates multiple AI and LLM providers (Anthropic, OpenAI, Copilot, Ollama, etc.), each with their own completion handlers and adapters to communicate securely.
- Additional Utilities: Modules for snippet extraction, storage, workspaces, and updates support the complete lifecycle for prompt management and secure interactions.
- Testing and CI: The extensive “tests” directory and GitHub workflows indicate a robust quality assurance process.

a. Main Components:
- Client Interfaces:
- Web Dashboard (browser-based, connected to port 9090)
- CLI (for command-line interactions)
- API Server:
- REST API endpoints (under “api/” with v1 processing)
- Authentication and request validation
- Core Engine:
- Inference Engine (handles AI prompt processing)
- Pipeline processing modules (context retrieval, secrets & PII redaction, security reviews)
- Muxing/Router module (route prompts to different AI providers)
- Provider Modules:
- Different AI providers (Anthropic, OpenAI, Ollama, Copilot, etc.) each with dedicated handlers and adapter logic under “providers/”
- Data and Database:
- Database layer (illustrated by “db” modules plus Alembic-managed migrations)
- Configuration and state storage (via the volume mount “codegate_volume” and persistent configuration files)
- Auxiliary Services:
- Logging and monitoring (integrated in modules like “codegate_logging.py”)
- File storage for models and prompt data (see “codegate_volume/models” and “prompts”)
- External configurations and security policies (configured via config.yaml and related docs)

b. Component Relationships and Data Flow:
- The API server forwards the requests to the Core Engine, which processes them through various pipeline stages (snippet extraction, security checks, context retrieval).
- The Muxing/Router directs the processed request to the appropriate Provider Module based on workspace settings or file types.
- Provider Modules then communicate with external AI services (or local endpoints, as configured) and route responses back through the pipeline (for post-processing, e.g., de-redaction) to the API server and finally the client.
- The Database Layer supports persistent storage for user workspaces, provider configurations, chat histories, security events, and token usage.

c. Highlighted Architectural Patterns and Design Principles:
- Modular design: Different subsystems (API, Pipeline, Providers, and Database) are separated.
- Layered architecture: Clear separation between presentation (dashboard/CLI), business logic (core engine and pipelines), and data persistence.
- Extensibility: The “providers” and “muxing” modules are designed to support multiple AI engines, each with its own logic.
- Security-first approach: Emphasize modules for secrets redaction, PII detection, and dependency risk analysis.

d. Relevant Technologies and Frameworks:
- Docker (containerization as defined in the Dockerfile and volume mounts)
- Python (code organization under “src/codegate”)
- Alembic (database migrations managed in “migrations”)
- Various AI provider integrations, each adapted through custom modules
- REST API as defined by the OpenAPI specification in “api/openapi.json”
- Web Dashboard running on a dedicated port, likely built with modern web stack principles

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI Interface"]:::client
        WD["Web Dashboard (Port 9090)"]:::client
    end

    %% API/Presentation Layer
    subgraph "API/Presentation Layer"
        API["API Server (REST API)"]:::presentation
    end

    %% Core Processing/Engine Layer
    subgraph "Core Processing/Engine Layer"
        INF["Inference Engine"]:::core
        PIPE["Pipeline Components"]:::core
        MUX["Muxing/Router Module"]:::core
        INF -->|"processes"| PIPE
        PIPE -->|"flows to"| MUX
    end

    %% Provider Integration Layer
    subgraph "Provider Integration Layer"
        PROV["Provider Modules"]:::provider
    end

    %% Data & Persistence Layer
    subgraph "Data & Persistence Layer"
        DB["Database & Migrations"]:::persistence
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        LOG["Logging"]:::auxiliary
        FILE["File Storage (Models & Prompts)"]:::auxiliary
        CONF["Configuration (config.yaml)"]:::auxiliary
    end

    %% Docker Container Deployment (Infrastructure)
    subgraph "Docker Container Deployment"
        DOCK["Containerized Backend"]:::container
    end

    %% Connections
    CLI -->|"sendsRequest"| API
    WD -->|"sendsRequest"| API
    API -->|"initiates"| INF
    MUX -->|"routesTo"| PROV
    PROV -->|"returnsResponse"| API
    API -->|"persistsData"| DB
    API -->|"logsActivity"| LOG
    API -->|"readsFiles"| FILE
    API -->|"loadsConfig"| CONF
    API --- DOCK
    CLI --- DOCK
    WD --- DOCK

    %% Click Events
    click CLI "https://github.com/stacklok/codegate/blob/main/src/codegate/cli.py"
    click WD "https://github.com/stacklok/codegate/tree/main/static"
    click API "https://github.com/stacklok/codegate/tree/main/src/codegate/api"
    click INF "https://github.com/stacklok/codegate/blob/main/src/codegate/inference/inference_engine.py"
    click PIPE "https://github.com/stacklok/codegate/tree/main/src/codegate/pipeline"
    click MUX "https://github.com/stacklok/codegate/tree/main/src/codegate/muxing"
    click PROV "https://github.com/stacklok/codegate/tree/main/src/codegate/providers"
    click DB "https://github.com/stacklok/codegate/tree/main/src/codegate/db"
    click LOG "https://github.com/stacklok/codegate/blob/main/src/codegate/codegate_logging.py"
    click FILE "https://github.com/stacklok/codegate/tree/main/codegate_volume"
    click CONF "https://github.com/stacklok/codegate/blob/main/config.yaml"

    %% Styles
    classDef client fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef presentation fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef core fill:#ffebcd,stroke:#000,stroke-width:2px;
    classDef provider fill:#ff7f7f,stroke:#000,stroke-width:2px;
    classDef persistence fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef auxiliary fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef container fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
