# rathna070-ai/ado-llm-defect-analyzer architecture

> Architecture diagram of the GitHub repository rathna070-ai/ado-llm-defect-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rathna070-ai/ado-llm-defect-analyzer
- Repository: https://github.com/rathna070-ai/ado-llm-defect-analyzer

## Overview

ADO Defect LLM Analysis imports defects from Azure DevOps or Excel/CSV, classifies them with a configurable LLM, persists results, and produces summaries and exports for BI or a Streamlit dashboard. The graph follows documented stages and caller-owned relationships shown in excerpts, the SOURCE INDEX, or README. Some dashboard, report, provider, and storage details are unsampled; their links are limited to those references and documented capabilities.

Main entry points: [`src/ado_defect_analysis/cli.py`](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/cli.py) (CLI), [`src/ado_defect_analysis/pipeline/fetch.py`](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/fetch.py) (Fetch stage), [`src/ado_defect_analysis/pipeline/categorize.py`](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/categorize.py) (Categorization stage), [`src/ado_defect_analysis/ado_client.py`](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/ado_client.py) (Azure DevOps client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_dashboard["Streamlit app<br/>[streamlit_app.py]"]
  node_home["Source and run view<br/>[home.py]"]
  node_results["Leadership results<br/>[results.py]"]
  node_background["Background run manager<br/>[background.py]"]
end

subgraph group_ingest["Defect ingestion"]
  node_ado_query["Saved-query URL parser<br/>[ado_query.py]"]
  node_ado_client["Azure DevOps client<br/>[ado_client.py]"]
  node_excel["Excel/CSV parser<br/>[excel_source.py]"]
  node_fetch["Fetch stage<br/>[fetch.py]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_models["Defect data models<br/>[models.py]"]
  node_categorize["Categorization stage<br/>[categorize.py]"]
  node_aggregate["Aggregation and review metrics<br/>[aggregate.py]"]
  node_capa["CAPA metrics<br/>[capa.py]"]
  node_report["Narrative report<br/>[report.py]"]
  node_export["BI export<br/>[export.py]"]
end

subgraph group_integration["LLM and configuration"]
  node_llm_factory["Provider selection<br/>[factory.py]"]
  node_llm_base["LLM interface and usage<br/>[base.py]"]
  node_openai_transport["OpenAI-compatible transport"]
  node_azure_provider["Azure provider<br/>[azure_provider.py]"]
  node_groq_provider["Groq provider<br/>[groq_provider.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_secrets["Credential store<br/>[secrets.py]"]
  node_http["Retrying HTTP session<br/>[http.py]"]
end

subgraph group_outputs["Persistence and results"]
  node_storage[("Defect store<br/>[storage.py]")]
end

node_operator(("Operator"))
node_ado_service["Azure DevOps"]
node_export_file["ADO export file"]
node_llm_service["LLM service"]
node_sqlite[("SQLite database")]
node_exports["CSV/XLSX and review outputs"]

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses dashboard"| node_dashboard
node_cli -->|"dispatches fetch"| node_fetch
node_cli -->|"dispatches categorize"| node_categorize
node_cli -->|"dispatches report"| node_report
node_cli -->|"dispatches export"| node_export
node_cli -->|"loads settings"| node_config
node_dashboard -->|"renders"| node_home
node_dashboard -->|"renders"| node_results
node_home -->|"starts source fetch"| node_fetch
node_home -->|"starts run"| node_background
node_background -->|"runs analysis"| node_categorize
node_home -->|"uses settings"| node_config
node_ado_query -->|"resolves query reference"| node_ado_client
node_fetch -->|"parses query URL"| node_ado_query
node_fetch -->|"fetches work items"| node_ado_client
node_fetch -->|"parses export"| node_excel
node_fetch -->|"upserts defects"| node_storage
node_ado_client -->|"queries API"| node_ado_service
node_excel -.->|"reads file"| node_export_file
node_ado_client -->|"constructs defects"| node_models
node_excel -->|"produces defects"| node_models
node_categorize -->|"loads and saves"| node_storage
node_categorize -->|"gets provider"| node_llm_factory
node_categorize -->|"uses interface"| node_llm_base
node_categorize -->|"uses defect shapes"| node_models
node_aggregate -->|"reads categorized defects"| node_storage
node_aggregate -->|"uses metrics"| node_capa
node_report -->|"builds summary input"| node_aggregate
node_report -->|"gets provider"| node_llm_factory
node_export -->|"uses aggregates"| node_aggregate
node_export -->|"writes reports"| node_exports
node_results -->|"renders metrics"| node_aggregate
node_results -->|"offers export"| node_export
node_llm_factory -->|"selects backend"| node_config
node_llm_factory -->|"constructs provider"| node_azure_provider
node_llm_factory -->|"constructs provider"| node_groq_provider
node_azure_provider -->|"extends transport"| node_openai_transport
node_groq_provider -->|"uses transport"| node_openai_transport
node_openai_transport -->|"implements interface"| node_llm_base
node_openai_transport -->|"builds session"| node_http
node_openai_transport -->|"sends completions"| node_llm_service
node_ado_client -->|"builds session"| node_http
node_config -->|"resolves credentials"| node_secrets
node_storage -->|"reads and writes"| node_sqlite
node_background -->|"uses settings"| node_config

click node_cli "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/cli.py"
click node_dashboard "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/streamlit_app.py"
click node_home "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/views/home.py"
click node_results "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/views/results.py"
click node_ado_query "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/ado_query.py"
click node_ado_client "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/ado_client.py"
click node_excel "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/excel_source.py"
click node_fetch "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/fetch.py"
click node_models "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/models.py"
click node_categorize "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/categorize.py"
click node_aggregate "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/aggregate.py"
click node_capa "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/capa.py"
click node_report "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/report.py"
click node_export "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/export.py"
click node_llm_factory "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/factory.py"
click node_llm_base "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/base.py"
click node_openai_transport "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/openai_compatible.py"
click node_azure_provider "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/azure_provider.py"
click node_groq_provider "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/groq_provider.py"
click node_config "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/config.py"
click node_secrets "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/secrets.py"
click node_background "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/background.py"
click node_storage "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/storage.py"
click node_http "https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/http.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_dashboard,node_home,node_results,node_background,node_exports toneBlue
class node_ado_query,node_ado_client,node_excel,node_fetch,node_sqlite toneAmber
class node_models,node_categorize,node_aggregate,node_capa,node_report,node_export toneMint
class node_llm_factory,node_llm_base,node_openai_transport,node_azure_provider,node_groq_provider,node_config,node_secrets,node_http toneRose
class node_storage,node_operator,node_ado_service,node_export_file,node_llm_service toneIndigo
```

## Components

### User entry points

- [CLI](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/cli.py): `src/ado_defect_analysis/cli.py`
- [Streamlit app](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/streamlit_app.py): `src/ado_defect_analysis/dashboard/streamlit_app.py`
- [Source and run view](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/views/home.py): `src/ado_defect_analysis/dashboard/views/home.py`
- [Leadership results](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/dashboard/views/results.py): `src/ado_defect_analysis/dashboard/views/results.py`
- [Background run manager](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/background.py): `src/ado_defect_analysis/background.py`

### Defect ingestion

- [Saved-query URL parser](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/ado_query.py): `src/ado_defect_analysis/ado_query.py`
- [Azure DevOps client](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/ado_client.py): `src/ado_defect_analysis/ado_client.py`
- [Excel/CSV parser](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/excel_source.py): `src/ado_defect_analysis/excel_source.py`
- [Fetch stage](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/fetch.py): `src/ado_defect_analysis/pipeline/fetch.py`

### Analysis pipeline

- [Defect data models](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/models.py): `src/ado_defect_analysis/models.py`
- [Categorization stage](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/categorize.py): `src/ado_defect_analysis/pipeline/categorize.py`
- [Aggregation and review metrics](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/aggregate.py): `src/ado_defect_analysis/pipeline/aggregate.py`
- [CAPA metrics](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/capa.py): `src/ado_defect_analysis/capa.py`
- [Narrative report](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/report.py): `src/ado_defect_analysis/pipeline/report.py`
- [BI export](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/pipeline/export.py): `src/ado_defect_analysis/pipeline/export.py`

### LLM and configuration

- [Provider selection](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/factory.py): `src/ado_defect_analysis/llm/factory.py`
- [LLM interface and usage](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/base.py): `src/ado_defect_analysis/llm/base.py`
- [OpenAI-compatible transport](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/openai_compatible.py): `src/ado_defect_analysis/llm/openai_compatible.py`
- [Azure provider](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/azure_provider.py): `src/ado_defect_analysis/llm/azure_provider.py`
- [Groq provider](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/llm/groq_provider.py): `src/ado_defect_analysis/llm/groq_provider.py`
- [Configuration](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/config.py): `src/ado_defect_analysis/config.py`
- [Credential store](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/secrets.py): `src/ado_defect_analysis/secrets.py`
- [Retrying HTTP session](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/http.py): `src/ado_defect_analysis/http.py`

### Persistence and results

- [Defect store](https://github.com/rathna070-ai/ado-llm-defect-analyzer/blob/main/src/ado_defect_analysis/storage.py): `src/ado_defect_analysis/storage.py`

### Other components

- **Operator**
- **Azure DevOps**
- **ADO export file**
- **LLM service**
- **SQLite database**
- **CSV/XLSX and review outputs**

## Connections

- Operator → CLI: runs commands (evidence: `README.md`)
- Operator → Streamlit app: uses dashboard (evidence: `README.md`)
- CLI → Fetch stage: dispatches fetch (evidence: `src/ado_defect_analysis/cli.py`)
- CLI → Categorization stage: dispatches categorize (evidence: `src/ado_defect_analysis/cli.py`)
- CLI → Narrative report: dispatches report (evidence: `src/ado_defect_analysis/cli.py`)
- CLI → BI export: dispatches export (evidence: `src/ado_defect_analysis/cli.py`)
- CLI → Configuration: loads settings (evidence: `src/ado_defect_analysis/cli.py`)
- Streamlit app → Source and run view: renders (evidence: `src/ado_defect_analysis/dashboard/streamlit_app.py`)
- Streamlit app → Leadership results: renders (evidence: `src/ado_defect_analysis/dashboard/streamlit_app.py`)
- Source and run view → Fetch stage: starts source fetch (evidence: `src/ado_defect_analysis/dashboard/views/home.py`)
- Source and run view → Background run manager: starts run (evidence: `src/ado_defect_analysis/dashboard/views/home.py`)
- Background run manager → Categorization stage: runs analysis (evidence: `src/ado_defect_analysis/background.py`)
- Source and run view → Configuration: uses settings (evidence: `src/ado_defect_analysis/dashboard/views/home.py`)
- Saved-query URL parser → Azure DevOps client: resolves query reference (evidence: `src/ado_defect_analysis/ado_client.py`)
- Fetch stage → Saved-query URL parser: parses query URL (evidence: `src/ado_defect_analysis/pipeline/fetch.py`)
- Fetch stage → Azure DevOps client: fetches work items (evidence: `src/ado_defect_analysis/pipeline/fetch.py`)
- Fetch stage → Excel/CSV parser: parses export (evidence: `src/ado_defect_analysis/pipeline/fetch.py`)
- Fetch stage → Defect store: upserts defects (evidence: `src/ado_defect_analysis/pipeline/fetch.py`)
- Azure DevOps client → Azure DevOps: queries API (evidence: `src/ado_defect_analysis/ado_client.py`)
- Excel/CSV parser → ADO export file: reads file
- Azure DevOps client → Defect data models: constructs defects (evidence: `src/ado_defect_analysis/ado_client.py`)
- Excel/CSV parser → Defect data models: produces defects (evidence: `src/ado_defect_analysis/excel_source.py`)
- Categorization stage → Defect store: loads and saves (evidence: `src/ado_defect_analysis/pipeline/categorize.py`)
- Categorization stage → Provider selection: gets provider (evidence: `src/ado_defect_analysis/pipeline/categorize.py`)
- Categorization stage → LLM interface and usage: uses interface (evidence: `src/ado_defect_analysis/pipeline/categorize.py`)
- Categorization stage → Defect data models: uses defect shapes (evidence: `src/ado_defect_analysis/pipeline/categorize.py`)
- Aggregation and review metrics → Defect store: reads categorized defects (evidence: `src/ado_defect_analysis/pipeline/aggregate.py`)
- Aggregation and review metrics → CAPA metrics: uses metrics (evidence: `src/ado_defect_analysis/pipeline/aggregate.py`)
- Narrative report → Aggregation and review metrics: builds summary input (evidence: `src/ado_defect_analysis/pipeline/report.py`)
- Narrative report → Provider selection: gets provider (evidence: `src/ado_defect_analysis/pipeline/report.py`)
- BI export → Aggregation and review metrics: uses aggregates (evidence: `src/ado_defect_analysis/pipeline/export.py`)
- BI export → CSV/XLSX and review outputs: writes reports (evidence: `README.md`)
- Leadership results → Aggregation and review metrics: renders metrics (evidence: `src/ado_defect_analysis/dashboard/views/results.py`)
- Leadership results → BI export: offers export (evidence: `src/ado_defect_analysis/dashboard/views/results.py`)
- Provider selection → Configuration: selects backend (evidence: `src/ado_defect_analysis/llm/factory.py`)
- Provider selection → Azure provider: constructs provider (evidence: `src/ado_defect_analysis/llm/factory.py`)
- Provider selection → Groq provider: constructs provider (evidence: `src/ado_defect_analysis/llm/factory.py`)
- Azure provider → OpenAI-compatible transport: extends transport (evidence: `src/ado_defect_analysis/llm/azure_provider.py`)
- Groq provider → OpenAI-compatible transport: uses transport (evidence: `src/ado_defect_analysis/llm/groq_provider.py`)
- OpenAI-compatible transport → LLM interface and usage: implements interface (evidence: `src/ado_defect_analysis/llm/openai_compatible.py`)
- OpenAI-compatible transport → Retrying HTTP session: builds session (evidence: `src/ado_defect_analysis/llm/openai_compatible.py`)
- OpenAI-compatible transport → LLM service: sends completions (evidence: `src/ado_defect_analysis/llm/openai_compatible.py`)
- Azure DevOps client → Retrying HTTP session: builds session (evidence: `src/ado_defect_analysis/ado_client.py`)
- Configuration → Credential store: resolves credentials (evidence: `src/ado_defect_analysis/config.py`)
- Defect store → SQLite database: reads and writes (evidence: `src/ado_defect_analysis/storage.py`)
- Background run manager → Configuration: uses settings (evidence: `src/ado_defect_analysis/background.py`)
