# aryanchougule/supportiq architecture

> Architecture diagram of the GitHub repository aryanchougule/supportiq, 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/aryanchougule/supportiq
- Repository: https://github.com/aryanchougule/supportiq

## Overview

SupportIQ loads and validates a support-ticket CSV into DuckDB, then serves analytics through FastAPI and a mounted Gradio interface. For natural-language questions, the answer service asks Gemini for a schema-constrained plan, runs deterministic DuckDB queries or anomaly detection, and asks Gemini to explain the computed result. Separate REST routes expose health, summary, and anomaly results. The graph reflects the shown application wiring and README-described capabilities; the Gradio excerpt is partial, so unshown UI interactions are not inferred.

Main entry points: [`app/main.py`](https://github.com/aryanchougule/supportiq/blob/main/app/main.py) (App setup), [`app/llm/gemini_client.py`](https://github.com/aryanchougule/supportiq/blob/main/app/llm/gemini_client.py) (Gemini planner and explainer), [`app/services/answer_service.py`](https://github.com/aryanchougule/supportiq/blob/main/app/services/answer_service.py) (Answer orchestration), [`app/data/database.py`](https://github.com/aryanchougule/supportiq/blob/main/app/data/database.py) (Ticket database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entrypoints"]
  node_main["App setup<br/>[main.py]"]
  node_query_api["Query API<br/>[routes_query.py]"]
  node_health_api["Health and summary API<br/>[routes_health.py]"]
  node_anomaly_api["Anomaly API<br/>[routes_anomaly.py]"]
  node_gradio["Gradio UI<br/>[gradio_app.py]"]
end

subgraph group_ingest["Ticket data"]
  node_validator["CSV validation<br/>[validator.py]"]
  node_database[("Ticket database<br/>[database.py]")]
end

subgraph group_query["Query and answers"]
  node_answer["Answer orchestration<br/>[answer_service.py]"]
  node_executor["Query executor<br/>[query_executor.py]"]
end

subgraph group_anomaly["Anomaly analytics"]
  node_anomaly_service["Anomaly detection<br/>[anomaly_service.py]"]
end

subgraph group_platform["Configuration and AI"]
  node_planner["Gemini planner and explainer<br/>[gemini_client.py]"]
  node_prompts["Planner prompts<br/>[prompts.py]"]
  node_schemas["Query-plan schemas<br/>[schemas.py]"]
  node_config["Application settings<br/>[config.py]"]
  node_logging["Logging setup<br/>[logging_config.py]"]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}

node_user -->|"asks questions"| node_gradio
node_user -->|"submits queries"| node_query_api
node_user -->|"requests anomalies"| node_anomaly_api
node_main -->|"loads CSV"| node_validator
node_main -->|"loads tickets"| node_database
node_main -->|"mounts route"| node_query_api
node_main -->|"mounts route"| node_health_api
node_main -->|"mounts route"| node_anomaly_api
node_main -->|"mounts UI"| node_gradio
node_main -->|"loads settings"| node_config
node_main -->|"sets up logging"| node_logging
node_query_api -->|"calls answer"| node_answer
node_gradio -->|"submits question"| node_answer
node_health_api -->|"checks and summarizes"| node_database
node_anomaly_api -->|"requests detection"| node_anomaly_service
node_answer -->|"plans and explains"| node_planner
node_answer -->|"executes plan"| node_executor
node_answer -->|"dispatches detection"| node_anomaly_service
node_planner -->|"uses prompt"| node_prompts
node_planner -->|"validates plan"| node_schemas
node_planner -->|"uses settings"| node_config
node_planner -->|"requests plans and explanations"| node_gemini
node_executor -->|"queries tickets"| node_database
node_anomaly_service -->|"reads tickets"| node_database

