# tanujkumar24/customer_ticket_resolver_with_ai architecture

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

- Interactive diagram: https://gitdiagram.com/tanujkumar24/customer_ticket_resolver_with_ai
- Repository: https://github.com/tanujkumar24/customer_ticket_resolver_with_ai

## Overview

##### Project type and purpose
- This is a full-stack Python application built with Streamlit as the UI layer and a lightweight backend “MCP” (Multi-Class Predictor) model server.
- Purpose: Automate customer-support ticket processing by classifying intent/urgency, generating summaries or reply drafts via OpenAI GPT, and optionally logging tickets to Google Sheets or sending emails.

##### File structure
Top-level files and directories:
- main.py – Streamlit frontend entry point
- mcp_server.py – Flask/FastAPI-style backend serving NLP model predictions
- register_ticket.py/test_euri.py – utility or test scripts
- tools/ – helper modules:
– classify_ticket.py – intent/urgency classifier
– generate_reply.py – wraps GPT API calls
– gmail_sender.py – handles email notifications
– sheet_connector.py – Google Sheets logging
- google_creds.json – credentials for Google API
- pyproject.toml, requirements.txt, .python-version, uv.lock – build/configuration/dependency lock

##### Extract architecture hints from the README
- Workflow graph:
Customer → Streamlit Form → MCP Server → LLM Response Generator → Display
↓
Google Sheet Logger
- Key components called out: Streamlit UI, MCP server, LLM integration, Google API integration.

##### Main components
a. User Agent (Web Browser)
b. Streamlit Frontend (main.py)
c. MCP Model Server (mcp_server.py + classify_ticket.py)
d. LLM Service (OpenAI GPT through generate_reply.py)
e. Persistence/Logging
- Google Sheets via sheet_connector.py
- Optionally emails via gmail_sender.py
f. Auxiliary/Test Modules (register_ticket.py, test_euri.py)
g. External services/APIs: OpenAI API, Google API, SMTP

##### Relationships & Data Flows
- Streamlit → MCP Server: “gRPC/REST request with raw text”
- MCP Server → classify_ticket module: “internal function call”
- MCP Server → LLM Service: “calls generate_reply.py → OpenAI GPT API”
- LLM Response → MCP Server → Streamlit for display
- Conditional branches:
- MCP Server → sheet_connector → Google Sheets
- Streamlit or MCP Server → gmail_sender → SMTP server
- Test scripts operate offline or via wrapper calls

##### Architectural patterns & design principles
- Separation of concerns: UI vs. ML inference vs. external integration
- Modular codebase (tools/ directory for pluggable functionality)
- Service-oriented backend (MCP as independent microservice)
- External API abstraction layers (generate_reply.py, sheet_connector.py, gmail_sender.py)

##### Technology & Framework callouts
- Frontend: Streamlit framework (main.py)
- Backend: Python microservice, could be FastAPI or Flask in mcp_server.py
- NLP/AI: custom classifier + OpenAI GPT via REST
- Data Logging: Google Sheets API (sheet_connector.py)
- Email: SMTP integration (gmail_sender.py)
- Testing: pytest or custom script (test_euri.py)
- Deployment hints: supports Docker/Kubernetes, Streamlit Cloud, Heroku

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UA["User Agent (Web Browser)"]:::external
        Streamlit["Streamlit UI\n(main.py)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        MCP["MCP Model Server\n(mcp_server.py)"]:::backend
        subgraph "MCP Internal"
            direction TB
            Classifier["Intent/Urgency Classifier\n(tools/classify_ticket.py)"]:::backend
            ReplyGen["LLM Response Generator\n(tools/generate_reply.py)"]:::backend
        end
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        OpenAIAPI["OpenAI GPT API"]:::external
        GoogleSheetsAPI["Google Sheets API"]:::external
        SMTPServer["SMTP Server"]:::external
        Creds["Google API Credentials\n(google_creds.json)"]:::external
    end

    %% Auxiliary Modules
    subgraph "Auxiliary / Test Modules"
        direction TB
        RegisterT["Ticket Registration Utility\n(register_ticket.py)"]:::external
        TestE2E["E2E/Test Script\n(test_euri.py)"]:::external
    end

    %% Data Flows
    UA -->|"HTTP POST/GET ticket_text"| Streamlit
    Streamlit -->|"gRPC/REST raw_text"| MCP
    MCP -->|"function call"| Classifier
    MCP -->|"invoke"| ReplyGen
    ReplyGen -->|"REST reply_text"| OpenAIAPI
    OpenAIAPI -->|"reply_text"| ReplyGen
    ReplyGen -->|"response"| MCP
    MCP -->|"response"| Streamlit

    %% Optional Flows
    MCP -.->|"async log_data"| SheetConnector["Google Sheets Logger\n(tools/sheet_connector.py)"]:::backend
    SheetConnector -->|"REST log_request"| GoogleSheetsAPI
    Streamlit -.->|"async email_data"| GmailSender["Email Sender\n(tools/gmail_sender.py)"]:::backend
    GmailSender -->|"SMTP send"| SMTPServer

    %% Configuration Link
    Creds --> GoogleSheetsAPI

    %% Click Events
    click Streamlit "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/main.py"
    click MCP "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/mcp_server.py"
    click Classifier "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/tools/classify_ticket.py"
    click ReplyGen "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/tools/generate_reply.py"
    click SheetConnector "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/tools/sheet_connector.py"
    click GmailSender "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/tools/gmail_sender.py"
    click Creds "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/google_creds.json"
    click RegisterT "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/register_ticket.py"
    click TestE2E "https://github.com/tanujkumar24/customer_ticket_resolver_with_ai/blob/main/test_euri.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003366;
    classDef backend  fill:#E6F5D0,stroke:#5C8A00,color:#3A5F00;
    classDef external fill:#F0F0F0,stroke:#CCCCCC,color:#333333;
    class Streamlit,UA external
    class MCP,Classifier,ReplyGen,SheetConnector,GmailSender backend
    class OpenAIAPI,GoogleSheetsAPI,SMTPServer,Creds external
```
