# dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails architecture

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

- Interactive diagram: https://gitdiagram.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails
- Repository: https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails

## Overview

##### Project Type and Purpose
- This is a backend AI workflow service (FastAPI) containerized with Docker, designed to automate customer email handling and responses using an internal knowledge base and LLM.

##### High-Level Architecture Components
a. External Triggers & Clients
- Scheduler / Cron (inside container) – periodically kicks off the workflow
- Email Client (Google Gmail API) – fetch incoming emails & send replies
- External Services:
– OpenRouter API (LLM endpoint)
– Remote SQL Database (tickets)
– Google Sheets API (logging)
b. AI Agent Microservice (Docker Container)
- FastAPI App (`app/main.py`) exposes REST endpoints and houses the scheduler
- Services Layer (`app/services/`)
– email_processor.py: fetches and parses new emails
– intent_classification.py: coarse intent tagging
– create_ticket.py: writes to remote SQL DB
– log_activity.py: writes to Google Sheets
– utils.py: shared helpers
- Reasoning Engine (`app/reasoning_engine/`)
– llm.py: handles LLM API calls via LangChain/OpenRouter
– reasoning_engine.py: orchestrates classification, KB lookup, ticket decisions, response generation
– reasoning_engine_helpers.py: prompt assembly & context curation
- Knowledge Base (`app/knowledge_base/`)
– documents/ (Markdown source files)
– chroma.sqlite3 (vector DB)
– knowledge_base.py: loader & retriever
- Prompts (`app/prompts/`): reusable prompt templates for classification, retrieval, ticketing, response generation

##### Data Flow & Interactions
1. Scheduler → triggers EmailProcessor
2. EmailProcessor → Gmail API → returns new emails
3. For each email:
a. IntentClassification → tag intent
b. ReasoningEngine →
i.  Decide if KB lookup needed → query Chroma
ii. Decide if ticket required → CreateTicket → Remote SQL DB
iii. Generate reply → LLM (with context, prompts)
c. EmailProcessor → send reply via Gmail API
d. LogActivity → record actions to Google Sheets

##### Architectural Patterns & Principles
- Modular, single‐responsibility services (email processing, classification, ticketing, logging)
- Orchestration layer (reasoning_engine) coordinating AI calls and business decisions
- Adapter patterns for external systems (Gmail, LLM, SQL, Sheets)
- Separation of concerns: prompts, KB, services, engine

##### Technology Stack Callouts
- Python 3.10, FastAPI for HTTP/scheduler
- LangChain + OpenRouter for LLM orchestration
- Chroma (SQLite) as local vector store
- Google APIs for email & Sheets
- Remote SQL (Postgres/MySQL) for ticket persistence
- Docker + GitHub Actions CI/CD → AWS EC2 deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GmailAPI["Gmail API"]:::external
    OpenRouterLLM["OpenRouter LLM (OpenRouter API)"]:::external
    RemoteSQLDB["Remote SQL Database"]:::db
    GoogleSheets["Google Sheets API"]:::db
    AWS["AWS EC2"]:::external

    %% Deployment
    subgraph "Deployment & CI/CD"
        Dockerfile["Dockerfile"]:::devops
        CI["GitHub Actions Workflow"]:::devops
        Env[".env"]:::devops
        Req["requirements.txt"]:::devops
    end

    Dockerfile --> AWS
    CI --> AWS

    %% AI Agent Container
    subgraph "AI Agent (Docker Container)"
        direction TB
        API["FastAPI App + Scheduler"]:::internal
        Entry["AI Agent Entrypoint"]:::internal

        subgraph "Services Layer"
            direction TB
            EP["Email Processor"]:::internal
            IC["Intent Classification"]:::internal
            CT["Create Ticket"]:::internal
            LA["Activity Logging"]:::internal
            U["Utils"]:::internal
        end

        subgraph "Reasoning Engine"
            direction TB
            LLMA["LLM Adapter"]:::internal
            ORCH["Engine Orchestrator"]:::internal
            HELP["Engine Helpers"]:::internal
        end

        subgraph "Knowledge Base"
            direction TB
            KB["KB Loader & Retriever"]:::internal
            CHR["Chroma DB"]:::db
            DOCS["Source Documents"]:::internal
        end

        Prompts["Prompts/Templates"]:::internal
    end

    %% Data Flow
    API -->|"Trigger"| EP
    EP -->|"FetchEmail"| GmailAPI
    GmailAPI --> EP
    EP -->|"Classify"| IC
    IC -->|"Intent"| ORCH
    ORCH -->|"QueryKB"| KB
    KB -->|"LoadContext"| ORCH
    KB --> CHR
    ORCH -->|"GenerateReply"| OpenRouterLLM
    ORCH -->|"CreateTicket"| CT
    CT -->|"WriteTicket"| RemoteSQLDB
    ORCH -->|"LogActivity"| LA
    EP -->|"SendReply"| GmailAPI
    LA -->|"Log"| GoogleSheets

    %% Deployment Link
    API --> Dockerfile
    API --> CI
    API --> Env
    API --> Req

    %% Styles and Classes
    classDef internal fill:#E0F7FA,stroke:#0277BD,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#455A64,stroke-width:1px
    classDef db fill:#CFD8DC,stroke:#546E7A,stroke-width:1px
    classDef devops fill:#FFF9C4,stroke:#F9A825,stroke-width:1px

    %% Click Events
    click API "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/main.py"
    click Entry "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/ai_agent.py"
    click EP "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/services/email_processor.py"
    click IC "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/services/intent_classification.py"
    click CT "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/services/create_ticket.py"
    click LA "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/services/log_activity.py"
    click U "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/services/utils.py"
    click LLMA "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/reasoning_engine/llm.py"
    click ORCH "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/reasoning_engine/reasoning_engine.py"
    click HELP "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/reasoning_engine/reasoning_engine_helpers.py"
    click KB "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/knowledge_base/knowledge_base.py"
    click CHR "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/app/knowledge_base/knowledge_db/chroma.sqlite3"
    click DOCS "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/tree/main/app/knowledge_base/documents/"
    click Prompts "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/tree/main/app/prompts/"
    click Dockerfile "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/tree/main/Dockerfile"
    click CI "https://github.com/dashankanadeeshandesilva/crm_ai_workflow_automation_to_handle_and_respond_customer_emails/blob/main/.github/workflows/deploy.yml"
```
