# lakshyapanwar05/troubleshoot-engine architecture

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

- Interactive diagram: https://gitdiagram.com/lakshyapanwar05/troubleshoot-engine
- Repository: https://github.com/lakshyapanwar05/troubleshoot-engine

## Overview

Smart Guided Troubleshooting Engine is an offline-first Python service that turns a customer complaint and optional support-document (SIIS) text into a validated troubleshooting plan. The main workflow enters through the API, normalizes the query, processes relevant support sections into classified and ordered actions, matches actionable steps to catalog deeplinks, then applies a safety and formatting gate before returning the response. The README documents additional semantic caching, paraphrase handling, and deterministic rule-based output. Connections for unsampled implementation details are limited to documented capabilities or the orchestrator’s indexed references.

Main entry points: [`app/pipeline.py`](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/pipeline.py) (Pipeline Orchestrator), [`app/main.py`](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/main.py) (Troubleshoot API), [`app/loader.py`](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/loader.py) (Data Loader), [`app/classify.py`](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/classify.py) (Action Classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_api_service["Troubleshoot API<br/>[main.py]"]
  node_request_contract["Request Contract<br/>[envelope.py]"]
  node_response_schema["Plan Schema<br/>[schema.py]"]
end

subgraph group_query["Query and Support Text"]
  node_query_normalizer["Query Normalizer<br/>[normalize.py]"]
  node_support_parser["SIIS Sectioner<br/>[sectioner.py]"]
end

subgraph group_plan["Plan Construction"]
  node_planner["Pipeline Orchestrator<br/>[pipeline.py]"]
  node_step_extractor["Step Extractor<br/>[steps.py]"]
  node_action_classifier["Action Classifier<br/>[classify.py]"]
  node_catalog_matcher["Deeplink Matcher<br/>[deeplinks.py]"]
  node_hybrid_search["Hybrid Retrieval<br/>[retrieval.py]"]
  node_text_formatter["Text Rule Formatter<br/>[textrules.py]"]
  node_action_orderer["Action Orderer<br/>[ordering.py]"]
end

subgraph group_knowledge["Rules and Catalog"]
  node_data_loader["Data Loader<br/>[loader.py]"]
  node_support_data["SIIS Articles"]
  node_rule_data["Classification Rules<br/>[categories.yaml]"]
  node_symptom_rules["Symptom Rules<br/>[symptoms.yaml]"]
  node_deeplink_data["Deeplink Catalog<br/>[deeplinks.json]"]
end

subgraph group_safety["Cache and Validation"]
  node_variation_generator["Query Variations<br/>[variations.py]"]
  node_plan_cache[("Semantic Plan Cache<br/>[cache.py]")]
  node_final_gate["Safety Validator<br/>[validators.py]"]
  node_optional_llm["Optional LLM Stub<br/>[llm_optional.py]"]
end

node_customer(("Customer"))

node_customer -->|"submits query"| node_api_service
node_api_service -->|"parses request"| node_request_contract
node_api_service -->|"calls pipeline"| node_planner
node_api_service -->|"loads startup articles"| node_data_loader
node_api_service -->|"uses response type"| node_response_schema
node_api_service -->|"returns plan"| node_customer
node_planner -->|"normalizes query"| node_query_normalizer
node_planner -->|"parses SIIS text"| node_support_parser
node_planner -->|"checks and updates"| node_plan_cache
node_planner -->|"loads catalog"| node_data_loader
node_planner -->|"extracts steps"| node_step_extractor
node_planner -->|"classifies actions"| node_action_classifier
node_planner -->|"matches deeplinks"| node_catalog_matcher
node_planner -->|"orders actions"| node_action_orderer
node_planner -->|"formats plan text"| node_text_formatter
node_planner -->|"validates response"| node_final_gate
node_planner -->|"generates cache variants"| node_variation_generator
node_catalog_matcher -->|"retrieves candidates"| node_hybrid_search
node_data_loader -->|"reads articles"| node_support_data
node_data_loader -->|"reads catalog"| node_deeplink_data
node_action_classifier -.->|"uses category rules"| node_rule_data
node_text_formatter -.->|"uses symptom templates"| node_symptom_rules
node_final_gate -->|"checks schema"| node_response_schema
node_optional_llm -.->|"optional request-time use"| node_planner

click node_api_service "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/main.py"
click node_request_contract "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/envelope.py"
click node_response_schema "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/schema.py"
click node_query_normalizer "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/normalize.py"
click node_support_parser "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/sectioner.py"
click node_data_loader "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/loader.py"
click node_support_data "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/data/siis_responses.json"
click node_rule_data "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/rules/categories.yaml"
click node_symptom_rules "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/rules/symptoms.yaml"
click node_deeplink_data "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/data/deeplinks.json"
click node_planner "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/pipeline.py"
click node_step_extractor "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/steps.py"
click node_action_classifier "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/classify.py"
click node_catalog_matcher "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/deeplinks.py"
click node_hybrid_search "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/retrieval.py"
click node_text_formatter "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/textrules.py"
click node_action_orderer "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/ordering.py"
click node_variation_generator "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/variations.py"
click node_plan_cache "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/cache.py"
click node_final_gate "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/validators.py"
click node_optional_llm "https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/llm_optional.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_service,node_request_contract,node_response_schema toneBlue
class node_query_normalizer,node_support_parser toneAmber
class node_planner,node_step_extractor,node_action_classifier,node_catalog_matcher,node_hybrid_search,node_text_formatter,node_action_orderer toneMint
class node_data_loader,node_support_data,node_rule_data,node_symptom_rules,node_deeplink_data toneRose
class node_variation_generator,node_plan_cache,node_final_gate,node_optional_llm,node_customer toneIndigo
```

## Components

### Service API

- [Troubleshoot API](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/main.py): `app/main.py`
- [Request Contract](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/envelope.py): `app/envelope.py`
- [Plan Schema](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/schema.py): `schema.py`

### Query and Support Text

- [Query Normalizer](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/normalize.py): `app/normalize.py`
- [SIIS Sectioner](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/sectioner.py): `app/sectioner.py`

### Plan Construction

- [Pipeline Orchestrator](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/pipeline.py): `app/pipeline.py`
- [Step Extractor](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/steps.py): `app/steps.py`
- [Action Classifier](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/classify.py): `app/classify.py`
- [Deeplink Matcher](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/deeplinks.py): `app/deeplinks.py`
- [Hybrid Retrieval](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/retrieval.py): `app/retrieval.py`
- [Text Rule Formatter](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/textrules.py): `app/textrules.py`
- [Action Orderer](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/ordering.py): `app/ordering.py`

### Rules and Catalog

- [Data Loader](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/loader.py): `app/loader.py`
- [SIIS Articles](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/data/siis_responses.json): `data/siis_responses.json`
- [Classification Rules](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/rules/categories.yaml): `rules/categories.yaml`
- [Symptom Rules](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/rules/symptoms.yaml): `rules/symptoms.yaml`
- [Deeplink Catalog](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/data/deeplinks.json): `data/deeplinks.json`

### Cache and Validation

- [Query Variations](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/variations.py): `app/variations.py`
- [Semantic Plan Cache](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/cache.py): `app/cache.py`
- [Safety Validator](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/validators.py): `app/validators.py`
- [Optional LLM Stub](https://github.com/lakshyapanwar05/troubleshoot-engine/blob/main/app/llm_optional.py): `app/llm_optional.py`

### Other components

- **Customer**

## Connections

- Customer → Troubleshoot API: submits query (evidence: `app/main.py`)
- Troubleshoot API → Request Contract: parses request (evidence: `app/main.py`)
- Troubleshoot API → Pipeline Orchestrator: calls pipeline (evidence: `app/main.py`)
- Troubleshoot API → Data Loader: loads startup articles (evidence: `app/main.py`)
- Troubleshoot API → Plan Schema: uses response type (evidence: `app/main.py`)
- Troubleshoot API → Customer: returns plan (evidence: `app/main.py`)
- Pipeline Orchestrator → Query Normalizer: normalizes query (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → SIIS Sectioner: parses SIIS text (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Semantic Plan Cache: checks and updates (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Data Loader: loads catalog (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Step Extractor: extracts steps (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Action Classifier: classifies actions (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Deeplink Matcher: matches deeplinks (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Action Orderer: orders actions (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Text Rule Formatter: formats plan text (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Safety Validator: validates response (evidence: `app/pipeline.py`)
- Pipeline Orchestrator → Query Variations: generates cache variants (evidence: `app/pipeline.py`)
- Deeplink Matcher → Hybrid Retrieval: retrieves candidates (evidence: `app/deeplinks.py`)
- Data Loader → SIIS Articles: reads articles (evidence: `app/loader.py`)
- Data Loader → Deeplink Catalog: reads catalog (evidence: `app/loader.py`)
- Action Classifier → Classification Rules: uses category rules (evidence: `README.md`)
- Text Rule Formatter → Symptom Rules: uses symptom templates (evidence: `README.md`)
- Safety Validator → Plan Schema: checks schema (evidence: `app/validators.py`)
- Optional LLM Stub → Pipeline Orchestrator: optional request-time use