# vishal060803/ai-powered-itsm-helpdesk-automation architecture

> Architecture diagram of the GitHub repository vishal060803/ai-powered-itsm-helpdesk-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishal060803/ai-powered-itsm-helpdesk-automation
- Repository: https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation

## Overview

This is a prototype IT helpdesk portal: employees ask support questions or search approved guidance, receive grounded troubleshooting, and can use a simulated ticket/request dashboard. The implemented runtime centers on the React portal, FastAPI knowledge routes, and a document-to-vector retrieval pipeline. MongoDB is initialized as a persistence foundation, but README describes ticket persistence, ServiceNow integration, self-heal automation, and software provisioning as future work. Edges reflect shown calls or README-documented flows; unsampled UI and backend behavior is not inferred beyond that documentation.

Main entry points: [`backend/app/routers/knowledge.py`](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/routers/knowledge.py) (Knowledge routes), [`frontend/src/App.jsx`](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/App.jsx) (Portal UI), [`backend/app/main.py`](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/knowledge_pipeline.py`](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/knowledge_pipeline.py) (Chunk & embed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Employee portal"]
  node_portal_ui["Portal UI<br/>[App.jsx]"]
  node_portal_mount["App mount<br/>[main.jsx]"]
  node_dashboard_requests["Dashboard &amp; requests<br/>[App.jsx]"]
end

subgraph group_api["Backend API"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_health_routes["Health routes<br/>[health.py]"]
  node_knowledge_routes["Knowledge routes<br/>[knowledge.py]"]
  node_contracts["API contracts<br/>[schemas.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_assistant["Grounded assistant<br/>[chat_assistant.py]"]
  node_vector_store[("Vector search")]
  node_pipeline["Chunk &amp; embed"]
  node_articles["Approved articles"]
  node_embedding_artifact["Embedding chunks"]
end

subgraph group_state["Persistence foundation"]
  node_mongo_setup["Mongo setup<br/>[database.py]"]
end

node_employee(("Employee"))
node_mongodb[("MongoDB")]

node_employee -->|"uses"| node_portal_ui
node_portal_mount -->|"renders"| node_portal_ui
node_portal_ui -->|"requests search"| node_knowledge_routes
node_portal_ui -->|"asks questions"| node_knowledge_routes
node_portal_ui -->|"shows"| node_dashboard_requests
node_api_app -->|"registers"| node_health_routes
node_api_app -->|"registers"| node_knowledge_routes
node_api_app -->|"initializes"| node_mongo_setup
node_mongo_setup -->|"connects"| node_mongodb
node_knowledge_routes -->|"searches"| node_vector_store
node_knowledge_routes -->|"builds reply"| node_assistant
node_knowledge_routes -->|"uses models"| node_contracts
node_articles -->|"provides articles"| node_pipeline
node_pipeline -->|"writes chunks"| node_embedding_artifact
node_embedding_artifact -->|"indexes chunks"| node_vector_store

click node_portal_ui "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/App.jsx"
click node_portal_mount "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/main.jsx"
click node_dashboard_requests "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/App.jsx"
click node_api_app "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/main.py"
click node_health_routes "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/routers/health.py"
click node_knowledge_routes "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/routers/knowledge.py"
click node_contracts "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/schemas.py"
click node_assistant "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/chat_assistant.py"
click node_vector_store "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/knowledge_vector_store.py"
click node_pipeline "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/knowledge_pipeline.py"
click node_articles "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/tree/main/data/knowledge_docs"
click node_embedding_artifact "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/data/embeddings/knowledge_chunks.jsonl"
click node_mongo_setup "https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/database.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_portal_ui,node_portal_mount,node_dashboard_requests toneBlue
class node_api_app,node_health_routes,node_knowledge_routes,node_contracts,node_mongodb toneAmber
class node_assistant,node_vector_store,node_pipeline,node_articles,node_embedding_artifact toneMint
class node_mongo_setup toneRose
class node_employee toneIndigo
```

## Components

### Employee portal

- [Portal UI](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [App mount](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Dashboard & requests](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Backend API

- [FastAPI app](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/main.py): `backend/app/main.py`
- [Health routes](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/routers/health.py): `backend/app/routers/health.py`
- [Knowledge routes](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/routers/knowledge.py): `backend/app/routers/knowledge.py`
- [API contracts](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Knowledge retrieval

- [Grounded assistant](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/chat_assistant.py): `backend/app/chat_assistant.py`
- [Vector search](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/knowledge_vector_store.py): `backend/app/knowledge_vector_store.py`
- [Chunk & embed](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/knowledge_pipeline.py): `backend/app/knowledge_pipeline.py`
- [Approved articles](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/tree/main/data/knowledge_docs): `data/knowledge_docs`
- [Embedding chunks](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/data/embeddings/knowledge_chunks.jsonl): `data/embeddings/knowledge_chunks.jsonl`

### Persistence foundation

- [Mongo setup](https://github.com/vishal060803/ai-powered-itsm-helpdesk-automation/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Employee**
- **MongoDB**

## Connections

- Employee → Portal UI: uses (evidence: `README.md`)
- App mount → Portal UI: renders (evidence: `frontend/src/main.jsx`)
- Portal UI → Knowledge routes: requests search (evidence: `frontend/src/App.jsx`)
- Portal UI → Knowledge routes: asks questions (evidence: `README.md`)
- Portal UI → Dashboard & requests: shows (evidence: `README.md`)
- FastAPI app → Health routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Knowledge routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Mongo setup: initializes (evidence: `backend/app/main.py`)
- Mongo setup → MongoDB: connects (evidence: `backend/app/database.py`)
- Knowledge routes → Vector search: searches (evidence: `backend/app/routers/knowledge.py`)
- Knowledge routes → Grounded assistant: builds reply (evidence: `backend/app/routers/knowledge.py`)
- Knowledge routes → API contracts: uses models (evidence: `backend/app/routers/knowledge.py`)
- Approved articles → Chunk & embed: provides articles (evidence: `README.md`)
- Chunk & embed → Embedding chunks: writes chunks (evidence: `README.md`)
- Embedding chunks → Vector search: indexes chunks (evidence: `backend/app/knowledge_vector_store.py`)
