# pavithra-ssg/sd-assistant architecture

> Architecture diagram of the GitHub repository pavithra-ssg/sd-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pavithra-ssg/sd-assistant
- Repository: https://github.com/pavithra-ssg/sd-assistant

## Overview

SD Assistant is an IT service desk: employees describe an issue in chat or a form, receive policy-gated guided fixes, and reach a human queue with the conversation and evidence attached when needed. Agents handle queued tickets; supervisors manage knowledge, users, and service performance. The diagram covers the documented OCR, authentication, ticket lifecycle, alerting, analytics, and privacy capabilities. Relationships follow the excerpts, SOURCE INDEX references, and README; some route-level details are unsampled, so they are not expanded.

Main entry points: [`api.py`](https://github.com/pavithra-ssg/sd-assistant/blob/main/api.py) (FastAPI routes), [`servicedesk/orchestrator.py`](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/orchestrator.py) (Conversation policy), [`servicedesk/store.py`](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/store.py) (Relational store), [`servicedesk/services/tickets.py`](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/tickets.py) (Ticket lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_employee_ui["Chat and forms<br/>[employee_chat.py]"]
  node_ticket_ui["Ticket views<br/>[ticket.py]"]
  node_admin_ui["Admin and insights<br/>[knowledge.py]"]
  node_ui_client["HTTP client<br/>[client.py]"]
end

subgraph group_backend["API and identity"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_assistant["Guided support"]
  node_orchestrator["Conversation policy<br/>[orchestrator.py]"]
  node_jev["Jev judgments<br/>[brain.py]"]
  node_knowledge["Knowledge and policy<br/>[knowledge.py]"]
  node_attachments["Screenshot OCR<br/>[attachments.py]"]
  node_tools["Verified tools<br/>[tools.py]"]
end

subgraph group_operations["Ticket operations"]
  node_tickets["Ticket lifecycle<br/>[tickets.py]"]
  node_alerts["Alerts and SLA<br/>[alerts.py]"]
  node_analytics["Service analytics<br/>[analytics.py]"]
  node_kb_admin["Article management<br/>[kb.py]"]
  node_privacy["Privacy controls<br/>[privacy.py]"]
  node_notify["Notifications<br/>[notify.py]"]
  node_worker["Background worker<br/>[worker.py]"]
end

subgraph group_platform["Data and services"]
  node_store[("Relational store<br/>[store.py]")]
  node_events["Audit events<br/>[logs.py]"]
end

node_employees(("Employees"))
node_agents(("IT agents"))
node_supervisors(("Supervisors"))
node_mail_teams["Email and Teams"]
node_database_engine[("SQLite or Postgres")]

node_employees -->|"describe issue"| node_employee_ui
node_agents -->|"work tickets"| node_ticket_ui
node_supervisors -->|"manage service"| node_admin_ui
node_employee_ui -->|"call API"| node_ui_client
node_ticket_ui -->|"call API"| node_ui_client
node_admin_ui -->|"call API"| node_ui_client
node_ui_client -->|"HTTP requests"| node_api
node_api -->|"authenticate"| node_auth
node_api -->|"route conversations"| node_orchestrator
node_api -->|"process uploads"| node_attachments
node_api -->|"route ticket actions"| node_tickets
node_api -->|"serve analytics"| node_analytics
node_api -->|"manage articles"| node_kb_admin
node_api -->|"serve privacy actions"| node_privacy
node_orchestrator -->|"request judgments"| node_jev
node_orchestrator -->|"apply policy"| node_knowledge
node_orchestrator -->|"use OCR evidence"| node_attachments
node_orchestrator -->|"invoke verified actions"| node_tools
node_orchestrator -->|"request transitions"| node_tickets
node_orchestrator -->|"escalate cases"| node_alerts
node_orchestrator -->|"send updates"| node_notify
node_tickets -->|"raise alerts"| node_alerts
node_alerts -->|"read routing and SLA"| node_knowledge
node_analytics -->|"read ticket data"| node_tickets
node_worker -->|"tick timers"| node_alerts
node_worker -->|"sweep tickets"| node_tickets
node_worker -->|"send outbox"| node_notify
node_worker -->|"run retention"| node_privacy
node_notify -.->|"deliver messages"| node_mail_teams
node_auth -->|"read and write"| node_store
node_attachments -->|"save metadata"| node_store
node_tickets -->|"persist lifecycle"| node_store
node_alerts -->|"persist alerts"| node_store
node_notify -->|"persist notifications"| node_store
node_privacy -->|"read and update"| node_store
node_kb_admin -->|"persist articles"| node_store
node_store -->|"use backend"| node_database_engine
node_api -.->|"audit actions"| node_events

click node_employee_ui "https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/employee_chat.py"
click node_ticket_ui "https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/ticket.py"
click node_admin_ui "https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/knowledge.py"
click node_ui_client "https://github.com/pavithra-ssg/sd-assistant/blob/main/ui/client.py"
click node_api "https://github.com/pavithra-ssg/sd-assistant/blob/main/api.py"
click node_auth "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/auth.py"
click node_orchestrator "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/orchestrator.py"
click node_jev "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/brain.py"
click node_knowledge "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/knowledge.py"
click node_attachments "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/attachments.py"
click node_tools "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/tools.py"
click node_tickets "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/tickets.py"
click node_alerts "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/alerts.py"
click node_analytics "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/analytics.py"
click node_kb_admin "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/kb.py"
click node_privacy "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/privacy.py"
click node_notify "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/notify.py"
click node_worker "https://github.com/pavithra-ssg/sd-assistant/blob/main/worker.py"
click node_store "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/store.py"
click node_events "https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/logs.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_employee_ui,node_ticket_ui,node_admin_ui,node_ui_client toneBlue
class node_api,node_auth,node_database_engine toneAmber
class node_orchestrator,node_jev,node_knowledge,node_attachments,node_tools toneMint
class node_tickets,node_alerts,node_analytics,node_kb_admin,node_privacy,node_notify,node_worker toneRose
class node_store,node_events,node_employees,node_agents,node_supervisors,node_mail_teams toneIndigo
```

## Components

### User experience

- [Chat and forms](https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/employee_chat.py): `pages/employee_chat.py`
- [Ticket views](https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/ticket.py): `pages/ticket.py`
- [Admin and insights](https://github.com/pavithra-ssg/sd-assistant/blob/main/pages/knowledge.py): `pages/knowledge.py`
- [HTTP client](https://github.com/pavithra-ssg/sd-assistant/blob/main/ui/client.py): `ui/client.py`

### API and identity

- [FastAPI routes](https://github.com/pavithra-ssg/sd-assistant/blob/main/api.py): `api.py`
- [Authentication](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/auth.py): `servicedesk/services/auth.py`

### Guided support

- [Conversation policy](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/orchestrator.py): `servicedesk/orchestrator.py`
- [Jev judgments](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/brain.py): `servicedesk/brain.py`
- [Knowledge and policy](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/knowledge.py): `servicedesk/knowledge.py`
- [Screenshot OCR](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/attachments.py): `servicedesk/services/attachments.py`
- [Verified tools](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/tools.py): `servicedesk/tools.py`

### Ticket operations

- [Ticket lifecycle](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/tickets.py): `servicedesk/services/tickets.py`
- [Alerts and SLA](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/alerts.py): `servicedesk/services/alerts.py`
- [Service analytics](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/analytics.py): `servicedesk/services/analytics.py`
- [Article management](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/kb.py): `servicedesk/services/kb.py`
- [Privacy controls](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/privacy.py): `servicedesk/services/privacy.py`
- [Notifications](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/services/notify.py): `servicedesk/services/notify.py`
- [Background worker](https://github.com/pavithra-ssg/sd-assistant/blob/main/worker.py): `worker.py`

### Data and services

- [Relational store](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/store.py): `servicedesk/store.py`
- [Audit events](https://github.com/pavithra-ssg/sd-assistant/blob/main/servicedesk/logs.py): `servicedesk/logs.py`

### Other components

- **Employees**
- **IT agents**
- **Supervisors**
- **Email and Teams**
- **SQLite or Postgres**

## Connections

- Employees → Chat and forms: describe issue
- IT agents → Ticket views: work tickets
- Supervisors → Admin and insights: manage service
- Chat and forms → HTTP client: call API (evidence: `ui/client.py`)
- Ticket views → HTTP client: call API (evidence: `ui/client.py`)
- Admin and insights → HTTP client: call API (evidence: `ui/client.py`)
- HTTP client → FastAPI routes: HTTP requests (evidence: `ui/client.py`)
- FastAPI routes → Authentication: authenticate (evidence: `api.py`)
- FastAPI routes → Conversation policy: route conversations (evidence: `api.py`)
- FastAPI routes → Screenshot OCR: process uploads (evidence: `api.py`)
- FastAPI routes → Ticket lifecycle: route ticket actions (evidence: `api.py`)
- FastAPI routes → Service analytics: serve analytics (evidence: `api.py`)
- FastAPI routes → Article management: manage articles (evidence: `api.py`)
- FastAPI routes → Privacy controls: serve privacy actions (evidence: `api.py`)
- Conversation policy → Jev judgments: request judgments (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Knowledge and policy: apply policy (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Screenshot OCR: use OCR evidence (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Verified tools: invoke verified actions (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Ticket lifecycle: request transitions (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Alerts and SLA: escalate cases (evidence: `servicedesk/orchestrator.py`)
- Conversation policy → Notifications: send updates (evidence: `servicedesk/orchestrator.py`)
- Ticket lifecycle → Alerts and SLA: raise alerts (evidence: `servicedesk/services/tickets.py`)
- Alerts and SLA → Knowledge and policy: read routing and SLA (evidence: `servicedesk/services/alerts.py`)
- Service analytics → Ticket lifecycle: read ticket data (evidence: `servicedesk/services/analytics.py`)
- Background worker → Alerts and SLA: tick timers (evidence: `worker.py`)
- Background worker → Ticket lifecycle: sweep tickets (evidence: `worker.py`)
- Background worker → Notifications: send outbox (evidence: `worker.py`)
- Background worker → Privacy controls: run retention (evidence: `worker.py`)
- Notifications → Email and Teams: deliver messages (evidence: `servicedesk/services/notify.py`)
- Authentication → Relational store: read and write (evidence: `servicedesk/services/auth.py`)
- Screenshot OCR → Relational store: save metadata (evidence: `servicedesk/services/attachments.py`)
- Ticket lifecycle → Relational store: persist lifecycle (evidence: `servicedesk/services/tickets.py`)
- Alerts and SLA → Relational store: persist alerts (evidence: `servicedesk/services/alerts.py`)
- Notifications → Relational store: persist notifications (evidence: `servicedesk/services/notify.py`)
- Privacy controls → Relational store: read and update (evidence: `servicedesk/services/privacy.py`)
- Article management → Relational store: persist articles (evidence: `servicedesk/services/kb.py`)
- Relational store → SQLite or Postgres: use backend (evidence: `servicedesk/store.py`)
- FastAPI routes → Audit events: audit actions (evidence: `api.py`)
