# ptlkevin83/ai-service-desk architecture

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

- Interactive diagram: https://gitdiagram.com/ptlkevin83/ai-service-desk
- Repository: https://github.com/ptlkevin83/ai-service-desk

## Overview

This is an internal IT service desk application: a requester submits a ticket, the backend triages and routes it, applies escalation and SLA policy, then persists it for analyst management and reporting. Analysts can review tickets, change status or override recommendations, with audit history retained; dashboards and Power BI expose operational metrics. The graph reflects the sampled ticket-service and API code plus README-documented capabilities. Triage implementation details and analytics wiring were not sampled, so those links rely on the documented architecture.

Main entry points: [`app/services/ai_triage.py`](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ai_triage.py) (AI Triage), [`app/services/ticket_service.py`](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ticket_service.py) (Ticket Service), [`app/main.py`](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/main.py) (FastAPI App), [`app/api/tickets.py`](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/tickets.py) (Ticket API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_ticket_api["Ticket API<br/>[tickets.py]"]
  node_knowledge_api["Knowledge API<br/>[knowledge.py]"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
end

subgraph group_ticketing["Ticket Operations"]
  node_ticket_service["Ticket Service<br/>[ticket_service.py]"]
  node_ticket_schema["Ticket Schemas<br/>[ticket.py]"]
  node_database[("SQLAlchemy Database<br/>[database.py]")]
  node_ticket_model["Ticket Records<br/>[ticket.py]"]
  node_audit_model["Audit Records<br/>[audit.py]"]
end

subgraph group_policy["Triage Policy"]
  node_triage["AI Triage<br/>[ai_triage.py]"]
  node_routing["Team Routing<br/>[routing_service.py]"]
  node_escalation["Escalation Rules"]
  node_sla["SLA Management<br/>[sla_service.py]"]
  node_knowledge_service["Knowledge Service"]
  node_knowledge_data["Articles &amp; Rules"]
end

subgraph group_experience["Web Experience"]
  node_frontend["Service Desk UI"]
  node_ui_client["Browser API Client<br/>[app.js]"]
end

subgraph group_reporting["Reporting"]
  node_dashboard["Analytics Dashboard<br/>[dashboard.js]"]
end

node_requester(("Requester"))
node_analyst(("Service Desk Analyst"))
node_openai{{"OpenAI API"}}
node_powerbi(("Power BI"))

node_requester -->|"submits request"| node_frontend
node_analyst -->|"manages tickets"| node_frontend
node_frontend -->|"requests pages"| node_app
node_frontend -->|"uses API client"| node_ui_client
node_ui_client -->|"sends JSON"| node_ticket_api
node_app -->|"dispatches routes"| node_ticket_api
node_app -->|"dispatches routes"| node_knowledge_api
node_app -->|"dispatches routes"| node_analytics_api
node_ticket_api -->|"validates payloads"| node_ticket_schema
node_ticket_api -->|"invokes operations"| node_ticket_service
node_ticket_service -->|"requests triage"| node_triage
node_triage -.->|"requests analysis"| node_openai
node_triage -->|"selects team"| node_routing
node_triage -->|"checks escalation"| node_escalation
node_triage -->|"retrieves guidance"| node_knowledge_service
node_ticket_service -->|"calculates status"| node_sla
node_escalation -->|"loads rules"| node_knowledge_service
node_knowledge_api -->|"requests knowledge"| node_knowledge_service
node_knowledge_service -->|"loads articles"| node_knowledge_data
node_ticket_service -->|"reads and writes"| node_database
node_database -->|"persists tickets"| node_ticket_model
node_database -->|"persists history"| node_audit_model
node_analytics_api -->|"requests metrics"| node_ticket_service
node_dashboard -->|"fetches metrics"| node_ui_client
node_powerbi -.->|"pulls export"| node_analytics_api

click node_frontend "https://github.com/ptlkevin83/ai-service-desk/tree/master/frontend"
click node_ui_client "https://github.com/ptlkevin83/ai-service-desk/blob/master/frontend/js/app.js"
click node_app "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/main.py"
click node_ticket_api "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/tickets.py"
click node_knowledge_api "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/knowledge.py"
click node_analytics_api "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/analytics.py"
click node_ticket_service "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ticket_service.py"
click node_ticket_schema "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/schemas/ticket.py"
click node_triage "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ai_triage.py"
click node_routing "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/routing_service.py"
click node_escalation "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/escalation_service.py"
click node_sla "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/sla_service.py"
click node_knowledge_service "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/knowledge_service.py"
click node_knowledge_data "https://github.com/ptlkevin83/ai-service-desk/tree/master/app/knowledge_base"
click node_database "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/database/database.py"
click node_ticket_model "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/models/ticket.py"
click node_audit_model "https://github.com/ptlkevin83/ai-service-desk/blob/master/app/models/audit.py"
click node_dashboard "https://github.com/ptlkevin83/ai-service-desk/blob/master/frontend/js/dashboard.js"

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_app,node_ticket_api,node_knowledge_api,node_analytics_api toneBlue
class node_ticket_service,node_ticket_schema,node_database,node_ticket_model,node_audit_model toneAmber
class node_triage,node_routing,node_escalation,node_sla,node_knowledge_service,node_knowledge_data,node_requester,node_openai toneMint
class node_frontend,node_ui_client toneRose
class node_dashboard,node_analyst,node_powerbi toneIndigo
```

## Components

### Application API

- [FastAPI App](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/main.py): `app/main.py`
- [Ticket API](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/tickets.py): `app/api/tickets.py`
- [Knowledge API](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/knowledge.py): `app/api/knowledge.py`
- [Analytics API](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/api/analytics.py): `app/api/analytics.py`

### Ticket Operations

- [Ticket Service](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ticket_service.py): `app/services/ticket_service.py`
- [Ticket Schemas](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/schemas/ticket.py): `app/schemas/ticket.py`
- [SQLAlchemy Database](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/database/database.py): `app/database/database.py`
- [Ticket Records](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/models/ticket.py): `app/models/ticket.py`
- [Audit Records](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/models/audit.py): `app/models/audit.py`

### Triage Policy

- [AI Triage](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/ai_triage.py): `app/services/ai_triage.py`
- [Team Routing](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/routing_service.py): `app/services/routing_service.py`
- [Escalation Rules](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/escalation_service.py): `app/services/escalation_service.py`
- [SLA Management](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/sla_service.py): `app/services/sla_service.py`
- [Knowledge Service](https://github.com/ptlkevin83/ai-service-desk/blob/master/app/services/knowledge_service.py): `app/services/knowledge_service.py`
- [Articles & Rules](https://github.com/ptlkevin83/ai-service-desk/tree/master/app/knowledge_base): `app/knowledge_base`

### Web Experience

- [Service Desk UI](https://github.com/ptlkevin83/ai-service-desk/tree/master/frontend): `frontend`
- [Browser API Client](https://github.com/ptlkevin83/ai-service-desk/blob/master/frontend/js/app.js): `frontend/js/app.js`

### Reporting

- [Analytics Dashboard](https://github.com/ptlkevin83/ai-service-desk/blob/master/frontend/js/dashboard.js): `frontend/js/dashboard.js`

### Other components

- **Requester**
- **Service Desk Analyst**
- **OpenAI API**
- **Power BI**

## Connections

- Requester → Service Desk UI: submits request
- Service Desk Analyst → Service Desk UI: manages tickets
- Service Desk UI → FastAPI App: requests pages
- Service Desk UI → Browser API Client: uses API client
- Browser API Client → Ticket API: sends JSON
- FastAPI App → Ticket API: dispatches routes
- FastAPI App → Knowledge API: dispatches routes
- FastAPI App → Analytics API: dispatches routes
- Ticket API → Ticket Schemas: validates payloads
- Ticket API → Ticket Service: invokes operations
- Ticket Service → AI Triage: requests triage
- AI Triage → OpenAI API: requests analysis
- AI Triage → Team Routing: selects team
- AI Triage → Escalation Rules: checks escalation
- AI Triage → Knowledge Service: retrieves guidance
- Ticket Service → SLA Management: calculates status
- Escalation Rules → Knowledge Service: loads rules
- Knowledge API → Knowledge Service: requests knowledge
- Knowledge Service → Articles & Rules: loads articles
- Ticket Service → SQLAlchemy Database: reads and writes
- SQLAlchemy Database → Ticket Records: persists tickets
- SQLAlchemy Database → Audit Records: persists history
- Analytics API → Ticket Service: requests metrics
- Analytics Dashboard → Browser API Client: fetches metrics
- Power BI → Analytics API: pulls export