# gantechproject/it-helpdesk-agent architecture

> Architecture diagram of the GitHub repository gantechproject/it-helpdesk-agent, 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/gantechproject/it-helpdesk-agent
- Repository: https://github.com/gantechproject/it-helpdesk-agent

## Overview

This is an IT helpdesk agent with a browser chat proxy and a FastAPI/ADK serving runtime. Employees submit issues; the agent can look up guidance and service status, manage tickets, run diagnostics, use persistent preferences, and generate equipment media, then return text or structured A2UI. The README documents several capabilities whose implementation was not sampled; those are shown at the documented subsystem level, while uncertain internal wiring is omitted.

Main entry points: [`app/agent.py`](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py) (ADK agent), [`frontend/static/index.html`](https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/static/index.html) (Web chat UI), [`frontend/main.py`](https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/main.py) (Chat proxy), [`app/fast_api_app.py`](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/fast_api_app.py) (FastAPI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_browser["Web chat UI<br/>[index.html]"]
  node_proxy["Chat proxy<br/>[main.py]"]
  node_a2ui["A2UI rendering<br/>[a2ui_utils.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_api["FastAPI runtime<br/>[fast_api_app.py]"]
  node_a2a["A2A endpoints<br/>[a2a.py]"]
  node_reasoning["Reasoning adapter"]
  node_runner["ADK agent<br/>[agent.py]"]
  node_services["Shared services<br/>[services.py]"]
end

subgraph group_support["Helpdesk capabilities"]
  node_ticket_ops["Ticket lifecycle<br/>[agent.py]"]
  node_knowledge["Knowledge lookup<br/>[agent.py]"]
  node_service_status["Service status<br/>[agent.py]"]
  node_diagnostics["Sandbox diagnostics<br/>[agent.py]"]
  node_media["Equipment media<br/>[agent.py]"]
end

subgraph group_state["State and integrations"]
  node_memory["User memory<br/>[agent.py]"]
  node_firestore[("Firestore")]
  node_memory_bank[("Vertex Memory Bank")]
  node_gcs[("Cloud Storage")]
  node_vertex["Vertex AI models"]
end

node_employee(("Employee"))
node_external_status["Status sources"]
node_sandbox_service["Agent Engine sandbox"]
node_support_user(("Support employee"))

node_employee -->|"enters request"| node_browser
node_browser -->|"sends chat"| node_proxy
node_proxy -->|"forwards A2A"| node_a2a
node_a2a -->|"dispatches task"| node_runner
node_runner -->|"returns reply"| node_proxy
node_proxy -->|"renders parts"| node_browser
node_browser -->|"renders cards"| node_a2ui
node_api -->|"registers routes"| node_a2a
node_api -->|"attaches routes"| node_reasoning
node_api -->|"creates runner"| node_runner
node_runner -->|"uses shared services"| node_services
node_reasoning -->|"reuses services"| node_services
node_runner -->|"dispatches tools"| node_ticket_ops
node_runner -->|"dispatches tools"| node_knowledge
node_runner -->|"dispatches tools"| node_service_status
node_runner -->|"dispatches tools"| node_diagnostics
node_runner -->|"dispatches tools"| node_media
node_runner -->|"uses memory"| node_memory
node_ticket_ops -->|"reads and writes"| node_firestore
node_knowledge -->|"reads articles"| node_firestore
node_service_status -->|"queries status"| node_external_status
node_diagnostics -->|"executes scripts"| node_sandbox_service
node_media -->|"generates media"| node_vertex
node_media -->|"stores media"| node_gcs
node_memory -->|"recalls preferences"| node_memory_bank
node_media -->|"provides media parts"| node_a2ui
node_ticket_ops -->|"provides ticket cards"| node_a2ui
node_support_user -.->|"uses helpdesk"| node_runner

click node_browser "https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/static/index.html"
click node_proxy "https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/main.py"
click node_a2ui "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/a2ui_utils.py"
click node_api "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/fast_api_app.py"
click node_a2a "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/a2a.py"
click node_reasoning "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/reasoning_engine_adapter.py"
click node_runner "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_services "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/services.py"
click node_ticket_ops "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_knowledge "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_service_status "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_diagnostics "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_media "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py"
click node_memory "https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.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_browser,node_proxy,node_a2ui toneBlue
class node_api,node_a2a,node_reasoning,node_runner,node_services toneAmber
class node_ticket_ops,node_knowledge,node_service_status,node_diagnostics,node_media toneMint
class node_memory,node_firestore,node_memory_bank,node_gcs,node_vertex toneRose
class node_employee,node_external_status,node_sandbox_service,node_support_user toneIndigo
```

## Components

### User experience

- [Web chat UI](https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/static/index.html): `frontend/static/index.html`
- [Chat proxy](https://github.com/gantechproject/it-helpdesk-agent/blob/main/frontend/main.py): `frontend/main.py`
- [A2UI rendering](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/a2ui_utils.py): `app/a2ui_utils.py`

### Agent runtime

- [FastAPI runtime](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/fast_api_app.py): `app/fast_api_app.py`
- [A2A endpoints](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/a2a.py): `app/app_utils/a2a.py`
- [Reasoning adapter](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/reasoning_engine_adapter.py): `app/app_utils/reasoning_engine_adapter.py`
- [ADK agent](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- [Shared services](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/app_utils/services.py): `app/app_utils/services.py`

### Helpdesk capabilities

- [Ticket lifecycle](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- [Knowledge lookup](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- [Service status](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- [Sandbox diagnostics](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- [Equipment media](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`

### State and integrations

- [User memory](https://github.com/gantechproject/it-helpdesk-agent/blob/main/app/agent.py): `app/agent.py`
- **Firestore**
- **Vertex Memory Bank**
- **Cloud Storage**
- **Vertex AI models**

### Other components

- **Employee**
- **Status sources**
- **Agent Engine sandbox**
- **Support employee**

## Connections

- Employee → Web chat UI: enters request
- Web chat UI → Chat proxy: sends chat
- Chat proxy → A2A endpoints: forwards A2A
- A2A endpoints → ADK agent: dispatches task
- ADK agent → Chat proxy: returns reply
- Chat proxy → Web chat UI: renders parts
- Web chat UI → A2UI rendering: renders cards
- FastAPI runtime → A2A endpoints: registers routes
- FastAPI runtime → Reasoning adapter: attaches routes
- FastAPI runtime → ADK agent: creates runner
- ADK agent → Shared services: uses shared services
- Reasoning adapter → Shared services: reuses services
- ADK agent → Ticket lifecycle: dispatches tools
- ADK agent → Knowledge lookup: dispatches tools
- ADK agent → Service status: dispatches tools
- ADK agent → Sandbox diagnostics: dispatches tools
- ADK agent → Equipment media: dispatches tools
- ADK agent → User memory: uses memory
- Ticket lifecycle → Firestore: reads and writes
- Knowledge lookup → Firestore: reads articles
- Service status → Status sources: queries status
- Sandbox diagnostics → Agent Engine sandbox: executes scripts
- Equipment media → Vertex AI models: generates media
- Equipment media → Cloud Storage: stores media
- User memory → Vertex Memory Bank: recalls preferences
- Equipment media → A2UI rendering: provides media parts
- Ticket lifecycle → A2UI rendering: provides ticket cards
- Support employee → ADK agent: uses helpdesk