# tomdevtech/docdrift architecture

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

- Interactive diagram: https://gitdiagram.com/tomdevtech/docdrift
- Repository: https://github.com/tomdevtech/docdrift

## Overview

docdrift maintains two independent documentation flows: a local technical-doc flow triggered by a push or manual run, and a merge-triggered product-doc flow. The local pipeline analyzes Git changes deterministically, then generates per-file notes, optional ADR drafts, and a conditional architecture overview for an Obsidian vault. The merge flow filters for user-visible changes and dispatches either a Copilot task or LLM-based documentation edits. Edges reflect the excerpts, SOURCE INDEX references, and README; some subsystem internals were not sampled.

Main entry points: [`src/docdrift/local/pipeline.py`](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/pipeline.py) (Local run pipeline), [`src/docdrift/merge/task.py`](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/task.py) (Merge task and filter), [`src/docdrift/cli/commands.py`](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/cli/commands.py) (CLI commands), [`src/docdrift/merge/llm.py`](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/llm.py) (Product-doc LLM engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and setup"]
  node_cli["CLI commands<br/>[commands.py]"]
  node_setup["Setup installer<br/>[install.py]"]
  node_doctor["Setup checks<br/>[doctor.py]"]
end

subgraph group_shared["Shared change analysis"]
  node_config["Configuration<br/>[config.py]"]
  node_git["Git operations<br/>[git_utils.py]"]
  node_changes["Change collection<br/>[changes.py]"]
  node_analysis["AST analysis<br/>[analysis.py]"]
end

subgraph group_local["Local technical docs"]
  node_pipeline["Local run pipeline<br/>[pipeline.py]"]
  node_state[("Run state<br/>[state.py]")]
  node_playbooks["Prompt playbooks<br/>[playbook_loader.py]"]
  node_local_llm["Local LLM client<br/>[llm_client.py]"]
  node_adr["ADR drafting<br/>[adr.py]"]
  node_vault["Vault access<br/>[vault.py]"]
end

subgraph group_merge["Merge product docs"]
  node_docs_task["Merge task and filter<br/>[task.py]"]
  node_docs_check["Docs pre-check<br/>[docs_check.py]"]
  node_merge_llm["Product-doc LLM engine<br/>[llm.py]"]
end

node_user(("Developer"))
node_local_service(("Local LLM server"))
node_obsidian["Obsidian vault"]
node_remote_llm(("OpenAI-compatible API"))
node_copilot(("Copilot agent"))
node_product_docs["README and docs"]

node_user -->|"runs commands"| node_cli
node_cli -->|"installs hooks"| node_setup
node_cli -->|"runs checks"| node_doctor
node_cli -->|"starts local run"| node_pipeline
node_cli -->|"builds merge task"| node_docs_task
node_cli -->|"runs docs updates"| node_merge_llm
node_pipeline -->|"loads settings"| node_config
node_pipeline -->|"locks and saves"| node_state
node_pipeline -->|"collects changes"| node_changes
node_changes -->|"reads Git range"| node_git
node_changes -->|"analyzes snapshots"| node_analysis
node_pipeline -->|"loads prompts"| node_playbooks
node_pipeline -->|"requests generated text"| node_local_llm
node_local_llm -->|"sends chat request"| node_local_service
node_pipeline -->|"assesses and drafts ADR"| node_adr
node_pipeline -->|"writes technical notes"| node_vault
node_adr -->|"reads and writes ADRs"| node_vault
node_vault -->|"stores notes"| node_obsidian
node_docs_task -->|"uses settings"| node_config
node_docs_task -->|"resolves PR range"| node_git
node_docs_task -->|"checks relevance"| node_docs_check
node_docs_task -->|"collects structural hints"| node_changes
node_docs_task -.->|"creates agent task"| node_copilot
node_merge_llm -->|"uses task hints"| node_docs_task
node_merge_llm -->|"sends chat requests"| node_remote_llm
node_merge_llm -->|"updates selected docs"| node_product_docs

click node_cli "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/cli/commands.py"
click node_config "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/config.py"
click node_setup "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/setup/install.py"
click node_doctor "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/setup/doctor.py"
click node_git "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/git_utils.py"
click node_changes "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/changes.py"
click node_analysis "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/analysis.py"
click node_pipeline "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/pipeline.py"
click node_state "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/state.py"
click node_playbooks "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/playbook_loader.py"
click node_local_llm "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/llm_client.py"
click node_adr "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/adr.py"
click node_vault "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/vault.py"
click node_docs_task "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/task.py"
click node_docs_check "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/docs_check.py"
click node_merge_llm "https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/llm.py"

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_cli,node_setup,node_doctor toneBlue
class node_config,node_git,node_changes,node_analysis toneAmber
class node_pipeline,node_state,node_playbooks,node_local_llm,node_adr,node_vault,node_local_service,node_remote_llm toneMint
class node_docs_task,node_docs_check,node_merge_llm toneRose
class node_user,node_obsidian,node_copilot,node_product_docs toneIndigo
```

## Components

### Entry and setup

- [CLI commands](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/cli/commands.py): `src/docdrift/cli/commands.py`
- [Setup installer](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/setup/install.py): `src/docdrift/setup/install.py`
- [Setup checks](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/setup/doctor.py): `src/docdrift/setup/doctor.py`

### Shared change analysis

- [Configuration](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/config.py): `src/docdrift/core/config.py`
- [Git operations](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/git_utils.py): `src/docdrift/core/git_utils.py`
- [Change collection](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/changes.py): `src/docdrift/core/changes.py`
- [AST analysis](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/core/analysis.py): `src/docdrift/core/analysis.py`

### Local technical docs

- [Local run pipeline](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/pipeline.py): `src/docdrift/local/pipeline.py`
- [Run state](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/state.py): `src/docdrift/local/state.py`
- [Prompt playbooks](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/playbook_loader.py): `src/docdrift/local/playbook_loader.py`
- [Local LLM client](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/llm_client.py): `src/docdrift/local/llm_client.py`
- [ADR drafting](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/adr.py): `src/docdrift/local/adr.py`
- [Vault access](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/local/vault.py): `src/docdrift/local/vault.py`

### Merge product docs

- [Merge task and filter](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/task.py): `src/docdrift/merge/task.py`
- [Docs pre-check](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/docs_check.py): `src/docdrift/merge/docs_check.py`
- [Product-doc LLM engine](https://github.com/tomdevtech/docdrift/blob/main/src/docdrift/merge/llm.py): `src/docdrift/merge/llm.py`

### Other components

- **Developer**
- **Local LLM server**
- **Obsidian vault**
- **OpenAI-compatible API**
- **Copilot agent**
- **README and docs**

## Connections

- Developer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Setup installer: installs hooks (evidence: `src/docdrift/cli/commands.py`)
- CLI commands → Setup checks: runs checks (evidence: `src/docdrift/cli/commands.py`)
- CLI commands → Local run pipeline: starts local run (evidence: `src/docdrift/cli/commands.py`)
- CLI commands → Merge task and filter: builds merge task (evidence: `src/docdrift/cli/commands.py`)
- CLI commands → Product-doc LLM engine: runs docs updates (evidence: `src/docdrift/cli/commands.py`)
- Local run pipeline → Configuration: loads settings (evidence: `src/docdrift/local/pipeline.py`)
- Local run pipeline → Run state: locks and saves (evidence: `src/docdrift/local/pipeline.py`)
- Local run pipeline → Change collection: collects changes (evidence: `src/docdrift/core/changes.py`)
- Change collection → Git operations: reads Git range (evidence: `src/docdrift/core/changes.py`)
- Change collection → AST analysis: analyzes snapshots (evidence: `src/docdrift/core/changes.py`)
- Local run pipeline → Prompt playbooks: loads prompts (evidence: `src/docdrift/local/pipeline.py`)
- Local run pipeline → Local LLM client: requests generated text (evidence: `src/docdrift/local/pipeline.py`)
- Local LLM client → Local LLM server: sends chat request (evidence: `src/docdrift/local/llm_client.py`)
- Local run pipeline → ADR drafting: assesses and drafts ADR (evidence: `src/docdrift/local/pipeline.py`)
- Local run pipeline → Vault access: writes technical notes (evidence: `src/docdrift/local/pipeline.py`)
- ADR drafting → Vault access: reads and writes ADRs (evidence: `src/docdrift/local/adr.py`)
- Vault access → Obsidian vault: stores notes (evidence: `src/docdrift/local/vault.py`)
- Merge task and filter → Configuration: uses settings (evidence: `src/docdrift/merge/task.py`)
- Merge task and filter → Git operations: resolves PR range (evidence: `src/docdrift/merge/task.py`)
- Merge task and filter → Docs pre-check: checks relevance (evidence: `src/docdrift/merge/task.py`)
- Merge task and filter → Change collection: collects structural hints (evidence: `src/docdrift/merge/task.py`)
- Merge task and filter → Copilot agent: creates agent task (evidence: `README.md`)
- Product-doc LLM engine → Merge task and filter: uses task hints (evidence: `src/docdrift/merge/llm.py`)
- Product-doc LLM engine → OpenAI-compatible API: sends chat requests (evidence: `src/docdrift/merge/llm.py`)
- Product-doc LLM engine → README and docs: updates selected docs (evidence: `README.md`)
