# hmoubarak72/self-healing-docs architecture

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

- Interactive diagram: https://gitdiagram.com/hmoubarak72/self-healing-docs
- Repository: https://github.com/hmoubarak72/self-healing-docs

## Overview

DocHeal is a documentation-staleness analyzer and repair tool, exposed as a local CLI and GitHub Action. Its main workflow parses code and Markdown into linked semantic units, classifies changes, finds affected sections, verifies and repairs stale text, then reports results and may open a fix PR. The graph preserves both LLM and deterministic rule engines, plus embedding-based indexing and GitHub delivery. Relationships for unsampled modules are included only where the README or source index supports them; optional provider and vector-store integrations are shown separately.

Main entry points: [`docheal/cli.py`](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/cli.py) (CLI and Action), [`docheal/pipeline.py`](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/pipeline.py) (Check orchestration), [`docheal/graph.py`](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/graph.py) (Link graph), [`docheal/llm.py`](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/llm.py) (LLM and rule engines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and settings"]
  node_cli["CLI and Action<br/>[cli.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_mapping["Code-doc mapping"]
  node_code_parser["Code parser<br/>[code_parser.py]"]
  node_doc_parser["Markdown parser<br/>[doc_parser.py]"]
  node_graph["Link graph<br/>[graph.py]"]
  node_embeddings["Embedding providers<br/>[embeddings.py]"]
  node_index_file[("Persisted index")]
end

subgraph group_analysis["Change analysis"]
  node_diff["Semantic diff<br/>[diff.py]"]
  node_facts["Change facts<br/>[facts.py]"]
  node_models["Shared data models<br/>[models.py]"]
  node_pipeline["Check orchestration<br/>[pipeline.py]"]
end

subgraph group_repair["Verification and repair"]
  node_llm["LLM and rule engines<br/>[llm.py]"]
end

subgraph group_delivery["Reporting and delivery"]
  node_report["Report renderer<br/>[report.py]"]
  node_github_io["GitHub operations<br/>[github_io.py]"]
end

node_pr_author(("PR author"))
node_llm_service{{"LLM providers"}}
node_doc_sections["Documentation files"]
node_codebase["Repository code"]
node_github{{"GitHub PR and checks"}}

node_pr_author -->|"starts check"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"runs check"| node_pipeline
node_codebase -->|"parsed into chunks"| node_code_parser
node_doc_sections -->|"parsed into sections"| node_doc_parser
node_code_parser -->|"supplies code chunks"| node_graph
node_doc_parser -->|"supplies doc sections"| node_graph
node_graph -->|"builds similarity links"| node_embeddings
node_graph -->|"persists index"| node_index_file
node_cli -->|"builds index"| node_graph
node_diff -->|"parses both versions"| node_code_parser
node_cli -->|"checks changes"| node_diff
node_pipeline -->|"classifies changes"| node_diff
node_pipeline -->|"looks up suspects"| node_graph
node_pipeline -->|"ranks evidence"| node_facts
node_pipeline -->|"verifies and repairs"| node_llm
node_llm -->|"uses change facts"| node_facts
node_llm -.->|"requests completions"| node_llm_service
node_pipeline -->|"writes corrections"| node_doc_sections
node_pipeline -->|"provides check results"| node_report
node_cli -->|"publishes Action results"| node_github_io
node_github_io -->|"comments and opens fix PR"| node_github
node_report -->|"renders PR content"| node_github_io
node_cli -->|"runs on pull requests"| node_github

click node_cli "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/cli.py"
click node_settings "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/config.py"
click node_code_parser "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/code_parser.py"
click node_doc_parser "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/doc_parser.py"
click node_graph "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/graph.py"
click node_embeddings "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/embeddings.py"
click node_diff "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/diff.py"
click node_facts "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/facts.py"
click node_models "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/models.py"
click node_pipeline "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/pipeline.py"
click node_llm "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/llm.py"
click node_report "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/report.py"
click node_github_io "https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/github_io.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_settings toneBlue
class node_code_parser,node_doc_parser,node_graph,node_embeddings,node_index_file toneAmber
class node_diff,node_facts,node_models,node_pipeline toneMint
class node_llm toneRose
class node_report,node_github_io,node_pr_author,node_llm_service,node_doc_sections,node_codebase,node_github toneIndigo
```

## Components

### Entry and settings

- [CLI and Action](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/cli.py): `docheal/cli.py`
- [Runtime settings](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/config.py): `docheal/config.py`

### Code-doc mapping

- [Code parser](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/code_parser.py): `docheal/code_parser.py`
- [Markdown parser](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/doc_parser.py): `docheal/doc_parser.py`
- [Link graph](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/graph.py): `docheal/graph.py`
- [Embedding providers](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/embeddings.py): `docheal/embeddings.py`
- **Persisted index**

### Change analysis

- [Semantic diff](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/diff.py): `docheal/diff.py`
- [Change facts](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/facts.py): `docheal/facts.py`
- [Shared data models](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/models.py): `docheal/models.py`
- [Check orchestration](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/pipeline.py): `docheal/pipeline.py`

### Verification and repair

- [LLM and rule engines](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/llm.py): `docheal/llm.py`

### Reporting and delivery

- [Report renderer](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/report.py): `docheal/report.py`
- [GitHub operations](https://github.com/hmoubarak72/self-healing-docs/blob/main/docheal/github_io.py): `docheal/github_io.py`

### Other components

- **PR author**
- **LLM providers**
- **Documentation files**
- **Repository code**
- **GitHub PR and checks**

## Connections

- PR author → CLI and Action: starts check (evidence: `README.md`)
- CLI and Action → Runtime settings: loads settings (evidence: `docheal/cli.py`)
- CLI and Action → Check orchestration: runs check (evidence: `README.md`)
- Repository code → Code parser: parsed into chunks (evidence: `README.md`)
- Documentation files → Markdown parser: parsed into sections (evidence: `README.md`)
- Code parser → Link graph: supplies code chunks (evidence: `README.md`)
- Markdown parser → Link graph: supplies doc sections (evidence: `README.md`)
- Link graph → Embedding providers: builds similarity links (evidence: `docheal/graph.py`)
- Link graph → Persisted index: persists index (evidence: `README.md`)
- CLI and Action → Link graph: builds index (evidence: `docheal/cli.py`)
- Semantic diff → Code parser: parses both versions (evidence: `docheal/diff.py`)
- CLI and Action → Semantic diff: checks changes (evidence: `docheal/cli.py`)
- Check orchestration → Semantic diff: classifies changes (evidence: `docheal/pipeline.py`)
- Check orchestration → Link graph: looks up suspects (evidence: `docheal/pipeline.py`)
- Check orchestration → Change facts: ranks evidence (evidence: `docheal/pipeline.py`)
- Check orchestration → LLM and rule engines: verifies and repairs (evidence: `README.md`)
- LLM and rule engines → Change facts: uses change facts (evidence: `docheal/llm.py`)
- LLM and rule engines → LLM providers: requests completions
- Check orchestration → Documentation files: writes corrections (evidence: `README.md`)
- Check orchestration → Report renderer: provides check results (evidence: `docheal/report.py`)
- CLI and Action → GitHub operations: publishes Action results (evidence: `docheal/cli.py`)
- GitHub operations → GitHub PR and checks: comments and opens fix PR (evidence: `README.md`)
- Report renderer → GitHub operations: renders PR content (evidence: `docheal/github_io.py`)
- CLI and Action → GitHub PR and checks: runs on pull requests (evidence: `README.md`)