# ittzspsv/lily-support architecture

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

- Interactive diagram: https://gitdiagram.com/ittzspsv/lily-support
- Repository: https://github.com/ittzspsv/lily-support

## Overview

This repository implements a helpdesk/support-ticket product with a Next.js interface and FastAPI backend. Its main workflow is user authentication, ticket creation and management, attachment handling, and ticket collaboration; administrative routes manage users and agents. The backend also exposes configurable ticket forms, role-based access, and WebSocket support. Relationships below are limited to imports and calls evidenced by sampled files or the SOURCE INDEX; unsampled ticket, role, and frontend wiring is not asserted.

Main entry points: [`backend/src/main.py`](https://github.com/ittzspsv/lily-support/blob/main/backend/src/main.py) (FastAPI app), [`backend/src/services/auth.py`](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/auth.py) (Authentication), [`backend/src/api/routes/tickets/tickets.py`](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/tickets/tickets.py) (Ticket routes), [`backend/src/api/routes/admin`](https://github.com/ittzspsv/lily-support/tree/main/backend/src/api/routes/admin) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_webapp["Next.js app"]
  node_ticketui["Ticket workspace"]
  node_ticketuihooks["Ticket hooks"]
  node_supportform["Support form<br/>[useSupportForm.ts]"]
  node_frontendapi["API clients"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_authroute["Auth routes<br/>[auth.py]"]
  node_ticketroute["Ticket routes<br/>[tickets.py]"]
  node_formroute["Form routes<br/>[forms.py]"]
  node_attachmentroute["Attachment routes<br/>[attachments.py]"]
  node_adminroutes["Admin routes"]
  node_roleadmin["Role administration<br/>[roles.py]"]
  node_skillsroute["Agent skills routes<br/>[skills.py]"]
end

subgraph group_identity["Identity and access"]
  node_authservice["Authentication<br/>[auth.py]"]
  node_authguard["Auth dependencies<br/>[auth.py]"]
  node_userservice["User service<br/>[users.py]"]
  node_roleservice["Role service<br/>[roles.py]"]
  node_credentialservice["Credential service<br/>[credintials.py]"]
  node_tokenservice["Token service<br/>[token.py]"]
end

subgraph group_ticketing["Ticket operations"]
  node_ticketservice["Ticket service<br/>[tickets.py]"]
  node_ticketconfig["Ticket configuration<br/>[tickets.py]"]
  node_websocket["WebSocket connection<br/>[connection.py]"]
  node_agentservice["Agent service<br/>[agents.py]"]
end

subgraph group_data["Persistence and integrations"]
  node_storageapi["Object storage service<br/>[storage.py]"]
  node_database[("Database<br/>[database.py]")]
  node_ticketmodels[("Ticket models<br/>[tickets.py]")]
  node_usermodels[("User models<br/>[user.py]")]
  node_objectstore[("S3-compatible storage")]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_server -->|"registers"| node_authroute
node_server -->|"registers"| node_ticketroute
node_server -->|"registers"| node_attachmentroute
node_server -->|"registers"| node_adminroutes
node_server -->|"registers"| node_formroute
node_server -->|"creates tables"| node_database
node_authroute -->|"invokes"| node_authservice
node_authroute -->|"uses guards"| node_authguard
node_authguard -->|"validates tokens"| node_authservice
node_authguard -->|"loads user"| node_userservice
node_authguard -->|"checks revocation"| node_tokenservice
node_authservice -->|"uses"| node_userservice
node_authservice -->|"loads default roles"| node_roleservice
node_authservice -->|"uses credentials"| node_credentialservice
node_authservice -->|"uses role model"| node_usermodels
node_ticketroute -->|"uses"| node_ticketservice
node_ticketroute -->|"uses events"| node_websocket
node_ticketroute -->|"uses configuration"| node_ticketconfig
node_attachmentroute -->|"requests storage"| node_storageapi
node_storageapi -->|"generates signed URLs"| node_objectstore
node_storageapi -->|"loads settings"| node_ticketconfig
node_formroute -->|"uses forms"| node_ticketconfig
node_adminroutes -->|"manages agents"| node_agentservice
node_adminroutes -->|"manages users"| node_userservice
node_adminroutes -.->|"includes role routes"| node_roleadmin
node_webapp -.->|"calls API"| node_frontendapi
node_ticketui -.->|"uses hooks"| node_ticketuihooks
node_supportform -.->|"submits form"| node_frontendapi
node_frontendapi -.->|"requests tickets"| node_ticketroute

click node_webapp "https://github.com/ittzspsv/lily-support/tree/main/frontend/src/app"
click node_ticketui "https://github.com/ittzspsv/lily-support/blob/main/frontend/src/components/ui/tickets/TicketWorkspace.tsx"
click node_ticketuihooks "https://github.com/ittzspsv/lily-support/tree/main/frontend/src/features/hooks/tickets"
click node_supportform "https://github.com/ittzspsv/lily-support/blob/main/frontend/src/features/hooks/useSupportForm.ts"
click node_frontendapi "https://github.com/ittzspsv/lily-support/tree/main/frontend/src/api"
click node_server "https://github.com/ittzspsv/lily-support/blob/main/backend/src/main.py"
click node_authroute "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/auth/auth.py"
click node_ticketroute "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/tickets/tickets.py"
click node_formroute "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/forms/forms.py"
click node_attachmentroute "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/attachments/attachments.py"
click node_adminroutes "https://github.com/ittzspsv/lily-support/tree/main/backend/src/api/routes/admin"
click node_authservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/auth.py"
click node_authguard "https://github.com/ittzspsv/lily-support/blob/main/backend/src/dependencies/auth.py"
click node_userservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/users.py"
click node_roleservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/roles.py"
click node_ticketservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/tickets.py"
click node_ticketconfig "https://github.com/ittzspsv/lily-support/blob/main/backend/src/configs/tickets.py"
click node_websocket "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/websockets/connection.py"
click node_agentservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/agents.py"
click node_storageapi "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/storage.py"
click node_database "https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/database.py"
click node_ticketmodels "https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/models/tickets.py"
click node_usermodels "https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/models/user.py"
click node_credentialservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/credintials.py"
click node_tokenservice "https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/token.py"
click node_roleadmin "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/admin/roles.py"
click node_skillsroute "https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/users/skills/skills.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_webapp,node_ticketui,node_ticketuihooks,node_supportform,node_frontendapi,node_user toneBlue
class node_server,node_authroute,node_ticketroute,node_formroute,node_attachmentroute,node_adminroutes,node_roleadmin,node_skillsroute toneAmber
class node_authservice,node_authguard,node_userservice,node_roleservice,node_credentialservice,node_tokenservice toneMint
class node_ticketservice,node_ticketconfig,node_websocket,node_agentservice toneRose
class node_storageapi,node_database,node_ticketmodels,node_usermodels,node_objectstore toneIndigo
```

## Components

### Web interface

- [Next.js app](https://github.com/ittzspsv/lily-support/tree/main/frontend/src/app): `frontend/src/app`
- [Ticket workspace](https://github.com/ittzspsv/lily-support/blob/main/frontend/src/components/ui/tickets/TicketWorkspace.tsx): `frontend/src/components/ui/tickets/TicketWorkspace.tsx`
- [Ticket hooks](https://github.com/ittzspsv/lily-support/tree/main/frontend/src/features/hooks/tickets): `frontend/src/features/hooks/tickets`
- [Support form](https://github.com/ittzspsv/lily-support/blob/main/frontend/src/features/hooks/useSupportForm.ts): `frontend/src/features/hooks/useSupportForm.ts`
- [API clients](https://github.com/ittzspsv/lily-support/tree/main/frontend/src/api): `frontend/src/api`

### Backend API

- [FastAPI app](https://github.com/ittzspsv/lily-support/blob/main/backend/src/main.py): `backend/src/main.py`
- [Auth routes](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/auth/auth.py): `backend/src/api/routes/auth/auth.py`
- [Ticket routes](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/tickets/tickets.py): `backend/src/api/routes/tickets/tickets.py`
- [Form routes](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/forms/forms.py): `backend/src/api/routes/forms/forms.py`
- [Attachment routes](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/attachments/attachments.py): `backend/src/api/routes/attachments/attachments.py`
- [Admin routes](https://github.com/ittzspsv/lily-support/tree/main/backend/src/api/routes/admin): `backend/src/api/routes/admin`
- [Role administration](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/admin/roles.py): `backend/src/api/routes/admin/roles.py`
- [Agent skills routes](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/routes/users/skills/skills.py): `backend/src/api/routes/users/skills/skills.py`

### Identity and access

- [Authentication](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/auth.py): `backend/src/services/auth.py`
- [Auth dependencies](https://github.com/ittzspsv/lily-support/blob/main/backend/src/dependencies/auth.py): `backend/src/dependencies/auth.py`
- [User service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/users.py): `backend/src/services/users.py`
- [Role service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/roles.py): `backend/src/services/roles.py`
- [Credential service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/credintials.py): `backend/src/services/credintials.py`
- [Token service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/token.py): `backend/src/services/token.py`

### Ticket operations

- [Ticket service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/tickets.py): `backend/src/services/tickets.py`
- [Ticket configuration](https://github.com/ittzspsv/lily-support/blob/main/backend/src/configs/tickets.py): `backend/src/configs/tickets.py`
- [WebSocket connection](https://github.com/ittzspsv/lily-support/blob/main/backend/src/api/websockets/connection.py): `backend/src/api/websockets/connection.py`
- [Agent service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/agents.py): `backend/src/services/agents.py`

### Persistence and integrations

- [Object storage service](https://github.com/ittzspsv/lily-support/blob/main/backend/src/services/storage.py): `backend/src/services/storage.py`
- [Database](https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/database.py): `backend/src/database/database.py`
- [Ticket models](https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/models/tickets.py): `backend/src/database/models/tickets.py`
- [User models](https://github.com/ittzspsv/lily-support/blob/main/backend/src/database/models/user.py): `backend/src/database/models/user.py`
- **S3-compatible storage**

### Other components

- **User**

## Connections

- User → Next.js app: uses
- FastAPI app → Auth routes: registers (evidence: `backend/src/main.py`)
- FastAPI app → Ticket routes: registers (evidence: `backend/src/main.py`)
- FastAPI app → Attachment routes: registers (evidence: `backend/src/main.py`)
- FastAPI app → Admin routes: registers (evidence: `backend/src/main.py`)
- FastAPI app → Form routes: registers (evidence: `backend/src/main.py`)
- FastAPI app → Database: creates tables (evidence: `backend/src/main.py`)
- Auth routes → Authentication: invokes (evidence: `backend/src/api/routes/auth/auth.py`)
- Auth routes → Auth dependencies: uses guards (evidence: `backend/src/api/routes/auth/auth.py`)
- Auth dependencies → Authentication: validates tokens (evidence: `backend/src/dependencies/auth.py`)
- Auth dependencies → User service: loads user (evidence: `backend/src/dependencies/auth.py`)
- Auth dependencies → Token service: checks revocation (evidence: `backend/src/dependencies/auth.py`)
- Authentication → User service: uses (evidence: `backend/src/services/auth.py`)
- Authentication → Role service: loads default roles (evidence: `backend/src/services/auth.py`)
- Authentication → Credential service: uses credentials (evidence: `backend/src/services/auth.py`)
- Authentication → User models: uses role model (evidence: `backend/src/services/auth.py`)
- Ticket routes → Ticket service: uses (evidence: `backend/src/api/routes/tickets/tickets.py`)
- Ticket routes → WebSocket connection: uses events (evidence: `backend/src/api/routes/tickets/tickets.py`)
- Ticket routes → Ticket configuration: uses configuration (evidence: `backend/src/api/routes/tickets/tickets.py`)
- Attachment routes → Object storage service: requests storage (evidence: `backend/src/api/routes/attachments/attachments.py`)
- Object storage service → S3-compatible storage: generates signed URLs (evidence: `backend/src/services/storage.py`)
- Object storage service → Ticket configuration: loads settings (evidence: `backend/src/services/storage.py`)
- Form routes → Ticket configuration: uses forms (evidence: `backend/src/api/routes/forms/forms.py`)
- Admin routes → Agent service: manages agents (evidence: `backend/src/api/routes/admin/agents.py`)
- Admin routes → User service: manages users (evidence: `backend/src/api/routes/admin/users.py`)
- Admin routes → Role administration: includes role routes
- Next.js app → API clients: calls API
- Ticket workspace → Ticket hooks: uses hooks
- Support form → API clients: submits form
- API clients → Ticket routes: requests tickets
