# adventh007/theme02-troubleshooting-engine architecture

> Architecture diagram of the GitHub repository adventh007/theme02-troubleshooting-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adventh007/theme02-troubleshooting-engine
- Repository: https://github.com/adventh007/theme02-troubleshooting-engine

## Overview

The product is a REST service that turns a complaint and a supplied SIIS article into a schema-validated, guided troubleshooting response with deeplinks. The documented workflow is API intake → query cleanup and article relevance scoring → grounded article-step parsing → action structuring and deeplink matching → validation and caching. The graph follows the sampled calls and README pipeline; optional LLM refinement and semantic matching are shown as separate capabilities. Several module bodies were not sampled, so uncertain connections are omitted.

Main entry points: [`app/engine.py`](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/engine.py) (Workflow engine), [`app/step_structurer.py`](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/step_structurer.py) (Action structurer), [`app/deeplink_matcher.py`](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/deeplink_matcher.py) (Deeplink matcher), [`app/main.py`](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/main.py) (Troubleshooting API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_api["Troubleshooting API<br/>[main.py]"]
end

subgraph group_flow["Troubleshooting flow"]
  node_engine["Workflow engine<br/>[engine.py]"]
  node_enrichment["Query enrichment"]
  node_relevance["Article relevance<br/>[relevance.py]"]
  node_parser["SIIS step parser<br/>[siis_parser.py]"]
  node_structurer["Action structurer<br/>[step_structurer.py]"]
  node_categorizer["Action categorizer<br/>[categorizer.py]"]
  node_schema["Response schema<br/>[schema.py]"]
end

subgraph group_matching["Matching"]
  node_matcher["Deeplink matcher"]
  node_catalog["Deeplink catalog<br/>[deeplinks.json]"]
  node_embeddings["Embedding model<br/>[embeddings.py]"]
end

subgraph group_support["Optional services"]
  node_cache[("Result cache<br/>[cache.py]")]
  node_llm["LLM refinement<br/>[llm_client.py]"]
end

node_caller(("API caller"))
node_llmservice{{"LLM provider"}}

node_caller -->|"submits query and article"| node_api
node_api -->|"invokes processing"| node_engine
node_engine -->|"cleans query"| node_enrichment
node_engine -->|"scores article"| node_relevance
node_engine -->|"parses article"| node_parser
node_engine -->|"builds actions"| node_structurer
node_engine -->|"validates response"| node_schema
node_engine -->|"reads and writes"| node_cache
node_structurer -->|"uses parsed sections"| node_parser
node_structurer -->|"matches step groups"| node_matcher
node_structurer -->|"categorizes actions"| node_categorizer
node_structurer -.->|"optionally refines steps"| node_llm
node_matcher -->|"loads entries"| node_catalog
node_matcher -->|"uses semantic scoring"| node_embeddings
node_relevance -->|"uses semantic scoring"| node_embeddings
node_llm -.->|"calls configured provider"| node_llmservice

click node_api "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/main.py"
click node_engine "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/engine.py"
click node_enrichment "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/query_enrichment.py"
click node_relevance "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/relevance.py"
click node_parser "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/siis_parser.py"
click node_structurer "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/step_structurer.py"
click node_categorizer "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/categorizer.py"
click node_schema "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/schema.py"
click node_cache "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/cache.py"
click node_matcher "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/deeplink_matcher.py"
click node_catalog "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/data/deeplinks.json"
click node_embeddings "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/embeddings.py"
click node_llm "https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/llm_client.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_api toneBlue
class node_engine,node_enrichment,node_relevance,node_parser,node_structurer,node_categorizer,node_schema toneAmber
class node_matcher,node_catalog,node_embeddings,node_caller toneMint
class node_cache,node_llm toneRose
class node_llmservice toneIndigo
```

## Components

### API

- [Troubleshooting API](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/main.py): `app/main.py`

### Troubleshooting flow

- [Workflow engine](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/engine.py): `app/engine.py`
- [Query enrichment](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/query_enrichment.py): `app/query_enrichment.py`
- [Article relevance](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/relevance.py): `app/relevance.py`
- [SIIS step parser](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/siis_parser.py): `app/siis_parser.py`
- [Action structurer](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/step_structurer.py): `app/step_structurer.py`
- [Action categorizer](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/categorizer.py): `app/categorizer.py`
- [Response schema](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/schema.py): `app/schema.py`

### Matching

- [Deeplink matcher](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/deeplink_matcher.py): `app/deeplink_matcher.py`
- [Deeplink catalog](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/data/deeplinks.json): `app/data/deeplinks.json`
- [Embedding model](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/embeddings.py): `app/embeddings.py`

### Optional services

- [Result cache](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/cache.py): `app/cache.py`
- [LLM refinement](https://github.com/adventh007/theme02-troubleshooting-engine/blob/main/app/llm_client.py): `app/llm_client.py`

### Other components

- **API caller**
- **LLM provider**

## Connections

- API caller → Troubleshooting API: submits query and article (evidence: `README.md`)
- Troubleshooting API → Workflow engine: invokes processing (evidence: `app/main.py`)
- Workflow engine → Query enrichment: cleans query (evidence: `app/engine.py`)
- Workflow engine → Article relevance: scores article (evidence: `app/engine.py`)
- Workflow engine → SIIS step parser: parses article (evidence: `app/engine.py`)
- Workflow engine → Action structurer: builds actions (evidence: `app/engine.py`)
- Workflow engine → Response schema: validates response (evidence: `app/engine.py`)
- Workflow engine → Result cache: reads and writes (evidence: `app/engine.py`)
- Action structurer → SIIS step parser: uses parsed sections (evidence: `app/step_structurer.py`)
- Action structurer → Deeplink matcher: matches step groups (evidence: `app/step_structurer.py`)
- Action structurer → Action categorizer: categorizes actions (evidence: `app/step_structurer.py`)
- Action structurer → LLM refinement: optionally refines steps (evidence: `app/step_structurer.py`)
- Deeplink matcher → Deeplink catalog: loads entries (evidence: `app/deeplink_matcher.py`)
- Deeplink matcher → Embedding model: uses semantic scoring (evidence: `app/deeplink_matcher.py`)
- Article relevance → Embedding model: uses semantic scoring (evidence: `app/relevance.py`)
- LLM refinement → LLM provider: calls configured provider (evidence: `app/llm_client.py`)
