# tanveer-singh7/ai-customer-support architecture

> Architecture diagram of the GitHub repository tanveer-singh7/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/tanveer-singh7/ai-customer-support
- Repository: https://github.com/tanveer-singh7/ai-customer-support

## Overview

This repository implements a Gmail polling and message-ingestion service, not an evidenced AI response workflow. The main path polls Gmail, claims each message in the event table, reads it, upserts a ticket and saves the inbound message, then labels it processed and records success; failures are recorded and retried up to a limit. A separate FastAPI health endpoint is defined but is not shown driving the poller. Gmail operations and database calls are visible in the excerpts; other README detail is unavailable beyond the product name.

Main entry points: [`app/gmail.py`](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/gmail.py) (Gmail Adapter), [`app/poller.py`](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/poller.py) (Mail Poller), [`app/pipeline.py`](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/pipeline.py) (Message Pipeline), [`app/db.py`](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/db.py) (Database Access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Polling and Processing"]
  node_poller["Mail Poller<br/>[poller.py]"]
  node_pipeline["Message Pipeline<br/>[pipeline.py]"]
end

subgraph group_integrations["External Integrations"]
  node_gmail_adapter["Gmail Adapter<br/>[gmail.py]"]
  node_mail_service["Gmail Service"]
  node_db_access["Database Access<br/>[db.py]"]
  node_postgres[("Postgres")]
end

subgraph group_configuration["Configuration"]
  node_settings["Settings<br/>[config.py]"]
end

subgraph group_api["Health API"]
  node_health_api["Health Endpoint<br/>[main.py]"]
end

node_caller(("Health Caller"))

node_poller -->|"lists mail"| node_gmail_adapter
node_poller -->|"handles messages"| node_pipeline
node_pipeline -->|"reads and labels"| node_gmail_adapter
node_pipeline -->|"records events and messages"| node_db_access
node_gmail_adapter -->|"calls Gmail API"| node_mail_service
node_db_access -->|"queries and updates"| node_postgres
node_poller -->|"reads interval"| node_settings
node_gmail_adapter -->|"reads credentials"| node_settings
node_db_access -->|"reads database URL"| node_settings
node_caller -->|"requests health"| node_health_api

click node_poller "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/poller.py"
click node_pipeline "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/pipeline.py"
click node_gmail_adapter "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/gmail.py"
click node_db_access "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/db.py"
click node_settings "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/config.py"
click node_health_api "https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/main.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_poller,node_pipeline toneBlue
class node_gmail_adapter,node_mail_service,node_db_access,node_postgres toneAmber
class node_settings toneMint
class node_health_api toneRose
class node_caller toneIndigo
```

## Components

### Polling and Processing

- [Mail Poller](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/poller.py): `app/poller.py`
- [Message Pipeline](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/pipeline.py): `app/pipeline.py`

### External Integrations

- [Gmail Adapter](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/gmail.py): `app/gmail.py`
- **Gmail Service**
- [Database Access](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/db.py): `app/db.py`
- **Postgres**

### Configuration

- [Settings](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/config.py): `app/config.py`

### Health API

- [Health Endpoint](https://github.com/tanveer-singh7/ai-customer-support/blob/main/app/main.py): `app/main.py`

### Other components

- **Health Caller**

## Connections

- Mail Poller → Gmail Adapter: lists mail (evidence: `app/poller.py`)
- Mail Poller → Message Pipeline: handles messages (evidence: `app/poller.py`)
- Message Pipeline → Gmail Adapter: reads and labels (evidence: `app/pipeline.py`)
- Message Pipeline → Database Access: records events and messages (evidence: `app/pipeline.py`)
- Gmail Adapter → Gmail Service: calls Gmail API (evidence: `app/gmail.py`)
- Database Access → Postgres: queries and updates (evidence: `app/db.py`)
- Mail Poller → Settings: reads interval (evidence: `app/poller.py`)
- Gmail Adapter → Settings: reads credentials (evidence: `app/gmail.py`)
- Database Access → Settings: reads database URL (evidence: `app/db.py`)
- Health Caller → Health Endpoint: requests health (evidence: `app/main.py`)
