# tinsaeabreham45/match-hire-ticket-clustering architecture

> Architecture diagram of the GitHub repository tinsaeabreham45/match-hire-ticket-clustering, 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/tinsaeabreham45/match-hire-ticket-clustering
- Repository: https://github.com/tinsaeabreham45/match-hire-ticket-clustering

## Overview

This is an event-driven support-ops prototype: synthetic Slack tickets enter n8n, are validated and clustered, then a three-ticket cluster receives LLM root-cause review and a drafted report. A support lead decides whether to approve, reject, or split; approval gates Google Docs creation and engineering alerts. The map preserves the documented review, requeue, and operator paths. Workflow internals were not excerpted, so workflow relationships cite the README rather than implying unshown implementation details.

Main entry points: [`workflows/support-ticket-clustering.template.json`](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/support-ticket-clustering.template.json) (n8n Workflows), [`workflows/approval-handler.template.json`](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/approval-handler.template.json) (Approval Handler), [`scripts/ticket_simulator.py`](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/scripts/ticket_simulator.py) (Ticket Simulator), [`data/evaluation-tickets.json`](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/data/evaluation-tickets.json) (Evaluation Tickets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Ticket Intake"]
  node_simulator["Ticket Simulator"]
  node_ticket_data["Evaluation Tickets"]
  node_slack_support["Support Slack"]
  node_n8n["n8n Workflows"]
end

subgraph group_analysis["Clustering Review"]
  node_cluster_store[("Cluster Store")]
  node_cluster_review["Root-Cause Review"]
  node_llm["LLM Service"]
  node_report_drafts[("Report Drafts")]
end

subgraph group_decision["Human Decision"]
  node_approval_handler["Approval Handler"]
  node_requeue_verification["Requeue Verification"]
end

subgraph group_delivery["Reporting Delivery"]
  node_google_doc["Google Doc"]
  node_google_sheet["Google Sheet"]
  node_slack_eng["Engineering Slack"]
end

node_support_lead(("Support Lead"))

node_ticket_data -->|"loads"| node_simulator
node_simulator -->|"posts tickets"| node_slack_support
node_slack_support -->|"sends ticket event"| node_n8n
node_n8n -->|"records and clusters"| node_cluster_store
node_n8n -->|"requests verification"| node_llm
node_n8n -->|"drafts report"| node_report_drafts
node_n8n -->|"posts review"| node_slack_support
node_support_lead -->|"reviews card"| node_slack_support
node_slack_support -->|"routes decision"| node_approval_handler
node_approval_handler -->|"requeues verification"| node_requeue_verification
node_approval_handler -->|"creates on approval"| node_google_doc
node_approval_handler -->|"records approved item"| node_google_sheet
node_approval_handler -->|"notifies on approval"| node_slack_eng

click node_simulator "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/scripts/ticket_simulator.py"
click node_ticket_data "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/data/evaluation-tickets.json"
click node_n8n "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/support-ticket-clustering.template.json"
click node_cluster_store "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/docs/sql/001_cluster_schema.sql"
click node_cluster_review "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/cluster-review.template.json"
click node_report_drafts "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/docs/sql/002_report_drafts.sql"
click node_approval_handler "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/approval-handler.template.json"
click node_requeue_verification "https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/requeue-cluster-verification.template.json"

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_simulator,node_ticket_data,node_slack_support,node_n8n toneBlue
class node_cluster_store,node_cluster_review,node_llm,node_report_drafts toneAmber
class node_approval_handler,node_requeue_verification toneMint
class node_google_doc,node_google_sheet,node_slack_eng toneRose
class node_support_lead toneIndigo
```

## Components

### Ticket Intake

- [Ticket Simulator](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/scripts/ticket_simulator.py): `scripts/ticket_simulator.py`
- [Evaluation Tickets](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/data/evaluation-tickets.json): `data/evaluation-tickets.json`
- **Support Slack**
- [n8n Workflows](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/support-ticket-clustering.template.json): `workflows/support-ticket-clustering.template.json`

### Clustering Review

- [Cluster Store](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/docs/sql/001_cluster_schema.sql): `docs/sql/001_cluster_schema.sql`
- [Root-Cause Review](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/cluster-review.template.json): `workflows/cluster-review.template.json`
- **LLM Service**
- [Report Drafts](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/docs/sql/002_report_drafts.sql): `docs/sql/002_report_drafts.sql`

### Human Decision

- [Approval Handler](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/approval-handler.template.json): `workflows/approval-handler.template.json`
- [Requeue Verification](https://github.com/tinsaeabreham45/match-hire-ticket-clustering/blob/main/workflows/requeue-cluster-verification.template.json): `workflows/requeue-cluster-verification.template.json`

### Reporting Delivery

- **Google Doc**
- **Google Sheet**
- **Engineering Slack**

### Other components

- **Support Lead**

## Connections

- Evaluation Tickets → Ticket Simulator: loads (evidence: `scripts/ticket_simulator.py`)
- Ticket Simulator → Support Slack: posts tickets (evidence: `scripts/ticket_simulator.py`)
- Support Slack → n8n Workflows: sends ticket event (evidence: `README.md`)
- n8n Workflows → Cluster Store: records and clusters (evidence: `README.md`)
- n8n Workflows → LLM Service: requests verification (evidence: `README.md`)
- n8n Workflows → Report Drafts: drafts report (evidence: `README.md`)
- n8n Workflows → Support Slack: posts review (evidence: `README.md`)
- Support Lead → Support Slack: reviews card (evidence: `README.md`)
- Support Slack → Approval Handler: routes decision (evidence: `README.md`)
- Approval Handler → Requeue Verification: requeues verification (evidence: `README.md`)
- Approval Handler → Google Doc: creates on approval (evidence: `README.md`)
- Approval Handler → Google Sheet: records approved item (evidence: `README.md`)
- Approval Handler → Engineering Slack: notifies on approval (evidence: `README.md`)