click node_main "https://github.com/aryanchougule/supportiq/blob/main/app/main.py"
click node_query_api "https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_query.py"
click node_health_api "https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_health.py"
click node_anomaly_api "https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_anomaly.py"
click node_gradio "https://github.com/aryanchougule/supportiq/blob/main/app/ui/gradio_app.py"
click node_validator "https://github.com/aryanchougule/supportiq/blob/main/app/data/validator.py"
click node_database "https://github.com/aryanchougule/supportiq/blob/main/app/data/database.py"
click node_answer "https://github.com/aryanchougule/supportiq/blob/main/app/services/answer_service.py"
click node_planner "https://github.com/aryanchougule/supportiq/blob/main/app/llm/gemini_client.py"
click node_prompts "https://github.com/aryanchougule/supportiq/blob/main/app/llm/prompts.py"
click node_schemas "https://github.com/aryanchougule/supportiq/blob/main/app/llm/schemas.py"
click node_executor "https://github.com/aryanchougule/supportiq/blob/main/app/services/query_executor.py"
click node_anomaly_service "https://github.com/aryanchougule/supportiq/blob/main/app/services/anomaly_service.py"
click node_config "https://github.com/aryanchougule/supportiq/blob/main/app/core/config.py"
click node_logging "https://github.com/aryanchougule/supportiq/blob/main/app/core/logging_config.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_main,node_query_api,node_health_api,node_anomaly_api,node_gradio,node_user toneBlue
class node_validator,node_database toneAmber
class node_answer,node_executor toneMint
class node_anomaly_service toneRose
class node_planner,node_prompts,node_schemas,node_config,node_logging,node_gemini toneIndigo
```

## Components

### Application entrypoints

- [App setup](https://github.com/aryanchougule/supportiq/blob/main/app/main.py): `app/main.py`
- [Query API](https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_query.py): `app/api/routes_query.py`
- [Health and summary API](https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_health.py): `app/api/routes_health.py`
- [Anomaly API](https://github.com/aryanchougule/supportiq/blob/main/app/api/routes_anomaly.py): `app/api/routes_anomaly.py`
- [Gradio UI](https://github.com/aryanchougule/supportiq/blob/main/app/ui/gradio_app.py): `app/ui/gradio_app.py`

### Ticket data

- [CSV validation](https://github.com/aryanchougule/supportiq/blob/main/app/data/validator.py): `app/data/validator.py`
- [Ticket database](https://github.com/aryanchougule/supportiq/blob/main/app/data/database.py): `app/data/database.py`

### Query and answers

- [Answer orchestration](https://github.com/aryanchougule/supportiq/blob/main/app/services/answer_service.py): `app/services/answer_service.py`
- [Query executor](https://github.com/aryanchougule/supportiq/blob/main/app/services/query_executor.py): `app/services/query_executor.py`

### Anomaly analytics

- [Anomaly detection](https://github.com/aryanchougule/supportiq/blob/main/app/services/anomaly_service.py): `app/services/anomaly_service.py`

### Configuration and AI

- [Gemini planner and explainer](https://github.com/aryanchougule/supportiq/blob/main/app/llm/gemini_client.py): `app/llm/gemini_client.py`
- [Planner prompts](https://github.com/aryanchougule/supportiq/blob/main/app/llm/prompts.py): `app/llm/prompts.py`
- [Query-plan schemas](https://github.com/aryanchougule/supportiq/blob/main/app/llm/schemas.py): `app/llm/schemas.py`
- [Application settings](https://github.com/aryanchougule/supportiq/blob/main/app/core/config.py): `app/core/config.py`
- [Logging setup](https://github.com/aryanchougule/supportiq/blob/main/app/core/logging_config.py): `app/core/logging_config.py`

### Other components

- **User**
- **Google Gemini**

## Connections

- User → Gradio UI: asks questions (evidence: `README.md`)
- User → Query API: submits queries (evidence: `README.md`)
- User → Anomaly API: requests anomalies (evidence: `README.md`)
- App setup → CSV validation: loads CSV (evidence: `app/main.py`)
- App setup → Ticket database: loads tickets (evidence: `app/main.py`)
- App setup → Query API: mounts route (evidence: `app/main.py`)
- App setup → Health and summary API: mounts route (evidence: `app/main.py`)
- App setup → Anomaly API: mounts route (evidence: `app/main.py`)
- App setup → Gradio UI: mounts UI (evidence: `app/main.py`)
- App setup → Application settings: loads settings (evidence: `app/main.py`)
- App setup → Logging setup: sets up logging (evidence: `app/main.py`)
- Query API → Answer orchestration: calls answer (evidence: `app/api/routes_query.py`)
- Gradio UI → Answer orchestration: submits question (evidence: `app/ui/gradio_app.py`)
- Health and summary API → Ticket database: checks and summarizes (evidence: `app/api/routes_health.py`)
- Anomaly API → Anomaly detection: requests detection (evidence: `app/api/routes_anomaly.py`)
- Answer orchestration → Gemini planner and explainer: plans and explains (evidence: `app/services/answer_service.py`)
- Answer orchestration → Query executor: executes plan (evidence: `app/services/answer_service.py`)
- Answer orchestration → Anomaly detection: dispatches detection (evidence: `app/services/answer_service.py`)
- Gemini planner and explainer → Planner prompts: uses prompt (evidence: `app/llm/gemini_client.py`)
- Gemini planner and explainer → Query-plan schemas: validates plan (evidence: `app/llm/gemini_client.py`)
- Gemini planner and explainer → Application settings: uses settings (evidence: `app/llm/gemini_client.py`)
- Gemini planner and explainer → Google Gemini: requests plans and explanations (evidence: `app/llm/gemini_client.py`)
- Query executor → Ticket database: queries tickets (evidence: `app/services/query_executor.py`)
- Anomaly detection → Ticket database: reads tickets (evidence: `app/services/anomaly_service.py`)
