# cased/kit architecture

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

- Interactive diagram: https://gitdiagram.com/cased/kit
- Repository: https://github.com/cased/kit

## Overview

##### Project type and purpose
- This is an open-source, modular Python toolkit (“kit”) exposing both a CLI (`kit cli`) and a Python API for codebase mapping, symbol extraction, code search, context assembly, and LLM-powered summarization.
- It ships with:
- A core library under `src/kit/`
- A set of Tree-sitter query files per language under `queries/`
- Utility scripts for benchmarking, indexing, testing, releasing
- An Astro-based documentation site in `docs/`

##### File structure
- Top-level:
- `src/kit/` – Python packages (api, cli, code_searcher, context_extractor, dependency_analyzer, docstring_indexer, llm_context, repo_mapper, repository, summaries, tree_sitter_symbol_extractor, vector_searcher)
- `queries/<lang>/tags.scm` – language grammar queries for symbol extraction
- `scripts/` – automation: `benchmark.py`, `index.py`, `release.sh`, etc.
- `tests/` – unit/integration tests and fixtures
- `docs/` – static site sources (Astro framework) for user docs and tutorials
- CI and build configs: `.github/workflows/ci.yml`, `Makefile`, `pyproject.toml`

##### Insights from README
- Key capabilities:
- File‐system or remote Git repo exploration (`Repository`)
- Symbol extraction (via Tree-sitter)
- Text and semantic search (vector store)
- Context chunking for LLMs
- AI-powered docstring summarization & indexing
- Targets integration points: local/remote repos, LLM providers, embedding/vector stores

1. “CLI / Entrypoint” – `kit cli` commands
2. “Python API” – top-level façade (`Repository`, `Summarizer`, etc.)
3. “Core Modules” –
- Repository & Filesystem Access
- Tree-sitter Symbol Extractor (+ `queries/`)
- Dependency Analyzer & Context Extractor
- Code Searcher & Vector Searcher (vector index)
- Docstring Indexer & Summary Searcher
- LLM Context & Summarizer (external LLM calls)
4. “Data Stores & External Services” –
- Local FS / Git Repo
- In-memory or persistent Vector DB (FAISS or other)
- LLM Provider API (OpenAI, etc.)
5. “Docs Site (Astro)” – static site generation reading from `docs/src/content`
6. “CI/CD Pipeline” – GitHub Actions, Makefile, scripts

- CLI → Python API → Core Modules
- Repository module ↔ Local FS / Git
- Symbol Extractor → consumes `queries/…tags.scm` → outputs symbol data
- Code Searcher & Vector Searcher ← embedding service → Vector DB
- Summarizer & LLM Context → HTTP calls → External LLM API
- Docstring Indexer → populates Vector DB
- Docs Site ← Markdown/MDX under `docs/src/content` → built assets

c. Architectural patterns & design principles
- Modular monolith: independent sub-packages plugged into a common API
- Layered architecture:
Presentation (CLI/Docs)
Application logic (kit modules)
Infrastructure (FS, external APIs, Vector DB)
- Plugin-style extensibility: new languages by adding query files

