# neverdecel/coderag architecture

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

- Interactive diagram: https://gitdiagram.com/neverdecel/coderag
- Repository: https://github.com/neverdecel/coderag

## Overview

1. **Repository shape**
   - This is a small Python 3.11+ application centered on a reusable `coderag` package, with thin entrypoints for a terminal CLI, a Streamlit UI, and background indexing/monitoring tasks.
   - The project is local-first: the main persistent artifact is a FAISS index file on disk, not a remote database service.

2. **Core domain boundary: `coderag/`**
   - `coderag/` contains the reusable engine for retrieval-augmented code assistance.
   - The main internal responsibilities are separated into configuration, embeddings, vector indexing, semantic search, and file monitoring.
   - This package is the architectural center; the UI, scripts, and tests all depend on it.

3. **Configuration layer**
   - `coderag/config.py` likely loads environment-driven settings such as the watched source directory, OpenAI model names, embedding dimension, and FAISS index path.
   - `example.env`, `README.md`, and `requirements.txt` show that runtime behavior is configured externally rather than hardcoded.

4. **Embedding and model boundary**
   - `coderag/embeddings.py` is the boundary to OpenAI’s embedding API.
   - The system converts code text into vectors using the configured embedding model, which is the foundation for semantic retrieval.
   - The README also implies GPT/chat models are used for the response-generation side of the RAG flow, though the exact orchestration likely lives elsewhere.

5. **Indexing/storage subsystem**
   - `coderag/index.py` owns FAISS vector index operations and persistence.
   - The index is the local storage layer for embeddings plus associated metadata, enabling fast similarity lookup without a separate vector database service.
   - `tests/test_faiss.py` and `tests/test_index.py` indicate this is a major correctness boundary.

6. **Search/retrieval subsystem**
   - `coderag/search.py` performs semantic search over the FAISS index.
   - Query text is embedded, matched against the stored vectors, and returns the most relevant code context.
   - This is the retrieval half of RAG and is likely consumed by both the CLI and the UI.

7. **Real-time update subsystem**
   - `coderag/monitor.py` handles filesystem watching, probably using Watchdog as the README suggests.
   - The monitor keeps the local index in sync with changes in the watched code directory, making indexing incremental rather than purely batch-oriented.
   - `scripts/run_monitor.py` appears to be a utility for running this subsystem directly.

8. **RAG orchestration**
   - `prompt_flow.py` is the likely orchestration boundary that combines retrieval output with an LLM prompt for final answers.
   - The data flow is: user question → search over FAISS → retrieved code snippets/context → chat model prompt → generated response.
   - This file probably sits above the lower-level package modules and coordinates end-to-end assistant behavior.

9. **User-facing entrypoints**
   - `app.py` is the Streamlit frontend, giving a conversational interface over the same retrieval engine.
   - `main.py` is the backend runner that starts indexing and monitoring, so the app can work against a live-updating index.
   - `coderag/cli.py` and the advertised `coderag-cli` command expose the same functionality in terminal form.

10. **Operational scripts**
   - `scripts/initialize_index.py` is a one-shot bootstrap path for creating the initial FAISS index from a codebase.
   - `scripts/run_monitor.py` is a long-running operational script for keeping the index updated.
   - These scripts separate setup/maintenance flows from the normal app entrypoints.

11. **Testing and quality boundary**
   - `tests/test_search.py`, `tests/test_index.py`, and `tests/test_faiss.py` focus on the retrieval stack rather than the UI.
   - `.github/workflows/ci-tests.yml` and `.pre-commit-config.yaml` show that CI and local code quality checks are part of the repository’s engineering workflow.

12. **High-level data flow**
   - Source files in `WATCHED_DIR` are observed, converted into embeddings, stored in the FAISS index, and then queried by user requests.
   - The retrieval result is fed into a prompt flow that prepares context for an OpenAI chat model.
   - The system therefore has two main runtime paths: background indexing/monitoring and foreground query/response generation.

13. **Important architecture boundaries to diagram**
   - External services: OpenAI embeddings/chat APIs.
   - Local persistence: FAISS index file and metadata on disk.
   - Long-running infrastructure: filesystem monitor/indexer process.
   - Presentation layers: Streamlit UI and CLI, both consuming the same shared package logic.

