# cngchis/support-ticket-router architecture

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

- Interactive diagram: https://gitdiagram.com/cngchis/support-ticket-router
- Repository: https://github.com/cngchis/support-ticket-router

## Overview

Support Ticket Router generates labeled intent examples, fine-tunes a Phi-4 classifier, and serves single or batch ticket classification with intent-based team and action metadata. The runtime normalizes input, runs available local and optional OpenAI models concurrently, votes across valid predictions, then the API maps the winning intent to routing metadata. Training, evaluation, and data preparation are distinct product workflows. The README describes a generation-to-training progression, but the checked-in paths do not establish how generated raw data becomes the processed training dataset.

Main entry points: [`scripts/train.py`](https://github.com/cngchis/support-ticket-router/blob/main/scripts/train.py) (Fine-tuning and export), [`api/classifier.py`](https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py) (Input and consensus), [`api/main.py`](https://github.com/cngchis/support-ticket-router/blob/main/api/main.py) (REST endpoints), [`scripts/data_prep.py`](https://github.com/cngchis/support-ticket-router/blob/main/scripts/data_prep.py) (Dataset preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data generation"]
  node_taxonomy["Intent taxonomy"]
  node_generator["Synthetic example generation<br/>[generate_data.py]"]
  node_datasets["Dataset files"]
end

subgraph group_training["Model development"]
  node_prepared["Dataset preparation<br/>[data_prep.py]"]
  node_model_loader["Base model and LoRA<br/>[model_loader.py]"]
  node_trainer["Fine-tuning and export<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evalute.py]"]
end

subgraph group_runtime["Inference service"]
  node_api["REST endpoints<br/>[main.py]"]
  node_classifier["Input and consensus<br/>[classifier.py]"]
  node_phi["Fine-tuned Phi model<br/>[classifier.py]"]
  node_gguf["GGUF inference<br/>[classifier.py]"]
  node_openai["GPT-4o-mini<br/>[classifier.py]"]
end

subgraph group_routing["Ticket routing"]
  node_routing["Team and action maps<br/>[config.py]"]
end

node_customer(("Ticket submitter"))
node_teams(("Support teams"))

node_customer -->|"submits ticket"| node_api
node_api -->|"calls predict"| node_classifier
node_classifier -->|"runs inference"| node_phi
node_classifier -->|"runs inference"| node_gguf
node_classifier -.->|"optionally queries"| node_openai
node_api -->|"maps intent"| node_routing
node_routing -->|"routes ticket"| node_teams
node_generator -->|"reads definitions"| node_taxonomy
node_generator -->|"generates examples"| node_openai
node_prepared -->|"imports helper"| node_model_loader
node_trainer -->|"loads and splits"| node_prepared
node_trainer -->|"loads and adapts"| node_model_loader
node_trainer -->|"writes splits"| node_datasets
node_evaluation -->|"uses prompt formatter"| node_prepared
node_evaluation -.->|"reads test data"| node_datasets
node_trainer -.->|"exports model"| node_phi

click node_api "https://github.com/cngchis/support-ticket-router/blob/main/api/main.py"
click node_classifier "https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py"
click node_phi "https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py"
click node_gguf "https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py"
click node_openai "https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py"
click node_routing "https://github.com/cngchis/support-ticket-router/blob/main/api/config.py"
click node_taxonomy "https://github.com/cngchis/support-ticket-router/blob/main/data/intent_taxonomy.json"
click node_generator "https://github.com/cngchis/support-ticket-router/blob/main/scripts/generate_data.py"
click node_prepared "https://github.com/cngchis/support-ticket-router/blob/main/scripts/data_prep.py"
click node_model_loader "https://github.com/cngchis/support-ticket-router/blob/main/scripts/model_loader.py"
click node_trainer "https://github.com/cngchis/support-ticket-router/blob/main/scripts/train.py"
click node_evaluation "https://github.com/cngchis/support-ticket-router/blob/main/scripts/evalute.py"
click node_datasets "https://github.com/cngchis/support-ticket-router/tree/main/data/processed"

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_taxonomy,node_generator,node_datasets toneBlue
class node_prepared,node_model_loader,node_trainer,node_evaluation toneAmber
class node_api,node_classifier,node_phi,node_gguf,node_openai toneMint
class node_routing toneRose
class node_customer,node_teams toneIndigo
```

## Components

### Data generation

- [Intent taxonomy](https://github.com/cngchis/support-ticket-router/blob/main/data/intent_taxonomy.json): `data/intent_taxonomy.json`
- [Synthetic example generation](https://github.com/cngchis/support-ticket-router/blob/main/scripts/generate_data.py): `scripts/generate_data.py`
- [Dataset files](https://github.com/cngchis/support-ticket-router/tree/main/data/processed): `data/processed`

### Model development

- [Dataset preparation](https://github.com/cngchis/support-ticket-router/blob/main/scripts/data_prep.py): `scripts/data_prep.py`
- [Base model and LoRA](https://github.com/cngchis/support-ticket-router/blob/main/scripts/model_loader.py): `scripts/model_loader.py`
- [Fine-tuning and export](https://github.com/cngchis/support-ticket-router/blob/main/scripts/train.py): `scripts/train.py`
- [Model evaluation](https://github.com/cngchis/support-ticket-router/blob/main/scripts/evalute.py): `scripts/evalute.py`

### Inference service

- [REST endpoints](https://github.com/cngchis/support-ticket-router/blob/main/api/main.py): `api/main.py`
- [Input and consensus](https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py): `api/classifier.py`
- [Fine-tuned Phi model](https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py): `api/classifier.py`
- [GGUF inference](https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py): `api/classifier.py`
- [GPT-4o-mini](https://github.com/cngchis/support-ticket-router/blob/main/api/classifier.py): `api/classifier.py`

### Ticket routing

- [Team and action maps](https://github.com/cngchis/support-ticket-router/blob/main/api/config.py): `api/config.py`

### Other components

- **Ticket submitter**
- **Support teams**

## Connections

- Ticket submitter → REST endpoints: submits ticket (evidence: `README.md`)
- REST endpoints → Input and consensus: calls predict (evidence: `api/main.py`)
- Input and consensus → Fine-tuned Phi model: runs inference (evidence: `api/classifier.py`)
- Input and consensus → GGUF inference: runs inference (evidence: `api/classifier.py`)
- Input and consensus → GPT-4o-mini: optionally queries (evidence: `api/classifier.py`)
- REST endpoints → Team and action maps: maps intent (evidence: `api/main.py`)
- Team and action maps → Support teams: routes ticket (evidence: `README.md`)
- Synthetic example generation → Intent taxonomy: reads definitions (evidence: `scripts/generate_data.py`)
- Synthetic example generation → GPT-4o-mini: generates examples (evidence: `scripts/generate_data.py`)
- Dataset preparation → Base model and LoRA: imports helper (evidence: `scripts/data_prep.py`)
- Fine-tuning and export → Dataset preparation: loads and splits (evidence: `scripts/train.py`)
- Fine-tuning and export → Base model and LoRA: loads and adapts (evidence: `scripts/train.py`)
- Fine-tuning and export → Dataset files: writes splits (evidence: `scripts/train.py`)
- Model evaluation → Dataset preparation: uses prompt formatter (evidence: `scripts/evalute.py`)
- Model evaluation → Dataset files: reads test data
- Fine-tuning and export → Fine-tuned Phi model: exports model