d. Key technologies/frameworks
- Python 3, Tree-sitter for parsing
- vector search backend (e.g., FAISS or in-memory)
- OpenAI or similar LLM provider
- Astro (JavaScript) for docs site
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI / Entrypoint"]:::cli
        DocsSite["Docs Site (Astro)"]:::docs
    end

    %% Application Layer (Core Modules)
    subgraph "Application Layer (Core Modules)"
        API["Python API Facade"]:::core
        Repo["Repository & Filesystem Access"]:::core
        RepoMapper["Repository Mapper"]:::core
        SymbolExt["Tree-sitter Symbol Extractor"]:::core
        DepAna["Dependency Analyzer"]:::core
        ContextExt["Context Extractor"]:::core
        CodeSearch["Code Searcher"]:::core
        VecSearch["Vector Searcher"]:::core
        DocIdx["Docstring Indexer"]:::core
        Summaries["Summaries Module"]:::core
        LLMContext["LLM Context & Provider"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        LocalFS["Local FS / Git Repo"]:::infra
        Queries["Language Query Files"]:::infra
        VectorDB["Vector DB"]:::infra
        LLMAPI["LLM Provider API"]:::infra
    end

    %% CI/CD & Scripts
    subgraph "CI/CD & Scripts"
        Benchmark["Benchmarking Script"]:::script
        IndexScript["Indexing Script"]:::script
        Release["Release Automation"]:::script
        TestScript["Test Automation"]:::script
        Typecheck["Type-check Script"]:::script
        CI["CI Workflow"]:::script
        MakefileNode["Makefile"]:::script
        Pyproj["pyproject.toml"]:::script
    end

    %% Data Flows
    CLI -->|"invokes"| API
    API -->|"uses"| Repo
    API -->|"uses"| SymbolExt
    API -->|"uses"| DepAna
    API -->|"uses"| ContextExt
    API -->|"uses"| CodeSearch
    API -->|"uses"| VecSearch
    API -->|"uses"| DocIdx
    API -->|"uses"| Summaries
    API -->|"uses"| LLMContext

    SymbolExt -->|"loads queries"| Queries
    Repo -->|"reads/writes"| LocalFS
    RepoMapper -->|"traverses"| Repo
    CodeSearch -->|"searches files"| LocalFS
    VecSearch -->|"stores/loads vectors"| VectorDB
    DocIdx -->|"indexes docstrings"| VectorDB
    LLMContext -->|"calls"| LLMAPI
    Summaries -->|"coordinates with"| LLMContext

    CI -->|"runs"| Benchmark
    CI -->|"runs"| IndexScript
    CI -->|"runs"| TestScript
    CI -->|"runs"| Typecheck
    CI -->|"triggers"| Release
    CI -->|"builds docs"| DocsSite
    CI -->|"uses"| MakefileNode
    CI -->|"uses"| Pyproj

    %% Click Events
    click CLI "https://github.com/cased/kit/blob/main/src/kit/cli.py"
    click API "https://github.com/cased/kit/blob/main/src/kit/api/app.py"
    click Repo "https://github.com/cased/kit/blob/main/src/kit/repository.py"
    click RepoMapper "https://github.com/cased/kit/blob/main/src/kit/repo_mapper.py"
    click SymbolExt "https://github.com/cased/kit/blob/main/src/kit/tree_sitter_symbol_extractor.py"
    click Queries "https://github.com/cased/kit/blob/main/queries/<lang>/tags.scm"
    click DepAna "https://github.com/cased/kit/blob/main/src/kit/dependency_analyzer.py"
    click ContextExt "https://github.com/cased/kit/blob/main/src/kit/context_extractor.py"
    click CodeSearch "https://github.com/cased/kit/blob/main/src/kit/code_searcher.py"
    click VecSearch "https://github.com/cased/kit/blob/main/src/kit/vector_searcher.py"
    click DocIdx "https://github.com/cased/kit/blob/main/src/kit/docstring_indexer.py"
    click Summaries "https://github.com/cased/kit/blob/main/src/kit/summaries.py"
    click LLMContext "https://github.com/cased/kit/blob/main/src/kit/llm_context.py"
    click DocsSite "https://github.com/cased/kit/tree/main/docs/"
    click Benchmark "https://github.com/cased/kit/blob/main/scripts/benchmark.py"
    click IndexScript "https://github.com/cased/kit/blob/main/scripts/index.py"
    click Release "https://github.com/cased/kit/blob/main/scripts/release.sh"
    click TestScript "https://github.com/cased/kit/blob/main/scripts/test.sh"
    click Typecheck "https://github.com/cased/kit/blob/main/scripts/typecheck.sh"
    click CI "https://github.com/cased/kit/blob/main/.github/workflows/ci.yml"
    click MakefileNode "https://github.com/cased/kit/tree/main/Makefile"
    click Pyproj "https://github.com/cased/kit/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#ccffcc,stroke:#006600;
    classDef infra fill:#cce5ff,stroke:#004085;
    classDef cli fill:#ffedcc,stroke:#cc7a00;
    classDef docs fill:#e2e3e5,stroke:#6c757d;
    classDef script fill:#f2f2f2,stroke:#999999;
```
