# context-labs/autodoc architecture

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

- Interactive diagram: https://gitdiagram.com/context-labs/autodoc
- Repository: https://github.com/context-labs/autodoc

## Overview

#### Purpose and Runtime
Autodoc is a Node.js (v18+) TypeScript CLI that generates, stores, and queries LLM-produced documentation for a local Git repository. Its public executable starts at `src/index.ts`; command implementations live under `src/cli/commands`. Generated documentation and retrieval artifacts are persisted inside the target repository’s `.autodoc/` directory.

#### CLI Control Plane
The CLI exposes initialization, indexing, estimation, querying, and user/model-management flows:
- `src/cli/commands/init/index.ts`
- `src/cli/commands/index/index.ts`
- `src/cli/commands/query/index.ts`

`init` interactively collects repository metadata, model access, and prompt choices, then writes `autodoc.config.json`. This configuration is the boundary between user/project policy and indexing/query execution.

#### Repository Indexing Pipeline
Indexing is orchestrated in `src/cli/commands/index/index.ts` and processes the repository depth-first through `src/cli/utils/traverseFileSystem.ts`. The main stages are:
1. Detect repository contents and prior generated documentation.
2. Determine changed or undocumented files.
3. Read source files and calculate token requirements.
4. Select a supported LLM/model for each input.
5. Generate file and directory documentation.
6. Persist structured JSON/Markdown documentation and rebuild retrieval data.

Core per-repository work is separated into `src/cli/commands/index/processRepository.ts`, while prompt construction resides in `src/cli/commands/index/prompts.ts`.

#### Documentation Artifact Boundary
The indexer emits two durable representations: structured documents for machine consumption and Markdown for repository-visible documentation. Conversion is handled by `src/cli/commands/index/convertJsonToMarkdown.ts`. In this repository, outputs demonstrate the layout:
- `.autodoc/docs/json/src/index.json`
- `.autodoc/docs/markdown/src/index.md`
- `.autodoc/docs/data/docstore.json`

These artifacts are intended to be committed with code, enabling subsequent users to query a prebuilt repository index.

#### Cost Estimation and Model Selection
Before indexing, the estimate command calculates likely token/cost usage based on repository contents and selectable OpenAI models:
- `src/cli/commands/estimate/index.ts`
- `src/cli/commands/index/selectModel.ts`
- `src/cli/utils/LLMUtil.ts`

Model choice is a material quality/cost boundary: the documented behavior selects the least expensive model whose context window fits a file. API throttling and pacing are isolated in `src/cli/utils/APIRateLimit.ts` and `src/cli/utils/WaitUtil.ts`.

#### Retrieval and Interactive Querying
Querying loads the locally persisted vector store, retrieves relevant generated documents, and supplies them as context to an LLM chat chain:
- `src/cli/commands/query/index.ts`
- `src/cli/commands/query/createChatChain.ts`
- `src/langchain/hnswlib.ts`

The vector index is stored locally (for example, `.autodoc/docs/data/hnswlib.index`) alongside the document store. This establishes a retrieval-augmented generation boundary: source code is documented during indexing; queries generally operate on generated documentation plus vector-retrieved context rather than repeatedly scanning the full codebase.

#### External Dependencies and Services
The primary external service is the OpenAI API, authenticated via `OPENAI_API_KEY`; current README behavior supports OpenAI models only. LangChain and HNSWLib underpin embeddings/vector retrieval, with the local HNSW index managed through `src/langchain/hnswlib.ts`. The tool is distributed as an npm CLI package and operates directly against local Git working trees, without a web-service runtime.

