# gokul-hawk/email_tickets architecture

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

- Interactive diagram: https://gitdiagram.com/gokul-hawk/email_tickets
- Repository: https://github.com/gokul-hawk/email_tickets

## Overview

This repository implements an AI customer-support email assistant, with a LangGraph workflow for handling customer requests and a separate evaluation framework. The main path accepts an email, detects intents, checks identity, routes relevant actions, and drafts a reply; the live inbox listener can supply emails asynchronously. The README also documents ticketing, plan management, general Q&A, MongoDB storage, and evaluation. Some of those implementation details are not present in the excerpts, so those links rely on README documentation rather than inspected source.

Main entry points: [`main.py`](https://github.com/gokul-hawk/email_tickets/blob/main/main.py) (Response Generator), [`evaluation_system.py`](https://github.com/gokul-hawk/email_tickets/blob/main/evaluation_system.py) (Workflow Evaluator), [`inbox_listener.py`](https://github.com/gokul-hawk/email_tickets/blob/main/inbox_listener.py) (IMAP Inbox Listener), [`data.json`](https://github.com/gokul-hawk/email_tickets/blob/main/data.json) (Evaluation Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Email Intake"]
  node_inbox["IMAP Inbox Listener<br/>[inbox_listener.py]"]
  node_workqueue["Email Processing Queue<br/>[main.py]"]
end

subgraph group_workflow["Support Workflow"]
  node_agent["Support Agent Entry<br/>[main.py]"]
  node_router["Intent Router<br/>[main.py]"]
  node_identity["Identity Gate<br/>[main.py]"]
  node_response["Response Generator<br/>[main.py]"]
  node_mongodb[("MongoDB")]
end

subgraph group_actions["Business Actions"]
  node_refund["Refund Processor<br/>[main.py]"]
  node_issue["Issue Resolver<br/>[main.py]"]
  node_plan["Plan Manager<br/>[main.py]"]
  node_general["General Assistant<br/>[main.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evalrunner["Workflow Evaluator"]
  node_evaldata["Evaluation Dataset<br/>[data.json]"]
  node_evalreport["Static Report Generator<br/>[ev.py]"]
end

node_customer(("Customer"))
node_groq{{"Groq LLM"}}

node_customer -.->|"sends email"| node_inbox
node_inbox -->|"queues payload"| node_workqueue
node_workqueue -->|"processes email"| node_agent
node_customer -.->|"submits request"| node_agent
node_agent -->|"starts workflow"| node_router
node_router -->|"routes intents"| node_identity
node_router -->|"routes general"| node_general
node_identity -.->|"routes refund"| node_refund
node_identity -.->|"routes issue"| node_issue
node_identity -.->|"routes plan"| node_plan
node_refund -.->|"checks policy"| node_groq
node_plan -.->|"recommends tier"| node_groq
node_general -.->|"answers questions"| node_groq
node_response -.->|"generates reply"| node_groq
node_refund -.->|"provides action"| node_response
node_issue -.->|"provides ticket"| node_response
node_plan -.->|"provides plan"| node_response
node_general -.->|"provides answer"| node_response
node_response -.->|"stores result"| node_mongodb
node_evalrunner -->|"invokes workflow"| node_agent
node_evalrunner -->|"loads cases"| node_evaldata
node_evalrunner -->|"judges output"| node_groq
node_evalreport -.->|"summarizes scores"| node_evaldata

click node_inbox "https://github.com/gokul-hawk/email_tickets/blob/main/inbox_listener.py"
click node_workqueue "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_agent "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_router "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_identity "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_refund "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_issue "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_plan "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_general "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_response "https://github.com/gokul-hawk/email_tickets/blob/main/main.py"
click node_evalrunner "https://github.com/gokul-hawk/email_tickets/blob/main/evaluation_system.py"
click node_evaldata "https://github.com/gokul-hawk/email_tickets/blob/main/data.json"
click node_evalreport "https://github.com/gokul-hawk/email_tickets/blob/main/ev.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_inbox,node_workqueue toneBlue
class node_agent,node_router,node_identity,node_response,node_mongodb toneAmber
class node_refund,node_issue,node_plan,node_general toneMint
class node_evalrunner,node_evaldata,node_evalreport toneRose
class node_customer,node_groq toneIndigo
```

## Components

### Email Intake

- [IMAP Inbox Listener](https://github.com/gokul-hawk/email_tickets/blob/main/inbox_listener.py): `inbox_listener.py`
- [Email Processing Queue](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`

### Support Workflow

- [Support Agent Entry](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [Intent Router](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [Identity Gate](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [Response Generator](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- **MongoDB**

### Business Actions

- [Refund Processor](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [Issue Resolver](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [Plan Manager](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`
- [General Assistant](https://github.com/gokul-hawk/email_tickets/blob/main/main.py): `main.py`

### Evaluation

- [Workflow Evaluator](https://github.com/gokul-hawk/email_tickets/blob/main/evaluation_system.py): `evaluation_system.py`
- [Evaluation Dataset](https://github.com/gokul-hawk/email_tickets/blob/main/data.json): `data.json`
- [Static Report Generator](https://github.com/gokul-hawk/email_tickets/blob/main/ev.py): `ev.py`

### Other components

- **Customer**
- **Groq LLM**

## Connections

- Customer → IMAP Inbox Listener: sends email (evidence: `readme.md`)
- IMAP Inbox Listener → Email Processing Queue: queues payload (evidence: `inbox_listener.py`)
- Email Processing Queue → Support Agent Entry: processes email (evidence: `main.py`)
- Customer → Support Agent Entry: submits request (evidence: `readme.md`)
- Support Agent Entry → Intent Router: starts workflow (evidence: `main.py`)
- Intent Router → Identity Gate: routes intents (evidence: `main.py`)
- Intent Router → General Assistant: routes general (evidence: `main.py`)
- Identity Gate → Refund Processor: routes refund (evidence: `readme.md`)
- Identity Gate → Issue Resolver: routes issue (evidence: `readme.md`)
- Identity Gate → Plan Manager: routes plan (evidence: `readme.md`)
- Refund Processor → Groq LLM: checks policy (evidence: `readme.md`)
- Plan Manager → Groq LLM: recommends tier (evidence: `readme.md`)
- General Assistant → Groq LLM: answers questions (evidence: `readme.md`)
- Response Generator → Groq LLM: generates reply (evidence: `readme.md`)
- Refund Processor → Response Generator: provides action (evidence: `readme.md`)
- Issue Resolver → Response Generator: provides ticket (evidence: `readme.md`)
- Plan Manager → Response Generator: provides plan (evidence: `readme.md`)
- General Assistant → Response Generator: provides answer (evidence: `readme.md`)
- Response Generator → MongoDB: stores result (evidence: `readme.md`)
- Workflow Evaluator → Support Agent Entry: invokes workflow (evidence: `evaluation_system.py`)
- Workflow Evaluator → Evaluation Dataset: loads cases (evidence: `evaluation_system.py`)
- Workflow Evaluator → Groq LLM: judges output (evidence: `evaluation_system.py`)
- Static Report Generator → Evaluation Dataset: summarizes scores
