# timpratim/cargo-chat architecture

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

- Interactive diagram: https://gitdiagram.com/timpratim/cargo-chat
- Repository: https://github.com/timpratim/cargo-chat

## Overview

##### Project type and purpose
- cargo-chat is a Rust-based, command-line Retrieval-Augmented Generation engine (RAG).
- It performs:
- Codebase chunking (tree-sitter + code-splitter)
- Embedding (via embed_anything/Jina)
- Approximate Nearest Neighbor (ANN) search (vector crate)
- Reranking (pluggable interface)
- Serialization (bincode)
- All orchestrated behind a simple CLI (clap + tokio).

##### File structure
- Top-level:
- Cargo.toml – crate manifest
- src/ – main application modules
– main.rs (CLI entrypoint)
– chunker.rs
– embedding.rs
– ann.rs
– rerank.rs
– openai.rs (if integrating OpenAI APIs)
– hyde.rs (optional augmentation)
- .gitignore / README.md
- README also references a sibling “vector/” crate providing the ANN index.

##### Key insights from the README
- Workflow:
- Index subcommand: traverse repo → chunker → embedder → ANN index → serialize
- Query subcommand: embed query → ANN search → optional reranker → output
- Dependencies map directly to modules.

##### Detailed component breakdown
- CLI Launcher
- Parses args → triggers either “index” or “query” subcommand
- Chunker Stage
- Invokes tree-sitter → produces code/text chunks
- Embedder Stage
- Calls Jina embed_anything API → returns float vectors
- ANN Index
- Uses vector-crate’s forest indexing → insert or k-NN search
- Reranker
- Accepts raw results → applies rerank interface → final order
- Serializer
- Uses bincode → read/write index.bin on disk
- External Model Repos
- Directory pointers for embedding & rerank models

##### Final advice
- Both “build” (index) and “serve” (query) flows side by side.
- Module boundaries and data contracts (e.g., “Vec<f32>”).
- Async boundaries if relevant (e.g., “tokio runtime”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI
    CLI["CLI Launcher\n(src/main.rs)"]:::cli

    %% Index Flow
    subgraph "Index Flow"
        direction TB
        Chunker["Chunker\n(src/chunker.rs)"]:::internal
        Hyde["Hyde Augmenter\n(src/hyde.rs)"]:::internal
        EmbedIndex["Embedder\n(src/embedding.rs)"]:::internal
        ModelDirE(("Embedding Model Dir")):::external
        ANNInsert["ANN Index\n(src/ann.rs)"]:::internal
        Serializer["Serializer\n(bincode)"]:::storage
    end

    %% Query Flow
    subgraph "Query Flow"
        direction TB
        EmbedQuery["Embedder\n(src/embedding.rs)"]:::internal
        ModelDirQ(("Embedding Model Dir")):::external
        ANNSearch["ANN Index\n(src/ann.rs)"]:::internal
        Reranker["Reranker\n(src/rerank.rs)"]:::internal
        ModelDirR(("Rerank Model Dir")):::external
    end

    %% Optional External
    subgraph "Optional LLM Hooks"
        direction TB
        OpenAI["OpenAI API\n(src/openai.rs)"]:::external
    end

    %% Flows
    CLI -->|"index"| Chunker
    Chunker -->|"augmented chunks"| Hyde
    Hyde -->|"chunks"| EmbedIndex
    EmbedIndex -->|"Vec<f32>"| ANNInsert
    EmbedIndex --> ModelDirE
    ANNInsert -->|"insert"| Serializer

    CLI -->|"query"| EmbedQuery
    EmbedQuery -->|"Vec<f32>"| ANNSearch
    EmbedQuery --> ModelDirQ
    ANNSearch -->|"raw hits"| Reranker
    Reranker -->|"reranked results"| CLI
    Reranker --> ModelDirR

    %% Async runtime annotation
    CLI -.->|"tokio runtime"| CLI

    %% Optional LLM integration
    CLI --> OpenAI
    OpenAI --> Reranker

    %% Click Events
    click CLI "https://github.com/timpratim/cargo-chat/blob/main/src/main.rs"
    click Chunker "https://github.com/timpratim/cargo-chat/blob/main/src/chunker.rs"
    click EmbedIndex "https://github.com/timpratim/cargo-chat/blob/main/src/embedding.rs"
    click EmbedQuery "https://github.com/timpratim/cargo-chat/blob/main/src/embedding.rs"
    click ANNInsert "https://github.com/timpratim/cargo-chat/blob/main/src/ann.rs"
    click ANNSearch "https://github.com/timpratim/cargo-chat/blob/main/src/ann.rs"
    click Reranker "https://github.com/timpratim/cargo-chat/blob/main/src/rerank.rs"
    click OpenAI "https://github.com/timpratim/cargo-chat/blob/main/src/openai.rs"
    click Hyde "https://github.com/timpratim/cargo-chat/blob/main/src/hyde.rs"
    click Serializer "https://github.com/timpratim/cargo-chat/blob/main/Cargo.toml"
    click Serializer "https://github.com/timpratim/cargo-chat/blob/main/README.md"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef external fill:#A9DFBF,stroke:#145A32,color:#0B5345,shape:cloud
    classDef storage fill:#F9E79F,stroke:#B9770E,color:#784212,shape:cylinder
    classDef cli fill:#F5B7B1,stroke:#7B241C,color:#512E5F,shape:hexagon
```
