# codestoryai/sidecar architecture

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

- Interactive diagram: https://gitdiagram.com/codestoryai/sidecar
- Repository: https://github.com/codestoryai/sidecar

## Overview

##### Main components
- Sidecar Core: This includes the central logic that ties together the various subsystems.
- Webserver/API Layer: Located under sidecar/src/bin (e.g., webserver.rs) and sidecar/src/webserver, this layer receives requests (e.g., from the Aide editor) and dispatches them to the underlying services.
- Agent and Agentic Modules: Found in sidecar/src/agent, sidecar/src/agentic. These modules define the AI “agent” behavior, including prompt generation, context parsing, and decision-making.
- Repository Mapping (Repomap): The repomap folder implements page rank and symbol mapping for the code base. Represent it as an independent module that processes code structure.
- LLM Clients: Both the “llm_client” and the “llm_prompts” directories (even if the latter is partly legacy) encapsulate the interfaces to various LLM providers (OpenAI, Anthropic, etc.). Include these as external service connectors.
- Logging and Reporting: The “logging” module and reporting subdirectories (under both llm_client and sidecar/src/reporting) provide instrumentation and feedback to track system performance.
- Database and Migrations: Several folders and SQL migration files appear in “llm_client/.sqlx” and “sidecar/migrations”. These represent the persistent data layer that stores model data, caches, or prompt history.
- Ancillary Tools: Additional modules such as repomap, chunking, git integration, and inline completion represent supporting functionalities that enhance the agent’s capabilities.

##### Relationships and interactions
- The Aide editor (an external consumer) communicates with Sidecar via a dedicated API (webserver layer).
- LLM Clients abstract the specifics of external providers; these components will interact with external APIs over the network.
- Data storage, logging, and reporting modules record interactions and metrics to support auditing, error tracking, and performance tuning.
- Cross-cutting functionalities like repo mapping and file analysis are separate services that are invoked as needed, often feeding data back into the higher-level agent logic.

##### Important architectural patterns and design principles
- Modular design: The project is broken into discrete libraries and binaries (e.g., separate crates such as “llm_client”, “llm_prompts”, “logging”, and “sidecar”).
- Pluggability and abstraction: Different LLM clients and tool implementations indicate that the system is designed for extensibility, where new providers or tools can be added with minimal changes.
- Separation of concerns: There is a clear division between request handling, AI agent control logic, tool execution, and reporting/logging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    AE["Aide Editor"]:::external

    %% Webserver/API Layer
    WS["Webserver/API Layer"]:::processing

    %% Sidecar Core
    SC["Sidecar Core"]:::processing

    %% Agent & Agentic Modules
    AM["Agent & Agentic Modules"]:::processing

    %% Tool Box & Symbol Processor
    TBPS["Tool Box & Symbol Processor"]:::tool

    %% Repository Mapping (Repomap)
    RM["Repository Mapping (Repomap)"]:::processing

    %% LLM Clients
    LLM["LLM Clients"]:::processing

    %% External LLM Providers
    LP["LLM Providers (External)"]:::external

    %% Logging & Reporting
    LR["Logging & Reporting"]:::infrastructure

    %% Database & Migrations
    DB["Database & Migrations"]:::infrastructure

    %% Ancillary Tools
    AT["Ancillary Tools (Chunking, Git, Inline Completion)"]:::processing

    %% Relationships
    AE -->|"sendsRequest"| WS
    WS -->|"dispatchesTo"| SC
    SC -->|"orchestrates"| AM
    AM -->|"uses"| TBPS
    AM -->|"invokes"| LLM
    LLM -->|"calls"| LP
    AM -->|"queries"| RM
    AM -->|"logsTo"| LR
    AM -->|"savesTo"| DB
    AM -->|"integrates"| AT

    %% Click Events
    click SC "https://github.com/codestoryai/sidecar/blob/main/sidecar/src/lib.rs"
    click SC "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/application/"
    click WS "https://github.com/codestoryai/sidecar/blob/main/sidecar/src/bin/webserver.rs"
    click WS "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/webserver/"
    click AM "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/agent"
    click AM "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/agentic/"
    click TBPS "https://github.com/codestoryai/sidecar/blob/main/sidecar/src/agentic/symbol/tool_box.rs"
    click TBPS "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/agentic/symbol/"
    click RM "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/repomap/"
    click LLM "https://github.com/codestoryai/sidecar/tree/main/llm_client/"
    click LLM "https://github.com/codestoryai/sidecar/tree/main/llm_prompts/"
    click LR "https://github.com/codestoryai/sidecar/tree/main/logging/"
    click LR "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/reporting/"
    click LR "https://github.com/codestoryai/sidecar/tree/main/llm_client/src/reporting/"
    click DB "https://github.com/codestoryai/sidecar/tree/main/llm_client/.sqlx/"
    click DB "https://github.com/codestoryai/sidecar/tree/main/sidecar/migrations/"
    click AT "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/chunking/"
    click AT "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/git/"
    click AT "https://github.com/codestoryai/sidecar/tree/main/sidecar/src/inline_completion/"

    %% Styles
    classDef external fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef processing fill:#C7E9C0,stroke:#333,stroke-width:2px;
    classDef tool fill:#F4CCCC,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#D0E0E3,stroke:#333,stroke-width:2px;
```