Main entry points: [`src/cli/commands/index/processRepository.ts`](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/processRepository.ts) (Repository processor), [`src/cli/utils/LLMUtil.ts`](https://github.com/context-labs/autodoc/blob/master/src/cli/utils/LLMUtil.ts) (LLM client), [`src/index.ts`](https://github.com/context-labs/autodoc/blob/master/src/index.ts) (Autodoc CLI), [`src/cli/commands/index/index.ts`](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/index.ts) (Index command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI control plane"]
  node_entrypoint["Autodoc CLI<br/>Node.js executable<br/>[index.ts]"]
  node_init["Init command<br/>interactive setup<br/>[index.ts]"]
  node_config["Project config<br/>policy boundary"]
  node_estimate["Estimate command<br/>cost estimator<br/>[index.ts]"]
end

subgraph group_indexing["Indexing pipeline"]
  node_index_command["Index command<br/>pipeline orchestrator<br/>[index.ts]"]
  node_traversal["Filesystem traversal<br/>repository scanner"]
  node_process_repository["Repository processor<br/>indexing core"]
  node_prompts["Index prompts<br/>prompt builder<br/>[prompts.ts]"]
  node_model_selector["Model selection<br/>cost/context policy<br/>[selectModel.ts]"]
  node_llm_util["LLM client<br/>OpenAI integration<br/>[LLMUtil.ts]"]
  node_rate_limit["API pacing<br/>throttling<br/>[APIRateLimit.ts]"]
  node_markdown_converter["Markdown conversion<br/>artifact renderer"]
end

subgraph group_artifacts["Local artifacts"]
  node_json_docs["Structured docs<br/>JSON documentation<br/>[index.json]"]
  node_markdown_docs["Markdown docs<br/>repository documentation<br/>[index.md]"]
  node_document_store[("Document store<br/>retrieval corpus<br/>[docstore.json]")]
  node_vector_index[("HNSW vector index<br/>local vector store<br/>[hnswlib.index]")]
end

subgraph group_query["Retrieval and query"]
  node_query_command["Query command<br/>interactive query<br/>[index.ts]"]
  node_chat_chain["RAG chat chain<br/>LLM query chain<br/>[createChatChain.ts]"]
  node_hnswlib["HNSWLib adapter<br/>vector retrieval<br/>[hnswlib.ts]"]
end

node_openai{{"OpenAI API<br/>external LLM service"}}

node_entrypoint -->|"runs"| node_init
node_entrypoint -->|"runs"| node_index_command
node_entrypoint -->|"runs"| node_estimate
node_entrypoint -->|"runs"| node_query_command
node_init -->|"writes"| node_config
node_config -.->|"governs"| node_index_command
node_config -.->|"governs"| node_query_command
node_estimate -->|"scans"| node_traversal
node_estimate -->|"prices inputs"| node_model_selector
node_index_command -->|"scans"| node_traversal
node_index_command -->|"orchestrates"| node_process_repository
node_traversal -->|"source files"| node_process_repository
node_process_repository -->|"builds requests"| node_prompts
node_process_repository -->|"selects model"| node_model_selector
node_prompts -->|"LLM request"| node_llm_util
node_model_selector -->|"selected model"| node_llm_util
node_rate_limit -.->|"paces calls"| node_llm_util
node_llm_util -->|"API calls"| node_openai
node_process_repository -->|"writes"| node_json_docs
node_json_docs -->|"converts"| node_markdown_converter
node_markdown_converter -->|"writes"| node_markdown_docs
node_json_docs -->|"builds corpus"| node_document_store
node_document_store -->|"embeds and indexes"| node_hnswlib
node_hnswlib -->|"persists"| node_vector_index
node_query_command -->|"starts"| node_chat_chain
node_chat_chain -->|"retrieves context"| node_hnswlib
node_hnswlib -->|"loads"| node_vector_index
node_chat_chain -->|"answers with context"| node_llm_util

click node_entrypoint "https://github.com/context-labs/autodoc/blob/master/src/index.ts"
click node_init "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/init/index.ts"
click node_config "https://github.com/context-labs/autodoc/blob/master/autodoc.config.json"
click node_index_command "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/index.ts"
click node_traversal "https://github.com/context-labs/autodoc/blob/master/src/cli/utils/traverseFileSystem.ts"
click node_process_repository "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/processRepository.ts"
click node_prompts "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/prompts.ts"
click node_model_selector "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/selectModel.ts"
click node_llm_util "https://github.com/context-labs/autodoc/blob/master/src/cli/utils/LLMUtil.ts"
click node_rate_limit "https://github.com/context-labs/autodoc/blob/master/src/cli/utils/APIRateLimit.ts"
click node_json_docs "https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/json/src/index.json"
click node_markdown_converter "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/convertJsonToMarkdown.ts"
click node_markdown_docs "https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/markdown/src/index.md"
click node_document_store "https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/data/docstore.json"
click node_vector_index "https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/data/hnswlib.index"
click node_estimate "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/estimate/index.ts"
click node_query_command "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/query/index.ts"
click node_chat_chain "https://github.com/context-labs/autodoc/blob/master/src/cli/commands/query/createChatChain.ts"
click node_hnswlib "https://github.com/context-labs/autodoc/blob/master/src/langchain/hnswlib.ts"

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_entrypoint,node_init,node_config,node_estimate toneBlue
class node_index_command,node_traversal,node_process_repository,node_prompts,node_model_selector,node_llm_util,node_rate_limit,node_markdown_converter toneAmber
class node_json_docs,node_markdown_docs,node_document_store,node_vector_index toneMint
class node_query_command,node_chat_chain,node_hnswlib toneRose
class node_openai toneNeutral
```

## Components

### CLI control plane

- [Autodoc CLI](https://github.com/context-labs/autodoc/blob/master/src/index.ts): Node.js executable · `src/index.ts`
- [Init command](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/init/index.ts): interactive setup · Collects repository, model, and prompt choices. · `src/cli/commands/init/index.ts`
- [Project config](https://github.com/context-labs/autodoc/blob/master/autodoc.config.json): policy boundary · Captures user and project indexing/query policy. · `autodoc.config.json`
- [Estimate command](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/estimate/index.ts): cost estimator · Calculates likely token and cost usage before indexing. · `src/cli/commands/estimate/index.ts`

### Indexing pipeline

- [Index command](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/index.ts): pipeline orchestrator · `src/cli/commands/index/index.ts`
- [Filesystem traversal](https://github.com/context-labs/autodoc/blob/master/src/cli/utils/traverseFileSystem.ts): repository scanner · Walks the Git working tree depth-first. · `src/cli/utils/traverseFileSystem.ts`
- [Repository processor](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/processRepository.ts): indexing core · Determines changed files and produces file and directory documentation. · `src/cli/commands/index/processRepository.ts`
- [Index prompts](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/prompts.ts): prompt builder · `src/cli/commands/index/prompts.ts`
- [Model selection](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/selectModel.ts): cost/context policy · Chooses the least expensive model that fits the input context. · `src/cli/commands/index/selectModel.ts`
- [LLM client](https://github.com/context-labs/autodoc/blob/master/src/cli/utils/LLMUtil.ts): OpenAI integration · `src/cli/utils/LLMUtil.ts`
- [API pacing](https://github.com/context-labs/autodoc/blob/master/src/cli/utils/APIRateLimit.ts): throttling · `src/cli/utils/APIRateLimit.ts`
- [Markdown conversion](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/index/convertJsonToMarkdown.ts): artifact renderer · `src/cli/commands/index/convertJsonToMarkdown.ts`

### Local artifacts

Persisted in the target repository.

- [Structured docs](https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/json/src/index.json): JSON documentation · Machine-consumable generated documents. · `.autodoc/docs/json/src/index.json`
- [Markdown docs](https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/markdown/src/index.md): repository documentation · Commit-ready, repository-visible documentation. · `.autodoc/docs/markdown/src/index.md`
- [Document store](https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/data/docstore.json): retrieval corpus · `.autodoc/docs/data/docstore.json`
- [HNSW vector index](https://github.com/context-labs/autodoc/blob/master/.autodoc/docs/data/hnswlib.index): local vector store · `.autodoc/docs/data/hnswlib.index`

### Retrieval and query

- [Query command](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/query/index.ts): interactive query · `src/cli/commands/query/index.ts`
- [RAG chat chain](https://github.com/context-labs/autodoc/blob/master/src/cli/commands/query/createChatChain.ts): LLM query chain · Answers using retrieved generated documentation. · `src/cli/commands/query/createChatChain.ts`
- [HNSWLib adapter](https://github.com/context-labs/autodoc/blob/master/src/langchain/hnswlib.ts): vector retrieval · Manages the local vector index. · `src/langchain/hnswlib.ts`

### Other components

- **OpenAI API**: external LLM service · Authenticated with OPENAI_API_KEY.

## Connections

- Autodoc CLI → Init command: runs
- Autodoc CLI → Index command: runs
- Autodoc CLI → Estimate command: runs
- Autodoc CLI → Query command: runs
- Init command → Project config: writes
- Project config → Index command: governs
- Project config → Query command: governs
- Estimate command → Filesystem traversal: scans
- Estimate command → Model selection: prices inputs
- Index command → Filesystem traversal: scans
- Index command → Repository processor: orchestrates
- Filesystem traversal → Repository processor: source files
- Repository processor → Index prompts: builds requests
- Repository processor → Model selection: selects model
- Index prompts → LLM client: LLM request
- Model selection → LLM client: selected model
- API pacing → LLM client: paces calls
- LLM client → OpenAI API: API calls
- Repository processor → Structured docs: writes
- Structured docs → Markdown conversion: converts
- Markdown conversion → Markdown docs: writes
- Structured docs → Document store: builds corpus
- Document store → HNSWLib adapter: embeds and indexes
- HNSWLib adapter → HNSW vector index: persists
- Query command → RAG chat chain: starts
- RAG chat chain → HNSWLib adapter: retrieves context
- HNSWLib adapter → HNSW vector index: loads
- RAG chat chain → LLM client: answers with context
