# thebandsoftware/helpdesk_banmd architecture

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

- Interactive diagram: https://gitdiagram.com/thebandsoftware/helpdesk_banmd
- Repository: https://github.com/thebandsoftware/helpdesk_banmd

## Overview

Helpdesk lets employees identify themselves, report IT issues, follow their tickets, and attach images or comment; IT staff can review, assign, prioritize, and resolve them, with category statistics. The React app routes users to feature pages, which communicate with a Spring REST API; backend services enforce business rules and use repositories for MariaDB persistence. Attachments additionally use S3-compatible storage. The README documents the overall frontend/API/database relationship; individual feature-to-API calls are not established by the excerpts, so those edges are omitted.

Main entry points: [`backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java) (Ticket rules), [`backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java) (Attachment rules), [`frontend/src/App.tsx`](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/App.tsx) (Page router), [`backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java`](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java) (Comment rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Page router<br/>[App.tsx]"]
  node_ticket_pages["Ticket pages<br/>[TicketDetail.tsx]"]
  node_user_pages["User selection<br/>[UserList.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
end

subgraph group_api["REST API"]
  node_ticket_api["Ticket endpoints"]
  node_comment_api["Comment endpoints"]
  node_attachment_api["Attachment endpoints"]
  node_user_api["User endpoints"]
  node_ticket_detail_dto["Ticket detail DTO"]
  node_ticket_summary_dto["Ticket summary DTO"]
  node_api_errors["API error handling"]
end

subgraph group_domain["Ticket operations"]
  node_ticket_service["Ticket rules<br/>[TicketService.java]"]
  node_comment_service["Comment rules"]
  node_user_service["User operations<br/>[UserService.java]"]
  node_ticket_mapper["Ticket mapping<br/>[TicketMapper.java]"]
  node_ticket_entity["Ticket entity<br/>[Ticket.java]"]
  node_user_entity["User entity<br/>[User.java]"]
  node_category_enum["Ticket categories<br/>[Category.java]"]
  node_role_enum["User roles<br/>[Role.java]"]
  node_status_enum["Ticket statuses<br/>[Status.java]"]
end

subgraph group_persistence["Persistence"]
  node_ticket_repo["Ticket repository"]
  node_user_repo["User repository"]
  node_mariadb[("MariaDB")]
  node_comment_repo["Comment repository"]
end

subgraph group_files["File attachments"]
  node_attachment_service["Attachment rules"]
  node_attachment_repo["Attachment repository"]
  node_storage_port["File storage interface"]
  node_s3_storage["S3 storage adapter"]
  node_attachment_entity["Attachment entity<br/>[Attachment.java]"]
end

node_employee(("Employee or IT staff"))
node_object_store[("S3-compatible bucket")]

node_employee -->|"uses"| node_app
node_app -->|"routes to"| node_ticket_pages
node_app -->|"routes to"| node_user_pages
node_app -.->|"provides API client"| node_api_client
node_api_client -.->|"calls /api"| node_ticket_api
node_ticket_api -->|"delegates to"| node_ticket_service
node_comment_api -->|"delegates to"| node_comment_service
node_attachment_api -->|"delegates to"| node_attachment_service
node_ticket_service -->|"queries and saves"| node_ticket_repo
node_ticket_service -->|"looks up users"| node_user_repo
node_ticket_service -->|"maps responses"| node_ticket_mapper
node_ticket_repo -->|"persists records"| node_mariadb
node_user_repo -->|"persists records"| node_mariadb
node_comment_service -->|"reads and saves"| node_comment_repo
node_comment_service -->|"checks ticket"| node_ticket_repo
node_comment_service -->|"looks up author"| node_user_repo
node_attachment_service -->|"reads and saves"| node_attachment_repo
node_attachment_service -->|"checks ticket"| node_ticket_repo
node_attachment_service -->|"checks uploader"| node_user_repo
node_attachment_service -->|"stores file bytes"| node_storage_port
node_s3_storage -->|"reads and writes objects"| node_object_store
node_s3_storage -->|"implements"| node_storage_port
node_ticket_service -->|"creates and updates"| node_ticket_entity
node_ticket_service -->|"returns"| node_ticket_detail_dto
node_ticket_service -->|"returns"| node_ticket_summary_dto
node_ticket_entity -->|"uses category"| node_category_enum
node_ticket_entity -->|"uses status"| node_status_enum
node_ticket_entity -->|"references users"| node_user_entity
node_attachment_service -->|"creates metadata"| node_attachment_entity

click node_app "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/App.tsx"
click node_ticket_pages "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/features/tickets/TicketDetail.tsx"
click node_user_pages "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/features/users/UserList.tsx"
click node_api_client "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/shared/apiClient.ts"
click node_ticket_api "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/TicketController.java"
click node_comment_api "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/CommentController.java"
click node_attachment_api "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/AttachmentController.java"
click node_user_api "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/UserController.java"
click node_ticket_service "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java"
click node_comment_service "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java"
click node_user_service "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/UserService.java"
click node_ticket_mapper "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/mappers/TicketMapper.java"
click node_ticket_repo "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/TicketRepository.java"
click node_user_repo "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/UserRepository.java"
click node_attachment_service "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java"
click node_attachment_repo "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/AttachmentRepository.java"
click node_storage_port "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/FileStorageService.java"
click node_s3_storage "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/S3FileStorageService.java"
click node_comment_repo "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/CommentRepository.java"
click node_ticket_entity "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java"
click node_user_entity "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/User.java"
click node_attachment_entity "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Attachment.java"
click node_ticket_detail_dto "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketDetailResponse.java"
click node_ticket_summary_dto "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketSummaryResponse.java"
click node_category_enum "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Category.java"
click node_role_enum "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Role.java"
click node_status_enum "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Status.java"
click node_api_errors "https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/exceptions/ApiExceptionHandler.java"

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_app,node_ticket_pages,node_user_pages,node_api_client toneBlue
class node_ticket_api,node_comment_api,node_attachment_api,node_user_api,node_ticket_detail_dto,node_ticket_summary_dto,node_api_errors,node_object_store toneAmber
class node_ticket_service,node_comment_service,node_user_service,node_ticket_mapper,node_ticket_entity,node_user_entity,node_category_enum,node_role_enum,node_status_enum toneMint
class node_ticket_repo,node_user_repo,node_mariadb,node_comment_repo toneRose
class node_attachment_service,node_attachment_repo,node_storage_port,node_s3_storage,node_attachment_entity,node_employee toneIndigo
```

## Components

### Web application

- [Page router](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Ticket pages](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/features/tickets/TicketDetail.tsx): `frontend/src/features/tickets/TicketDetail.tsx`
- [User selection](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/features/users/UserList.tsx): `frontend/src/features/users/UserList.tsx`
- [API client](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/frontend/src/shared/apiClient.ts): `frontend/src/shared/apiClient.ts`

### REST API

- [Ticket endpoints](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/TicketController.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/TicketController.java`
- [Comment endpoints](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/CommentController.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/CommentController.java`
- [Attachment endpoints](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/AttachmentController.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/AttachmentController.java`
- [User endpoints](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/UserController.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/UserController.java`
- [Ticket detail DTO](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketDetailResponse.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketDetailResponse.java`
- [Ticket summary DTO](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketSummaryResponse.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/dtos/TicketSummaryResponse.java`
- [API error handling](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/exceptions/ApiExceptionHandler.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/exceptions/ApiExceptionHandler.java`

### Ticket operations

- [Ticket rules](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`
- [Comment rules](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java`
- [User operations](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/UserService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/UserService.java`
- [Ticket mapping](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/mappers/TicketMapper.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/mappers/TicketMapper.java`
- [Ticket entity](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java`
- [User entity](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/User.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/User.java`
- [Ticket categories](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Category.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Category.java`
- [User roles](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Role.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Role.java`
- [Ticket statuses](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Status.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/enums/Status.java`

### Persistence

- [Ticket repository](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/TicketRepository.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/TicketRepository.java`
- [User repository](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/UserRepository.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/UserRepository.java`
- **MariaDB**
- [Comment repository](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/CommentRepository.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/CommentRepository.java`

### File attachments

- [Attachment rules](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`
- [Attachment repository](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/AttachmentRepository.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/repositories/AttachmentRepository.java`
- [File storage interface](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/FileStorageService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/FileStorageService.java`
- [S3 storage adapter](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/S3FileStorageService.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/S3FileStorageService.java`
- [Attachment entity](https://github.com/thebandsoftware/helpdesk_banmd/blob/develop/backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Attachment.java): `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Attachment.java`

### Other components

- **Employee or IT staff**
- **S3-compatible bucket**

## Connections

- Employee or IT staff → Page router: uses (evidence: `frontend/src/App.tsx`)
- Page router → Ticket pages: routes to (evidence: `frontend/src/App.tsx`)
- Page router → User selection: routes to (evidence: `frontend/src/App.tsx`)
- Page router → API client: provides API client
- API client → Ticket endpoints: calls /api
- Ticket endpoints → Ticket rules: delegates to (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/TicketController.java`)
- Comment endpoints → Comment rules: delegates to (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/CommentController.java`)
- Attachment endpoints → Attachment rules: delegates to (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/controllers/AttachmentController.java`)
- Ticket rules → Ticket repository: queries and saves (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket rules → User repository: looks up users (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket rules → Ticket mapping: maps responses (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket repository → MariaDB: persists records (evidence: `README.md`)
- User repository → MariaDB: persists records (evidence: `README.md`)
- Comment rules → Comment repository: reads and saves (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java`)
- Comment rules → Ticket repository: checks ticket (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java`)
- Comment rules → User repository: looks up author (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/CommentService.java`)
- Attachment rules → Attachment repository: reads and saves (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`)
- Attachment rules → Ticket repository: checks ticket (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`)
- Attachment rules → User repository: checks uploader (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`)
- Attachment rules → File storage interface: stores file bytes (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`)
- S3 storage adapter → S3-compatible bucket: reads and writes objects (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/S3FileStorageService.java`)
- S3 storage adapter → File storage interface: implements (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/S3FileStorageService.java`)
- Ticket rules → Ticket entity: creates and updates (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket rules → Ticket detail DTO: returns (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket rules → Ticket summary DTO: returns (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/TicketService.java`)
- Ticket entity → Ticket categories: uses category (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java`)
- Ticket entity → Ticket statuses: uses status (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java`)
- Ticket entity → User entity: references users (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/entities/Ticket.java`)
- Attachment rules → Attachment entity: creates metadata (evidence: `backend/helpdesk/src/main/java/com/thebanmd/helpdesk/services/AttachmentService.java`)