# kantord/seagoat architecture

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

- Interactive diagram: https://gitdiagram.com/kantord/seagoat
- Repository: https://github.com/kantord/seagoat

## Overview

##### Project type and purpose
- SeaGOAT is a full-stack, local code search engine CLI application written in Python.
- It consists of two main “faces”:
- A CLI client (`seagoat`, `gt`) for querying/searching
- A persistent server (`seagoat-server`) that indexes files and serves queries
- It leverages ripgrep for text/regex search and ChromaDB as a local vector database for semantic search.

##### File structure
- Top level:
- `seagoat/`: core Python package
- `seagoat/cli.py`: CLI entrypoint
- `seagoat/server.py`: HTTP server entrypoint
- `seagoat/engine.py`, `cache.py`, `queue/`, `repository.py`, `gitfile.py`, `result.py`: business logic
- `seagoat/sources/`: adapters for different data sources (Chroma, ripgrep)
- `seagoat/utils/`: helpers (config, file reading, JSON, display, etc.)
- `locustfile.py`: performance testing
- `docs/`, `mkdocs.yml`: documentation site
- GitHub workflows, CI/CD configs, tests, typing stubs
- Patterns:
- CLI ↔ HTTP server ↔ engine
- Engine enqueues tasks, processes file streams, stores embeddings in a vector DB
- “Sources” abstraction: each query/indexing source implements a common interface
- Background queue (`seagoat/queue`) decouples indexing from request handling

##### README for additional insights
- Architecture described implicitly in “How does SeaGOAT work?” and “Why does it need a server?”
- Key external dependencies: Python 3.11, ripgrep, optional `bat`, ChromaDB (embedded), local file system, Git repo.

##### Final advice
- Be granular: break “Engine” into subcomponents (Index Worker, Query Handler).
- Both indexing and query-time flows.
- Config layer feeding into Server & Engine.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% CLI Layer
  subgraph "CLI Client Layer"
    CLI["CLI Client"]:::process
    Display["CLI Display (bat/pygments)"]:::external
  end
  CLI -->|"formats output"| Display
  CLI -->|"sends HTTP request"| Server

  %% Server Layer
  subgraph "Backend Server"
    Server["HTTP Server"]:::process
    Config["Configuration Loader"]:::config
    Server -->|"load config"| Config
    Server -->|"enqueue tasks"| Queue
    Server -->|"handle query"| QueryHandler
  end

  %% Task Queue
  subgraph "Task Queue"
    Queue["Task Queue"]:::process
    Queue -->|"dispatch task"| IndexWorker
  end

  %% Engine Layer
  subgraph "Engine"
    IndexWorker["Index Worker"]:::process
    QueryHandler["Query Handler"]:::process
    FileReader["File Reader"]:::process
    Repo["Repository Adapter"]:::process
    GitFile["Git File Reader"]:::process
    Ripgrep["Ripgrep Source"]:::external
    ChromaSource["ChromaDB Source"]:::external
    DB["ChromaDB"]:::database
    Cache["Cache / On-disk Store"]:::database

    IndexWorker -->|"read files"| FileReader
    FileReader -->|"stream files"| Repo
    Repo -->|"access git"| GitFile
    IndexWorker -->|"generate embeddings"| ChromaSource
    ChromaSource -->|"store vectors"| DB

    QueryHandler -->|"text/regex search"| Ripgrep
    QueryHandler -->|"semantic search"| ChromaSource
    QueryHandler -->|"cache lookup"| Cache
    QueryHandler -->|"return results"| Server
  end

  %% External Tools
  subgraph "External Tools"
    RipgrepTool["ripgrep"]:::external
    BatTool["bat"]:::external
  end
  Ripgrep --> RipgrepTool
  Display --> BatTool

  %% Config to Engine
  Config --> Server
  Config --> IndexWorker
  Config --> QueryHandler

  %% Click Events
  click CLI "https://github.com/kantord/seagoat/blob/main/seagoat/cli.py"
  click Display "https://github.com/kantord/seagoat/blob/main/seagoat/utils/cli_display.py"
  click Server "https://github.com/kantord/seagoat/blob/main/seagoat/server.py"
  click Config "https://github.com/kantord/seagoat/blob/main/seagoat/utils/config.py"
  click Queue "https://github.com/kantord/seagoat/blob/main/seagoat/queue/task_queue.py"
  click IndexWorker "https://github.com/kantord/seagoat/blob/main/seagoat/engine.py"
  click QueryHandler "https://github.com/kantord/seagoat/blob/main/seagoat/engine.py"
  click FileReader "https://github.com/kantord/seagoat/blob/main/seagoat/utils/file_reader.py"
  click Repo "https://github.com/kantord/seagoat/blob/main/seagoat/repository.py"
  click GitFile "https://github.com/kantord/seagoat/blob/main/seagoat/gitfile.py"
  click Ripgrep "https://github.com/kantord/seagoat/blob/main/seagoat/sources/ripgrep.py"
  click ChromaSource "https://github.com/kantord/seagoat/blob/main/seagoat/sources/chroma.py"
  click DB "https://github.com/kantord/seagoat/blob/main/seagoat/cache.py"
  click Cache "https://github.com/kantord/seagoat/blob/main/seagoat/cache.py"
  click Display "https://github.com/kantord/seagoat/blob/main/seagoat/utils/cli_display.py"
  click Config "https://github.com/kantord/seagoat/blob/main/seagoat/utils/config.py"
  click Json "https://github.com/kantord/seagoat/blob/main/seagoat/utils/json_file.py"
  click Debug "https://github.com/kantord/seagoat/blob/main/seagoat/utils/debug.py"
  click FileTypes "https://github.com/kantord/seagoat/blob/main/seagoat/utils/file_types.py"
  click Wait "https://github.com/kantord/seagoat/blob/main/seagoat/utils/wait.py"
  click Generative "https://github.com/kantord/seagoat/blob/main/seagoat/utils/generative.py"

  %% Styles
  classDef process fill:#D0E8FF,stroke:#0366D6,color:#000;
  classDef database fill:#E2F0D9,stroke:#228B22,color:#000;
  classDef external fill:#FFE5B4,stroke:#FF8C00,color:#000;
  classDef config fill:#F3E5F5,stroke:#9932CC,color:#000;
```
