# sharwindtharumadurai/itops-ai-helpdesk architecture

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

- Interactive diagram: https://gitdiagram.com/sharwindtharumadurai/itops-ai-helpdesk
- Repository: https://github.com/sharwindtharumadurai/itops-ai-helpdesk

## Overview

ITOps AI turns an authenticated user’s support request into a ticket and, when safe, an approved remediation on a managed endpoint or an Entra/Microsoft 365 account change. The main path is triage, catalog validation, device and policy resolution, dispatch, then execution-result capture and ticket closure. Separate capabilities include admin approvals, generated-script review, device inventory, and ticket history. The README documents these branches; sampled source confirms several API, storage, identity, LLM, and Graph details, while some subsystem wiring is represented only where explicitly documented.

Main entry points: [`lambda/itops/api.py`](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/api.py) (API handler), [`web/app.js`](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/web/app.js) (Web chat), [`infra/itops/itops_stack.py`](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/infra/itops/itops_stack.py) (HTTP API), [`lambda/itops/store.py`](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/store.py) (Ticket and device store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User clients"]
  node_web["Web chat<br/>[app.js]"]
  node_cli["CLI client<br/>[itops_cli.py]"]
end

subgraph group_request["Request handling"]
  node_api["API handler<br/>[api.py]"]
  node_identity["Caller identity<br/>[auth.py]"]
  node_ai["AI triage<br/>[ai.py]"]
  node_catalog["Action catalog<br/>[catalog.py]"]
  node_guardrails["Script guardrails<br/>[guardrails.py]"]
end

subgraph group_execution["Remediation"]
  node_dispatcher["Action dispatcher<br/>[dispatcher.py]"]
  node_scripts["Endpoint actions"]
  node_graph["Graph account actions<br/>[graph.py]"]
end

subgraph group_state["State and events"]
  node_store[("Ticket and device store<br/>[store.py]")]
  node_events["SSM event handler<br/>[ssm_events.py]"]
  node_inventory["Device inventory sync<br/>[ssm_events.py]"]
end

node_user(("IT user"))
node_admin(("IT admin"))
node_entra["Entra ID"]
node_gateway["HTTP API<br/>[itops_stack.py]"]
node_llm["LLM providers"]
node_ssm["AWS Systems Manager"]
node_endpoint["Managed endpoints"]
node_msgraph["Microsoft Graph"]
node_eventbridge["EventBridge<br/>[itops_stack.py]"]

node_user -->|"submits request"| node_web
node_admin -->|"reviews tickets"| node_web
node_user -->|"submits request"| node_cli
node_web -->|"signs in"| node_entra
node_web -->|"calls API"| node_gateway
node_cli -->|"calls API"| node_gateway
node_entra -->|"issues JWT"| node_gateway
node_gateway -->|"routes requests"| node_api
node_api -->|"reads claims"| node_identity
node_api -->|"requests triage"| node_ai
node_ai -->|"requests completion"| node_llm
node_api -->|"validates proposal"| node_catalog
node_api -->|"reads and writes"| node_store
node_api -->|"dispatches approved action"| node_dispatcher
node_api -->|"runs account action"| node_graph
node_graph -->|"changes accounts"| node_msgraph
node_dispatcher -->|"sends command"| node_ssm
node_ssm -->|"delivers command"| node_endpoint
node_endpoint -->|"runs action"| node_scripts
node_ssm -->|"emits status"| node_eventbridge
node_eventbridge -->|"dispatches event"| node_events
node_events -->|"fetches output"| node_ssm
node_events -->|"records result"| node_store
node_eventbridge -.->|"schedules sync"| node_inventory
node_inventory -->|"reads fleet"| node_ssm
node_inventory -->|"updates devices"| node_store
node_api -->|"scans generated script"| node_guardrails
node_ai -->|"returns draft"| node_api
node_api -->|"records approval state"| node_store
node_web -->|"polls ticket status"| node_gateway

click node_web "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/web/app.js"
click node_cli "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/tools/itops_cli.py"
click node_gateway "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/infra/itops/itops_stack.py"
click node_api "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/api.py"
click node_identity "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/auth.py"
click node_ai "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ai.py"
click node_catalog "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/catalog.py"
click node_guardrails "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/guardrails.py"
click node_store "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/store.py"
click node_dispatcher "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/dispatcher.py"
click node_scripts "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/tree/main/scripts"
click node_graph "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/graph.py"
click node_events "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ssm_events.py"
click node_eventbridge "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/infra/itops/itops_stack.py"
click node_inventory "https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ssm_events.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_web,node_cli,node_user toneBlue
class node_api,node_identity,node_ai,node_catalog,node_guardrails toneAmber
class node_dispatcher,node_scripts,node_graph,node_gateway toneMint
class node_store,node_events,node_inventory toneRose
class node_admin,node_entra,node_llm,node_ssm,node_endpoint,node_msgraph toneIndigo
class node_eventbridge toneTeal
```

## Components

### User clients

- [Web chat](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/web/app.js): `web/app.js`
- [CLI client](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/tools/itops_cli.py): `tools/itops_cli.py`

### Request handling

- [API handler](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/api.py): `lambda/itops/api.py`
- [Caller identity](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/auth.py): `lambda/itops/auth.py`
- [AI triage](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ai.py): `lambda/itops/ai.py`
- [Action catalog](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/catalog.py): `lambda/itops/catalog.py`
- [Script guardrails](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/guardrails.py): `lambda/itops/guardrails.py`

### Remediation

- [Action dispatcher](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/dispatcher.py): `lambda/itops/dispatcher.py`
- [Endpoint actions](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/tree/main/scripts): `scripts`
- [Graph account actions](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/graph.py): `lambda/itops/graph.py`

### State and events

- [Ticket and device store](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/store.py): `lambda/itops/store.py`
- [SSM event handler](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ssm_events.py): `lambda/itops/ssm_events.py`
- [Device inventory sync](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/lambda/itops/ssm_events.py): `lambda/itops/ssm_events.py`

### Other components

- **IT user**
- **IT admin**
- **Entra ID**
- [HTTP API](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/infra/itops/itops_stack.py): `infra/itops/itops_stack.py`
- **LLM providers**
- **AWS Systems Manager**
- **Managed endpoints**
- **Microsoft Graph**
- [EventBridge](https://github.com/sharwindtharumadurai/itops-ai-helpdesk/blob/main/infra/itops/itops_stack.py): `infra/itops/itops_stack.py`

## Connections

- IT user → Web chat: submits request
- IT admin → Web chat: reviews tickets
- IT user → CLI client: submits request
- Web chat → Entra ID: signs in
- Web chat → HTTP API: calls API
- CLI client → HTTP API: calls API
- Entra ID → HTTP API: issues JWT
- HTTP API → API handler: routes requests
- API handler → Caller identity: reads claims
- API handler → AI triage: requests triage
- AI triage → LLM providers: requests completion
- API handler → Action catalog: validates proposal
- API handler → Ticket and device store: reads and writes
- API handler → Action dispatcher: dispatches approved action
- API handler → Graph account actions: runs account action
- Graph account actions → Microsoft Graph: changes accounts
- Action dispatcher → AWS Systems Manager: sends command
- AWS Systems Manager → Managed endpoints: delivers command
- Managed endpoints → Endpoint actions: runs action
- AWS Systems Manager → EventBridge: emits status
- EventBridge → SSM event handler: dispatches event
- SSM event handler → AWS Systems Manager: fetches output
- SSM event handler → Ticket and device store: records result
- EventBridge → Device inventory sync: schedules sync
- Device inventory sync → AWS Systems Manager: reads fleet
- Device inventory sync → Ticket and device store: updates devices
- API handler → Script guardrails: scans generated script
- AI triage → API handler: returns draft
- API handler → Ticket and device store: records approval state
- Web chat → HTTP API: polls ticket status