# arshadak1/ai-customer-support architecture

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

- Interactive diagram: https://gitdiagram.com/arshadak1/ai-customer-support
- Repository: https://github.com/arshadak1/ai-customer-support

## Overview

This is an AI-assisted customer-support service: it polls Gmail, screens and classifies incoming conversations, drafts or escalates replies, and records tickets and processing events. A FastAPI service exposes those records and knowledge-base editing to a password-protected dashboard. The dashboard covers activity, conversations, knowledge-base maintenance, and login. The excerpts show the backend workflow and dashboard composition; frontend-to-API wiring is not shown, so that relationship is marked unverified. The repository also includes golden-email evaluation cases, but their runtime role is separate from customer support.

Main entry points: [`dashboard/src/App.tsx`](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/App.tsx) (Dashboard shell), [`app/pipeline.py`](https://github.com/arshadak1/ai-customer-support/blob/main/app/pipeline.py) (Message workflow), [`app/ai/decide.py`](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/decide.py) (Decision logic), [`app/gmail.py`](https://github.com/arshadak1/ai-customer-support/blob/main/app/gmail.py) (Gmail client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mail["Mail workflow"]
  node_gmail["Gmail client<br/>[gmail.py]"]
  node_poller["Inbox poller<br/>[poller.py]"]
  node_pipeline["Message workflow<br/>[pipeline.py]"]
  node_guards["Message guards<br/>[guards.py]"]
end

subgraph group_ai["AI decisions"]
  node_classifier["Classifier<br/>[classifier.py]"]
  node_decision["Decision logic<br/>[decide.py]"]
  node_rules["Support rules<br/>[rules.py]"]
  node_agent["Reply agent<br/>[agent.py]"]
  node_schemas["AI schemas<br/>[schemas.py]"]
  node_evals["Golden email cases<br/>[golden_emails.py]"]
end

subgraph group_service["Service and records"]
  node_api["FastAPI service<br/>[main.py]"]
  node_database[("Support records<br/>[db.py]")]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_dashboard["Support dashboard"]
  node_dashboardapp["Dashboard shell<br/>[App.tsx]"]
  node_login["Login view<br/>[login.tsx]"]
  node_events["Activity view<br/>[events.tsx]"]
  node_tickets["Conversation view<br/>[tickets.tsx]"]
  node_knowledge["Knowledge view<br/>[knowledge-base.tsx]"]
  node_dashboardapi["Dashboard API client<br/>[api.ts]"]
end

node_customer(("Email sender"))
node_gmailservice["Gmail API"]
node_browser(("Dashboard user"))

node_customer -->|"emails"| node_gmail
node_poller -->|"fetches mail"| node_gmail
node_poller -->|"dispatches messages"| node_pipeline
node_pipeline -->|"reads and replies"| node_gmail
node_pipeline -->|"checks messages"| node_guards
node_pipeline -->|"requests decision"| node_decision
node_pipeline -->|"records processing"| node_database
node_gmail -->|"calls Gmail API"| node_gmailservice
node_gmail -->|"loads credentials"| node_config
node_decision -->|"classifies thread"| node_classifier
node_decision -->|"applies rules"| node_rules
node_decision -->|"requests reply"| node_agent
node_agent -->|"reads knowledge"| node_database
node_agent -->|"loads model setting"| node_config
node_classifier -->|"loads model setting"| node_config
node_api -->|"serves and updates"| node_database
node_api -->|"starts polling"| node_poller
node_api -->|"checks login"| node_config
node_dashboardapp -->|"shows when logged out"| node_login
node_dashboardapp -->|"renders activity"| node_events
node_dashboardapp -->|"renders conversations"| node_tickets
node_dashboardapp -->|"renders knowledge"| node_knowledge
node_dashboardapp -->|"checks session"| node_dashboardapi
node_browser -->|"uses dashboard"| node_dashboardapp
node_dashboardapi -.->|"calls service"| node_api
node_evals -.->|"evaluation input"| node_decision

click node_gmail "https://github.com/arshadak1/ai-customer-support/blob/main/app/gmail.py"
click node_poller "https://github.com/arshadak1/ai-customer-support/blob/main/app/poller.py"
click node_pipeline "https://github.com/arshadak1/ai-customer-support/blob/main/app/pipeline.py"
click node_guards "https://github.com/arshadak1/ai-customer-support/blob/main/app/guards.py"
click node_classifier "https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/classifier.py"
click node_decision "https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/decide.py"
click node_rules "https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/rules.py"
click node_agent "https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/agent.py"
click node_schemas "https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/schemas.py"
click node_evals "https://github.com/arshadak1/ai-customer-support/blob/main/evals/golden_emails.py"
click node_api "https://github.com/arshadak1/ai-customer-support/blob/main/app/main.py"
click node_database "https://github.com/arshadak1/ai-customer-support/blob/main/app/db.py"
click node_config "https://github.com/arshadak1/ai-customer-support/blob/main/app/config.py"
click node_dashboardapp "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/App.tsx"
click node_login "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/login.tsx"
click node_events "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/events.tsx"
click node_tickets "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/tickets.tsx"
click node_knowledge "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/knowledge-base.tsx"
click node_dashboardapi "https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/lib/api.ts"

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_gmail,node_poller,node_pipeline,node_guards,node_browser toneBlue
class node_classifier,node_decision,node_rules,node_agent,node_schemas,node_evals toneAmber
class node_api,node_database,node_config,node_gmailservice toneMint
class node_dashboardapp,node_login,node_events,node_tickets,node_knowledge,node_dashboardapi toneRose
class node_customer toneIndigo
```

## Components

### Mail workflow

- [Gmail client](https://github.com/arshadak1/ai-customer-support/blob/main/app/gmail.py): `app/gmail.py`
- [Inbox poller](https://github.com/arshadak1/ai-customer-support/blob/main/app/poller.py): `app/poller.py`
- [Message workflow](https://github.com/arshadak1/ai-customer-support/blob/main/app/pipeline.py): `app/pipeline.py`
- [Message guards](https://github.com/arshadak1/ai-customer-support/blob/main/app/guards.py): `app/guards.py`

### AI decisions

- [Classifier](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/classifier.py): `app/ai/classifier.py`
- [Decision logic](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/decide.py): `app/ai/decide.py`
- [Support rules](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/rules.py): `app/ai/rules.py`
- [Reply agent](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/agent.py): `app/ai/agent.py`
- [AI schemas](https://github.com/arshadak1/ai-customer-support/blob/main/app/ai/schemas.py): `app/ai/schemas.py`
- [Golden email cases](https://github.com/arshadak1/ai-customer-support/blob/main/evals/golden_emails.py): `evals/golden_emails.py`

### Service and records

- [FastAPI service](https://github.com/arshadak1/ai-customer-support/blob/main/app/main.py): `app/main.py`
- [Support records](https://github.com/arshadak1/ai-customer-support/blob/main/app/db.py): `app/db.py`
- [Runtime settings](https://github.com/arshadak1/ai-customer-support/blob/main/app/config.py): `app/config.py`

### Support dashboard

- [Dashboard shell](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Login view](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/login.tsx): `dashboard/src/pages/login.tsx`
- [Activity view](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/events.tsx): `dashboard/src/pages/events.tsx`
- [Conversation view](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/tickets.tsx): `dashboard/src/pages/tickets.tsx`
- [Knowledge view](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/pages/knowledge-base.tsx): `dashboard/src/pages/knowledge-base.tsx`
- [Dashboard API client](https://github.com/arshadak1/ai-customer-support/blob/main/dashboard/src/lib/api.ts): `dashboard/src/lib/api.ts`

### Other components

- **Email sender**
- **Gmail API**
- **Dashboard user**

## Connections

- Email sender → Gmail client: emails
- Inbox poller → Gmail client: fetches mail (evidence: `app/poller.py`)
- Inbox poller → Message workflow: dispatches messages (evidence: `app/poller.py`)
- Message workflow → Gmail client: reads and replies (evidence: `app/pipeline.py`)
- Message workflow → Message guards: checks messages (evidence: `app/pipeline.py`)
- Message workflow → Decision logic: requests decision (evidence: `app/pipeline.py`)
- Message workflow → Support records: records processing (evidence: `app/pipeline.py`)
- Gmail client → Gmail API: calls Gmail API (evidence: `app/gmail.py`)
- Gmail client → Runtime settings: loads credentials (evidence: `app/gmail.py`)
- Decision logic → Classifier: classifies thread (evidence: `app/ai/decide.py`)
- Decision logic → Support rules: applies rules (evidence: `app/ai/decide.py`)
- Decision logic → Reply agent: requests reply (evidence: `app/ai/decide.py`)
- Reply agent → Support records: reads knowledge (evidence: `app/ai/agent.py`)
- Reply agent → Runtime settings: loads model setting (evidence: `app/ai/agent.py`)
- Classifier → Runtime settings: loads model setting (evidence: `app/ai/classifier.py`)
- FastAPI service → Support records: serves and updates (evidence: `app/main.py`)
- FastAPI service → Inbox poller: starts polling (evidence: `app/main.py`)
- FastAPI service → Runtime settings: checks login (evidence: `app/main.py`)
- Dashboard shell → Login view: shows when logged out (evidence: `dashboard/src/App.tsx`)
- Dashboard shell → Activity view: renders activity (evidence: `dashboard/src/App.tsx`)
- Dashboard shell → Conversation view: renders conversations (evidence: `dashboard/src/App.tsx`)
- Dashboard shell → Knowledge view: renders knowledge (evidence: `dashboard/src/App.tsx`)
- Dashboard shell → Dashboard API client: checks session (evidence: `dashboard/src/App.tsx`)
- Dashboard user → Dashboard shell: uses dashboard
- Dashboard API client → FastAPI service: calls service
- Golden email cases → Decision logic: evaluation input
