# jnobr3c/helpdesk-api architecture

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

- Interactive diagram: https://gitdiagram.com/jnobr3c/helpdesk-api
- Repository: https://github.com/jnobr3c/helpdesk-api

## Overview

Helpdesk API is a Spring Boot REST service for managing customers, technicians, and support tickets. A client request reaches the REST resources, whose services apply CRUD and ticket-assignment rules before using JPA repositories and the configured database. Authentication is a separate path: Spring Security uses JWT filters and user lookup to authenticate requests and enforce role-based access. The README documents H2/MySQL support and the principal capabilities; some resource and security wiring is unsampled, so only documented or indexed relationships are shown.

Main entry points: [`src/main/java/com/nobre/helpdesk/services/ChamadoService.java`](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ChamadoService.java) (Ticket Service), [`src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java`](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java) (JWT Authentication), [`src/main/java/com/nobre/helpdesk/services/ClienteService.java`](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ClienteService.java) (Customer Service), [`src/main/java/com/nobre/helpdesk/services/TecnicoService.java`](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/TecnicoService.java) (Technician Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_customer_api["Customer Endpoints"]
  node_technician_api["Technician Endpoints"]
  node_ticket_api["Ticket Endpoints"]
  node_errors["API Error Mapping"]
end

subgraph group_business["Helpdesk Domain"]
  node_customer_service["Customer Service"]
  node_technician_service["Technician Service"]
  node_ticket_service["Ticket Service"]
  node_domain["Entities, DTOs &amp; Enums"]
end

subgraph group_security["JWT Security"]
  node_security_config["Security Configuration"]
  node_jwt_auth["JWT Authentication"]
  node_jwt_authorization["JWT Authorization"]
  node_jwt_util["JWT Utilities<br/>[JWTUtil.java]"]
  node_user_details["User Lookup"]
  node_user_identity["Security Principal<br/>[UserSS.java]"]
end

subgraph group_persistence["Persistence"]
  node_customer_repo["Customer Repository"]
  node_technician_repo["Technician Repository"]
  node_ticket_repo["Ticket Repository"]
  node_person_repo["Person Repository"]
  node_database[("Relational Database")]
  node_seed_data["Sample Data Setup<br/>[DBService.java]"]
end

node_client(("API Client"))

node_client -->|"manages customers"| node_customer_api
node_client -->|"manages technicians"| node_technician_api
node_client -->|"manages tickets"| node_ticket_api
node_customer_api -->|"delegates to"| node_customer_service
node_technician_api -->|"delegates to"| node_technician_service
node_ticket_api -.->|"delegates to"| node_ticket_service
node_customer_service -->|"reads and writes"| node_customer_repo
node_customer_service -->|"checks identity"| node_person_repo
node_technician_service -->|"reads and writes"| node_technician_repo
node_technician_service -->|"checks identity"| node_person_repo
node_ticket_service -->|"reads and writes"| node_ticket_repo
node_ticket_service -->|"looks up technician"| node_technician_service
node_ticket_service -->|"looks up customer"| node_customer_service
node_customer_repo -->|"persists entities"| node_database
node_technician_repo -->|"persists entities"| node_database
node_ticket_repo -->|"persists entities"| node_database
node_person_repo -->|"persists entities"| node_database
node_seed_data -->|"saves sample data"| node_technician_repo
node_seed_data -->|"saves sample data"| node_customer_repo
node_seed_data -->|"saves sample data"| node_ticket_repo
node_security_config -->|"configures filter"| node_jwt_auth
node_security_config -->|"configures filter"| node_jwt_authorization
node_jwt_auth -->|"creates tokens"| node_jwt_util
node_jwt_authorization -->|"validates tokens"| node_jwt_util
node_jwt_auth -.->|"loads identity"| node_user_details
node_user_details -->|"finds user"| node_person_repo
node_user_details -->|"builds principal"| node_user_identity
node_jwt_auth -->|"uses principal"| node_user_identity

click node_customer_api "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/ClienteResource.java"
click node_technician_api "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/TecnicoResource.java"
click node_ticket_api "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/ChamadoResource.java"
click node_errors "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/exceptions/ResourceExceptionHandler.java"
click node_customer_service "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ClienteService.java"
click node_technician_service "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/TecnicoService.java"
click node_ticket_service "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ChamadoService.java"
click node_domain "https://github.com/jnobr3c/helpdesk-api/tree/main/src/main/java/com/nobre/helpdesk/domain"
click node_customer_repo "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/ClienteRepository.java"
click node_technician_repo "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/TecnicoRepository.java"
click node_ticket_repo "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/ChamadoRepository.java"
click node_person_repo "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/PessoaRepository.java"
click node_seed_data "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/DBService.java"
click node_security_config "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/config/SecurityConfig.java"
click node_jwt_auth "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java"
click node_jwt_authorization "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTAuthorizationFilter.java"
click node_jwt_util "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTUtil.java"
click node_user_details "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/UserDetailsServiceImpl.java"
click node_user_identity "https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/UserSS.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_customer_api,node_technician_api,node_ticket_api,node_errors,node_client toneBlue
class node_customer_service,node_technician_service,node_ticket_service,node_domain toneAmber
class node_security_config,node_jwt_auth,node_jwt_authorization,node_jwt_util,node_user_details,node_user_identity toneMint
class node_customer_repo,node_technician_repo,node_ticket_repo,node_person_repo,node_database,node_seed_data toneRose
```

## Components

### REST API

- [Customer Endpoints](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/ClienteResource.java): `src/main/java/com/nobre/helpdesk/resources/ClienteResource.java`
- [Technician Endpoints](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/TecnicoResource.java): `src/main/java/com/nobre/helpdesk/resources/TecnicoResource.java`
- [Ticket Endpoints](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/ChamadoResource.java): `src/main/java/com/nobre/helpdesk/resources/ChamadoResource.java`
- [API Error Mapping](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/resources/exceptions/ResourceExceptionHandler.java): `src/main/java/com/nobre/helpdesk/resources/exceptions/ResourceExceptionHandler.java`

### Helpdesk Domain

- [Customer Service](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ClienteService.java): `src/main/java/com/nobre/helpdesk/services/ClienteService.java`
- [Technician Service](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/TecnicoService.java): `src/main/java/com/nobre/helpdesk/services/TecnicoService.java`
- [Ticket Service](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/ChamadoService.java): `src/main/java/com/nobre/helpdesk/services/ChamadoService.java`
- [Entities, DTOs & Enums](https://github.com/jnobr3c/helpdesk-api/tree/main/src/main/java/com/nobre/helpdesk/domain): `src/main/java/com/nobre/helpdesk/domain`

### JWT Security

- [Security Configuration](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/config/SecurityConfig.java): `src/main/java/com/nobre/helpdesk/config/SecurityConfig.java`
- [JWT Authentication](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java): `src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java`
- [JWT Authorization](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTAuthorizationFilter.java): `src/main/java/com/nobre/helpdesk/security/JWTAuthorizationFilter.java`
- [JWT Utilities](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/JWTUtil.java): `src/main/java/com/nobre/helpdesk/security/JWTUtil.java`
- [User Lookup](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/UserDetailsServiceImpl.java): `src/main/java/com/nobre/helpdesk/services/UserDetailsServiceImpl.java`
- [Security Principal](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/security/UserSS.java): `src/main/java/com/nobre/helpdesk/security/UserSS.java`

### Persistence

- [Customer Repository](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/ClienteRepository.java): `src/main/java/com/nobre/helpdesk/repositories/ClienteRepository.java`
- [Technician Repository](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/TecnicoRepository.java): `src/main/java/com/nobre/helpdesk/repositories/TecnicoRepository.java`
- [Ticket Repository](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/ChamadoRepository.java): `src/main/java/com/nobre/helpdesk/repositories/ChamadoRepository.java`
- [Person Repository](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/repositories/PessoaRepository.java): `src/main/java/com/nobre/helpdesk/repositories/PessoaRepository.java`
- **Relational Database**
- [Sample Data Setup](https://github.com/jnobr3c/helpdesk-api/blob/main/src/main/java/com/nobre/helpdesk/services/DBService.java): `src/main/java/com/nobre/helpdesk/services/DBService.java`

### Other components

- **API Client**

## Connections

- API Client → Customer Endpoints: manages customers (evidence: `README.md`)
- API Client → Technician Endpoints: manages technicians (evidence: `README.md`)
- API Client → Ticket Endpoints: manages tickets (evidence: `README.md`)
- Customer Endpoints → Customer Service: delegates to (evidence: `src/main/java/com/nobre/helpdesk/resources/ClienteResource.java`)
- Technician Endpoints → Technician Service: delegates to (evidence: `src/main/java/com/nobre/helpdesk/resources/TecnicoResource.java`)
- Ticket Endpoints → Ticket Service: delegates to (evidence: `README.md`)
- Customer Service → Customer Repository: reads and writes (evidence: `src/main/java/com/nobre/helpdesk/services/ClienteService.java`)
- Customer Service → Person Repository: checks identity (evidence: `src/main/java/com/nobre/helpdesk/services/ClienteService.java`)
- Technician Service → Technician Repository: reads and writes (evidence: `src/main/java/com/nobre/helpdesk/services/TecnicoService.java`)
- Technician Service → Person Repository: checks identity (evidence: `src/main/java/com/nobre/helpdesk/services/TecnicoService.java`)
- Ticket Service → Ticket Repository: reads and writes (evidence: `src/main/java/com/nobre/helpdesk/services/ChamadoService.java`)
- Ticket Service → Technician Service: looks up technician (evidence: `src/main/java/com/nobre/helpdesk/services/ChamadoService.java`)
- Ticket Service → Customer Service: looks up customer (evidence: `src/main/java/com/nobre/helpdesk/services/ChamadoService.java`)
- Customer Repository → Relational Database: persists entities (evidence: `README.md`)
- Technician Repository → Relational Database: persists entities (evidence: `README.md`)
- Ticket Repository → Relational Database: persists entities (evidence: `README.md`)
- Person Repository → Relational Database: persists entities (evidence: `README.md`)
- Sample Data Setup → Technician Repository: saves sample data (evidence: `src/main/java/com/nobre/helpdesk/services/DBService.java`)
- Sample Data Setup → Customer Repository: saves sample data (evidence: `src/main/java/com/nobre/helpdesk/services/DBService.java`)
- Sample Data Setup → Ticket Repository: saves sample data (evidence: `src/main/java/com/nobre/helpdesk/services/DBService.java`)
- Security Configuration → JWT Authentication: configures filter (evidence: `src/main/java/com/nobre/helpdesk/config/SecurityConfig.java`)
- Security Configuration → JWT Authorization: configures filter (evidence: `src/main/java/com/nobre/helpdesk/config/SecurityConfig.java`)
- JWT Authentication → JWT Utilities: creates tokens (evidence: `src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java`)
- JWT Authorization → JWT Utilities: validates tokens (evidence: `src/main/java/com/nobre/helpdesk/security/JWTAuthorizationFilter.java`)
- JWT Authentication → User Lookup: loads identity
- User Lookup → Person Repository: finds user (evidence: `src/main/java/com/nobre/helpdesk/services/UserDetailsServiceImpl.java`)
- User Lookup → Security Principal: builds principal (evidence: `src/main/java/com/nobre/helpdesk/services/UserDetailsServiceImpl.java`)
- JWT Authentication → Security Principal: uses principal (evidence: `src/main/java/com/nobre/helpdesk/security/JWTAuthenticationFilter.java`)