Main entry points: [`coderag/index.py`](https://github.com/neverdecel/coderag/blob/master/coderag/index.py) (Index), [`coderag/search.py`](https://github.com/neverdecel/coderag/blob/master/coderag/search.py) (Search), [`coderag/config.py`](https://github.com/neverdecel/coderag/blob/master/coderag/config.py) (Config), [`prompt_flow.py`](https://github.com/neverdecel/coderag/blob/master/prompt_flow.py) (Prompt flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core package"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_embeddings["Embeddings<br/>embedding client<br/>[embeddings.py]"]
  node_index[("Index<br/>faiss storage<br/>[index.py]")]
  node_search["Search<br/>retrieval<br/>[search.py]"]
  node_monitor["Monitor<br/>watcher<br/>[monitor.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_prompt_flow["Prompt flow<br/>rag orchestration<br/>[prompt_flow.py]"]
  node_cli["CLI<br/>terminal entrypoint<br/>[cli.py]"]
  node_app["Streamlit app<br/>ui entrypoint<br/>[app.py]"]
  node_main["Runner<br/>process entrypoint<br/>[main.py]"]
end

subgraph group_ops["Operations"]
  node_init_index["Init index<br/>bootstrap script"]
  node_run_monitor["Run monitor<br/>ops script<br/>[run_monitor.py]"]
end

subgraph group_quality["Quality"]
  node_tests["Tests<br/>test suite"]
end

subgraph group_external["External boundaries"]
  node_openai_embed(("OpenAI embeds<br/>external api"))
  node_openai_chat(("OpenAI chat<br/>external api"))
  node_faiss_store[("FAISS index<br/>local persistence")]
end

node_config -->|"model settings"| node_embeddings
node_config -->|"storage settings"| node_index
node_config -->|"runtime settings"| node_search
node_config -->|"watch settings"| node_monitor
node_embeddings -->|"calls"| node_openai_embed
node_index -->|"persists to"| node_faiss_store
node_search -->|"embed query"| node_embeddings
node_search -->|"reads"| node_index
node_monitor -->|"updates"| node_index
node_prompt_flow -->|"retrieves"| node_search
node_prompt_flow -->|"generates"| node_openai_chat
node_cli -->|"drives"| node_prompt_flow
node_app -->|"drives"| node_prompt_flow
node_main -->|"starts"| node_monitor
node_init_index -->|"bootstraps"| node_index
node_init_index -->|"embeds"| node_embeddings
node_run_monitor -->|"runs"| node_monitor
node_tests -->|"verifies"| node_index
node_tests -->|"verifies"| node_search
node_tests -->|"verifies"| node_faiss_store

click node_config "https://github.com/neverdecel/coderag/blob/master/coderag/config.py"
click node_embeddings "https://github.com/neverdecel/coderag/blob/master/coderag/embeddings.py"
click node_index "https://github.com/neverdecel/coderag/blob/master/coderag/index.py"
click node_search "https://github.com/neverdecel/coderag/blob/master/coderag/search.py"
click node_monitor "https://github.com/neverdecel/coderag/blob/master/coderag/monitor.py"
click node_prompt_flow "https://github.com/neverdecel/coderag/blob/master/prompt_flow.py"
click node_cli "https://github.com/neverdecel/coderag/blob/master/coderag/cli.py"
click node_app "https://github.com/neverdecel/coderag/blob/master/app.py"
click node_main "https://github.com/neverdecel/coderag/blob/master/main.py"
click node_init_index "https://github.com/neverdecel/coderag/blob/master/scripts/initialize_index.py"
click node_run_monitor "https://github.com/neverdecel/coderag/blob/master/scripts/run_monitor.py"
click node_tests "https://github.com/neverdecel/coderag/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_embeddings,node_index,node_search,node_monitor toneBlue
class node_prompt_flow,node_cli,node_app,node_main toneAmber
class node_init_index,node_run_monitor toneMint
class node_tests toneRose
class node_openai_embed,node_openai_chat,node_faiss_store toneIndigo
```

## Components

### Core package

Reusable retrieval and monitoring engine.

- [Config](https://github.com/neverdecel/coderag/blob/master/coderag/config.py): settings · Loads runtime settings and environment-driven paths/models. · `coderag/config.py`
- [Embeddings](https://github.com/neverdecel/coderag/blob/master/coderag/embeddings.py): embedding client · Converts code and queries into vectors via the embedding API. · `coderag/embeddings.py`
- [Index](https://github.com/neverdecel/coderag/blob/master/coderag/index.py): faiss storage · Builds, updates, and persists the local vector index. · `coderag/index.py`
- [Search](https://github.com/neverdecel/coderag/blob/master/coderag/search.py): retrieval · Runs semantic lookup over the stored vectors and metadata. · `coderag/search.py`
- [Monitor](https://github.com/neverdecel/coderag/blob/master/coderag/monitor.py): watcher · Watches the source tree and incrementally updates the index. · `coderag/monitor.py`

### Interfaces

User-facing entrypoints and orchestration.

- [Prompt flow](https://github.com/neverdecel/coderag/blob/master/prompt_flow.py): rag orchestration · Coordinates retrieval and prompt construction for final answers. · `prompt_flow.py`
- [CLI](https://github.com/neverdecel/coderag/blob/master/coderag/cli.py): terminal entrypoint · Command-line interface over the shared retrieval engine. · `coderag/cli.py`
- [Streamlit app](https://github.com/neverdecel/coderag/blob/master/app.py): ui entrypoint · Interactive frontend for asking questions against the codebase. · `app.py`
- [Runner](https://github.com/neverdecel/coderag/blob/master/main.py): process entrypoint · Starts the background indexing and monitoring workflow. · `main.py`

### Operations

Scripts for bootstrap and long-running sync.

- [Init index](https://github.com/neverdecel/coderag/blob/master/scripts/initialize_index.py): bootstrap script · One-shot script to create the initial index from source code. · `scripts/initialize_index.py`
- [Run monitor](https://github.com/neverdecel/coderag/blob/master/scripts/run_monitor.py): ops script · Long-running script for keeping the index updated. · `scripts/run_monitor.py`

### Quality

Tests and CI coverage of core flows.

- [Tests](https://github.com/neverdecel/coderag/tree/master/tests): test suite · Covers retrieval, indexing, and FAISS integration behavior. · `tests`

### External boundaries

Model APIs and local persistence.

- **OpenAI embeds**: external api · External embedding service used to vectorize code and queries.
- **OpenAI chat**: external api · Generates the final assistant response from retrieved context.
- **FAISS index**: local persistence · On-disk vector index and associated metadata storage.

## Connections

- Config → Embeddings: model settings · Provides embedding model and API configuration.
- Config → Index: storage settings · Provides index path and embedding dimensions.
- Config → Search: runtime settings · Configures retrieval behavior and limits.
- Config → Monitor: watch settings · Provides watched directory and sync options.
- Embeddings → OpenAI embeds: calls · Uses the embedding API to encode text.
- Index → FAISS index: persists to · Stores and loads the local vector index.
- Search → Embeddings: embed query · Turns user queries into vectors before lookup.
- Search → Index: reads · Queries the indexed vectors and metadata.
- Monitor → Index: updates · Keeps the index in sync with file changes.
- Prompt flow → Search: retrieves · Pulls relevant code context for a question.
- Prompt flow → OpenAI chat: generates · Sends retrieved context to the chat model.
- CLI → Prompt flow: drives · Uses the shared RAG orchestration for terminal queries.
- Streamlit app → Prompt flow: drives · Uses the same orchestration from the UI.
- Runner → Monitor: starts · Launches the background filesystem watcher.
- Init index → Index: bootstraps · Creates the initial local index from source files.
- Init index → Embeddings: embeds · Vectorizes the initial corpus during bootstrap.
- Run monitor → Monitor: runs · Executes the monitoring loop as a standalone process.
- Tests → Index: verifies · Covers index correctness and persistence behavior.
- Tests → Search: verifies · Covers semantic retrieval behavior.
- Tests → FAISS index: verifies · Checks FAISS integration and storage semantics.
