# tridip100/ai-helpdesk-management-system- architecture

> Architecture diagram of the GitHub repository tridip100/ai-helpdesk-management-system-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tridip100/ai-helpdesk-management-system-
- Repository: https://github.com/tridip100/ai-helpdesk-management-system-

## Overview

AI Helpdesk Copilot takes employee issues through chat, voice, email, or screenshots; classifies and attempts resolution with cached solutions, retrieval, and a local LLM; then escalates unresolved work into a role-managed ticket lifecycle. The README documents routing, SLA enforcement, anomaly clustering, audit history, and digest capabilities. Sampled code confirms the main streaming/RAG interactions and email parsing; some documented capability wiring is not visible in the excerpts, so uncertain links are omitted.

Main entry points: [`backend/services/ai_pipeline.py`](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ai_pipeline.py) (AI decision pipeline), [`backend/main.py`](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/main.py) (FastAPI application), [`backend/services/ticket_service.py`](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ticket_service.py) (Ticket management), [`frontend/src/App.jsx`](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/frontend/src/App.jsx) (Role dashboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_frontend["Role dashboards<br/>[App.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_intake["Issue Intake"]
  node_app["FastAPI application<br/>[main.py]"]
  node_chat_router["Chat endpoint<br/>[chat.py]"]
  node_intake_router["Ticket intake<br/>[intake.py]"]
  node_channels["Channel normalization<br/>[normalizer.py]"]
  node_email_handler["Email parsing<br/>[email_handler.py]"]
  node_imap_poller["Mailbox polling<br/>[imap_poller.py]"]
  node_stt["Voice transcription<br/>[stt_service.py]"]
  node_vision["Screenshot extraction<br/>[vision_service.py]"]
end

subgraph group_intelligence["AI Resolution"]
  node_pipeline["AI decision pipeline<br/>[ai_pipeline.py]"]
  node_nlp["Intent and NLP<br/>[nlp_services.py]"]
  node_cache[("Solution cache")]
  node_rag["Knowledge retrieval<br/>[rag_service.py]"]
  node_llm["Local LLM service<br/>[llm_services.py]"]
  node_sanitizer["Query sanitization"]
  node_tavily["Web search<br/>[tavily_service.py]"]
end

subgraph group_lifecycle["Ticket Lifecycle"]
  node_tickets_router["Ticket operations<br/>[tickets.py]"]
  node_ticket_service["Ticket management<br/>[ticket_service.py]"]
  node_routing["Assignment routing<br/>[routing_service.py]"]
  node_sla["SLA monitoring<br/>[sla_service.py]"]
  node_anomaly["Incident detection"]
  node_digest["Support digests<br/>[digest_service.py]"]
  node_admin_router["Administration<br/>[admin.py]"]
end

subgraph group_persistence["Data and Knowledge"]
  node_database[("Relational database<br/>[database.py]")]
  node_vector_store[("Vector knowledge store<br/>[base_ingestor.py]")]
  node_documents["SOP ingestion"]
  node_resolved_tickets["Resolved-ticket ingestion<br/>[ticket_ingestor.py]"]
end

node_employees(("Employees"))
node_agents(("Helpdesk and IT staff"))
node_ollama["Ollama local model"]
node_web_search["Tavily service"]
node_mailbox["IMAP mailbox"]

node_employees -->|"use"| node_frontend
node_agents -->|"use"| node_frontend
node_frontend -->|"request"| node_api_client
node_api_client -->|"HTTP calls"| node_app
node_app -->|"mounts"| node_chat_router
node_app -->|"mounts"| node_intake_router
node_app -->|"mounts"| node_tickets_router
node_app -->|"mounts"| node_admin_router
node_chat_router -->|"stream message"| node_pipeline
node_intake_router -->|"normalize input"| node_channels
node_imap_poller -->|"polls"| node_mailbox
node_imap_poller -->|"parse mail"| node_email_handler
node_email_handler -->|"produce input"| node_channels
node_channels -->|"submit issue"| node_ticket_service
node_pipeline -->|"classify intent"| node_nlp
node_pipeline -->|"check and store"| node_cache
node_pipeline -->|"retrieve context"| node_rag
node_pipeline -->|"generate response"| node_llm
node_rag -->|"search knowledge"| node_vector_store
node_pipeline -->|"sanitize fallback query"| node_sanitizer
node_pipeline -->|"search fallback"| node_tavily
node_tavily -.->|"query"| node_web_search
node_llm -->|"generate locally"| node_ollama
node_pipeline -->|"create escalation"| node_ticket_service
node_tickets_router -->|"manage tickets"| node_ticket_service
node_ticket_service -->|"assign ticket"| node_routing
node_ticket_service -->|"read and write"| node_database
node_app -->|"start checker"| node_sla
node_sla -->|"check ticket state"| node_database
node_admin_router -->|"administer records"| node_database
node_documents -->|"index SOPs"| node_vector_store
node_resolved_tickets -->|"index resolutions"| node_vector_store

click node_frontend "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/frontend/src/api/client.js"
click node_app "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/main.py"
click node_chat_router "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/chat.py"
click node_intake_router "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/intake.py"
click node_channels "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/normalizer.py"
click node_email_handler "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/email_handler.py"
click node_imap_poller "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/imap_poller.py"
click node_stt "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/stt_service.py"
click node_vision "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/vision_service.py"
click node_pipeline "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ai_pipeline.py"
click node_nlp "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/nlp_services.py"
click node_cache "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/solution_cache_service.py"
click node_rag "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/rag_service.py"
click node_llm "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/llm_services.py"
click node_sanitizer "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/sanitizer_service.py"
click node_tavily "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/tavily_service.py"
click node_tickets_router "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/tickets.py"
click node_ticket_service "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ticket_service.py"
click node_routing "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/routing_service.py"
click node_sla "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/sla_service.py"
click node_anomaly "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/anomaly_services.py"
click node_digest "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/digest_service.py"
click node_admin_router "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/admin.py"
click node_database "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/database.py"
click node_vector_store "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/base_ingestor.py"
click node_documents "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/document_ingestor.py"
click node_resolved_tickets "https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/ticket_ingestor.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_frontend,node_api_client toneBlue
class node_app,node_chat_router,node_intake_router,node_channels,node_email_handler,node_imap_poller,node_stt,node_vision toneAmber
class node_pipeline,node_nlp,node_cache,node_rag,node_llm,node_sanitizer,node_tavily toneMint
class node_tickets_router,node_ticket_service,node_routing,node_sla,node_anomaly,node_digest,node_admin_router toneRose
class node_database,node_vector_store,node_documents,node_resolved_tickets,node_employees,node_agents,node_ollama,node_web_search,node_mailbox toneIndigo
```

## Components

### User Experience

- [Role dashboards](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Issue Intake

- [FastAPI application](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/main.py): `backend/main.py`
- [Chat endpoint](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/chat.py): `backend/routers/chat.py`
- [Ticket intake](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/intake.py): `backend/routers/intake.py`
- [Channel normalization](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/normalizer.py): `backend/channels/normalizer.py`
- [Email parsing](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/email_handler.py): `backend/channels/email_handler.py`
- [Mailbox polling](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/channels/imap_poller.py): `backend/channels/imap_poller.py`
- [Voice transcription](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/stt_service.py): `backend/services/stt_service.py`
- [Screenshot extraction](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/vision_service.py): `backend/services/vision_service.py`

### AI Resolution

- [AI decision pipeline](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ai_pipeline.py): `backend/services/ai_pipeline.py`
- [Intent and NLP](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/nlp_services.py): `backend/services/nlp_services.py`
- [Solution cache](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/solution_cache_service.py): `backend/services/solution_cache_service.py`
- [Knowledge retrieval](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/rag_service.py): `backend/services/rag_service.py`
- [Local LLM service](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/llm_services.py): `backend/services/llm_services.py`
- [Query sanitization](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/sanitizer_service.py): `backend/services/sanitizer_service.py`
- [Web search](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/tavily_service.py): `backend/services/tavily_service.py`

### Ticket Lifecycle

- [Ticket operations](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/tickets.py): `backend/routers/tickets.py`
- [Ticket management](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/ticket_service.py): `backend/services/ticket_service.py`
- [Assignment routing](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/routing_service.py): `backend/services/routing_service.py`
- [SLA monitoring](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/sla_service.py): `backend/services/sla_service.py`
- [Incident detection](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/anomaly_services.py): `backend/services/anomaly_services.py`
- [Support digests](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/services/digest_service.py): `backend/services/digest_service.py`
- [Administration](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/routers/admin.py): `backend/routers/admin.py`

### Data and Knowledge

- [Relational database](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/database.py): `backend/database.py`
- [Vector knowledge store](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/base_ingestor.py): `backend/ingestion/base_ingestor.py`
- [SOP ingestion](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/document_ingestor.py): `backend/ingestion/document_ingestor.py`
- [Resolved-ticket ingestion](https://github.com/tridip100/ai-helpdesk-management-system-/blob/main/backend/ingestion/ticket_ingestor.py): `backend/ingestion/ticket_ingestor.py`

### Other components

- **Employees**
- **Helpdesk and IT staff**
- **Ollama local model**
- **Tavily service**
- **IMAP mailbox**

## Connections

- Employees → Role dashboards: use
- Helpdesk and IT staff → Role dashboards: use
- Role dashboards → API client: request
- API client → FastAPI application: HTTP calls
- FastAPI application → Chat endpoint: mounts
- FastAPI application → Ticket intake: mounts
- FastAPI application → Ticket operations: mounts
- FastAPI application → Administration: mounts
- Chat endpoint → AI decision pipeline: stream message
- Ticket intake → Channel normalization: normalize input
- Mailbox polling → IMAP mailbox: polls
- Mailbox polling → Email parsing: parse mail
- Email parsing → Channel normalization: produce input
- Channel normalization → Ticket management: submit issue
- AI decision pipeline → Intent and NLP: classify intent
- AI decision pipeline → Solution cache: check and store
- AI decision pipeline → Knowledge retrieval: retrieve context
- AI decision pipeline → Local LLM service: generate response
- Knowledge retrieval → Vector knowledge store: search knowledge
- AI decision pipeline → Query sanitization: sanitize fallback query
- AI decision pipeline → Web search: search fallback
- Web search → Tavily service: query
- Local LLM service → Ollama local model: generate locally
- AI decision pipeline → Ticket management: create escalation
- Ticket operations → Ticket management: manage tickets
- Ticket management → Assignment routing: assign ticket
- Ticket management → Relational database: read and write
- FastAPI application → SLA monitoring: start checker
- SLA monitoring → Relational database: check ticket state
- Administration → Relational database: administer records
- SOP ingestion → Vector knowledge store: index SOPs
- Resolved-ticket ingestion → Vector knowledge store: index resolutions