# rogeriobgregorio/ticket-management-system architecture

> Architecture diagram of the GitHub repository rogeriobgregorio/ticket-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rogeriobgregorio/ticket-management-system
- Repository: https://github.com/rogeriobgregorio/ticket-management-system

## Overview

1. **Purpose and shape of the system**
   - This is a Go backend API for technical ticket management (“gestor de chamados”).
   - The repository is organized as a layered application: HTTP entrypoints, application services, domain model, and infrastructure adapters.
   - The main persistent store is **MySQL**; identity is integrated with **LDAP/Active Directory** and tokens are **JWT**.

2. **Application bootstrap and runtime entrypoints**
   - `cmd/api` is the only executable boundary.
   - `main.go` and `comandos.go` expose a small CLI with three operational modes: **server**, **migrate**, and **seed**.
   - `servidor.go` wires the HTTP server, while `logger.go` and `doc.go` support startup/logging/documentation.
   - This means the app can run as a long-lived API process or as a one-off maintenance command against the same config and infrastructure.

3. **Configuration as a first-class subsystem**
   - `internal/config` centralizes environment loading and validation for app, server, database, auth, and LDAP settings.
   - The README shows strong startup validation: ports, timeouts, CORS, JWT secrets, DB connectivity, and environment mode.
   - This is an important architectural boundary because the application is expected to fail fast if deployment settings are invalid.

4. **HTTP layer: request translation, not business logic**
   - `internal/http` contains the public API surface:
     - `handler` packages per resource
     - `router` packages per route group
     - `middleware` for CORS and panic recovery
     - `dto` for request/response shapes
   - Handlers convert HTTP payloads and query parameters into domain/service calls, then map results back into API responses.
   - The DTO layer is a deliberate boundary so domain entities are not exposed directly over the wire.

5. **Authentication and authorization subsystem**
   - `internal/auth` handles login, token issuance, claims, and authorization checks.
   - LDAP is used to validate credentials; JWT access/refresh tokens are then issued for API usage.
   - Authorization is role- and permission-based, with permissions like `ADM`, `TEC`, `USR`, and `DEV`.
   - This subsystem sits between HTTP middleware/handlers and the domain services, enforcing access before business operations execute.

6. **Domain model: business concepts and invariants**
   - `internal/domain` contains the core business entities and their rules.
   - Main aggregates/entities are:
     - `chamado` (ticket)
     - `usuario`
     - `categoria` / `subcategoria`
     - `atendimento` (assignment)
     - `acompanhamento` (comments/follow-up)
     - `categoria_permissao` (category-scoped access)
     - `log` (auditing)
   - Domain packages also define filters, repository interfaces, pagination, identifiers, and validation/error types.
   - This layer is framework-independent and is where state transitions such as ticket status changes are expected to be validated.

7. **Application services: orchestration of use cases**
   - `internal/service` is the use-case layer.
   - Each service package coordinates domain entities and repository interfaces for operations like creating tickets, assigning technicians, adding comments, updating users, and querying paginated lists.
   - The services likely enforce cross-entity rules such as status transitions, permission checks, and audit logging.
   - Tests exist here as well, which suggests this layer carries most of the business logic.

8. **Infrastructure adapters: persistence and system concerns**
   - `internal/infra/mysql` contains concrete MySQL repository implementations for each domain area.
   - `internal/infra/migrations` manages schema creation and versioning, with SQL migrations and seed data.
   - `internal/infra/id` provides ID generation, specifically UUIDv7-style IDs.
   - `internal/infra/container` assembles the object graph, connecting HTTP handlers, services, repositories, auth, and configuration.

9. **Main data flow through the system**
   - A request enters the HTTP router, passes middleware, and reaches the relevant handler.
   - The handler parses DTOs and query filters, then invokes a service.
   - The service applies business rules using domain types and repository interfaces.
   - The repository implementation persists or reads data from MySQL.
   - For login flows, the path is slightly different: HTTP -> auth -> LDAP validation -> local user lookup/creation -> JWT issuance.

10. **Ticketing lifecycle and core business boundaries**
   - The central workflow is the ticket lifecycle: `ABERTO -> ATRIBUIDO -> RESOLVIDO -> FECHADO`, with `REJEITADO` as a terminal alternative.
   - Related subsystems support that workflow:
     - `atendimento` links technicians to tickets
     - `acompanhamento` stores comments and progress updates
     - `categoria` / `subcategoria` classify tickets
     - `categoria_permissao` scopes technician access by category
   - `log` captures audit events, and is intentionally restricted to `DEV` access in the API.

11. **Operational concerns**
   - The API exposes Swagger docs under `docs/` and through a dedicated router.
   - Standardized error handling follows Problem Details-style responses, which is important for consumers and for diagramming the error boundary.
   - Pagination and filtering are pervasive in list endpoints, so query parsing is a shared HTTP concern rather than embedded in services.

12. **Deployment and local development**
   - `deploy/docker-compose.yml` brings up MySQL and an OpenLDAP instance for local development/testing.
   - `scripts/` and `Makefile` suggest repeatable operational tasks, though the real operational control is the CLI under `cmd/api`.
   - Database schema and seed data are managed through the app itself, not as an external migration tool.

13. **What to draw in an architecture diagram**
   - Show four major application layers: **HTTP/API**, **Auth**, **Service/Use Cases**, **Domain**, and **Infrastructure**.
   - Show two external systems: **MySQL** for persistence and **LDAP/AD** for authentication.
   - Show a container/bootstrap edge in `cmd/api` that wires everything together.
   - Emphasize the one-way dependencies inward: HTTP and infra depend on services/domain abstractions, while services depend on domain interfaces, not concrete MySQL implementations.

Main entry points: [`internal/infra/container/container.go`](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/container/container.go) (Container), [`internal/http/router/roteador.go`](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/router/roteador.go) (Router), [`internal/auth/service.go`](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/service.go) (Auth Core), [`cmd/api/main.go`](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/cmd/api/main.go) (API CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_cmd_api["API CLI<br/>entrypoint<br/>[main.go]"]
  node_config["Config<br/>settings<br/>[config.go]"]
end

subgraph group_http["HTTP/API"]
  node_router["Router<br/>http routes<br/>[roteador.go]"]
  node_middleware["Middleware<br/>http filters<br/>[recuperar.go]"]
  node_handlers["Handlers<br/>[chamado.go]"]
end

subgraph group_auth["Auth"]
  node_auth_handler["Auth API<br/>auth handler<br/>[handler.go]"]
  node_auth_service["Auth Core<br/>auth service<br/>[service.go]"]
  node_ldap["LDAP<br/>directory adapter<br/>[ldap.go]"]
  node_jwt["JWT<br/>token issuer<br/>[jwt.go]"]
end

subgraph group_service["Use Cases"]
  node_svc_chamado["Chamado<br/>use case<br/>[chamado.go]"]
  node_svc_usuario["Usuario<br/>use case<br/>[usuario.go]"]
end

subgraph group_domain["Domain"]
  node_domain_chamado{{"Chamado<br/>aggregate<br/>[chamado.go]"}}
  node_domain_usuario{{"Usuario<br/>entity<br/>[usuario.go]"}}
  node_domain_log{{"Log<br/>audit model<br/>[log.go]"}}
end

subgraph group_infra["Infrastructure"]
  node_infra_container["Container<br/>composition root<br/>[container.go]"]
  node_mysql_repo[("MySQL Repos<br/>persistence adapters<br/>[mysql.go]")]
  node_migrations["Migrations<br/>schema management<br/>[migrador.go]"]
  node_id_gen{{"ID Gen<br/>uuidv7<br/>[uuidv7.go]"}}
end

subgraph group_external["External Systems"]
  node_mysql[("MySQL<br/>database")]
  node_ldap_ad[("LDAP/AD<br/>identity provider")]
end

node_cmd_api -->|"loads"| node_config
node_cmd_api -->|"wires"| node_infra_container
node_cmd_api -->|"runs"| node_migrations
node_cmd_api -->|"starts"| node_router
node_infra_container -->|"injects"| node_router
node_infra_container -->|"injects"| node_auth_service
node_infra_container -->|"injects"| node_svc_chamado
node_infra_container -->|"injects"| node_svc_usuario
node_infra_container -->|"connects"| node_mysql_repo
node_infra_container -->|"provides"| node_id_gen
node_router -->|"uses"| node_middleware
node_router -->|"routes"| node_handlers
node_router -->|"routes"| node_auth_handler
node_handlers -->|"calls"| node_svc_chamado
node_handlers -->|"calls"| node_svc_usuario
node_auth_handler -->|"calls"| node_auth_service
node_auth_service -->|"validates"| node_ldap
node_auth_service -->|"issues"| node_jwt
node_auth_service -->|"loads"| node_domain_usuario
node_svc_chamado -->|"orchestrates"| node_domain_chamado
node_svc_chamado -->|"audits"| node_domain_log
node_svc_usuario -->|"orchestrates"| node_domain_usuario
node_mysql_repo -->|"persists"| node_mysql
node_migrations -->|"migrates"| node_mysql
node_ldap -->|"binds"| node_ldap_ad

click node_cmd_api "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/cmd/api/main.go"
click node_config "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/config/config.go"
click node_router "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/router/roteador.go"
click node_middleware "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/middleware/recuperar.go"
click node_handlers "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/handler/chamado.go"
click node_auth_handler "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/handler.go"
click node_auth_service "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/service.go"
click node_ldap "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/ldap.go"
click node_jwt "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/jwt.go"
click node_svc_chamado "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/service/chamado.go"
click node_svc_usuario "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/service/usuario.go"
click node_domain_chamado "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/chamado/chamado.go"
click node_domain_usuario "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/usuario/usuario.go"
click node_domain_log "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/log/log.go"
click node_infra_container "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/container/container.go"
click node_mysql_repo "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/mysql/mysql.go"
click node_migrations "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/migrations/migrador.go"
click node_id_gen "https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/id/uuidv7.go"

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_cmd_api,node_config,node_mysql,node_ldap_ad toneBlue
class node_router,node_middleware,node_handlers toneAmber
class node_auth_handler,node_auth_service,node_ldap,node_jwt toneMint
class node_svc_chamado,node_svc_usuario toneRose
class node_domain_chamado,node_domain_usuario,node_domain_log toneIndigo
class node_infra_container,node_mysql_repo,node_migrations,node_id_gen toneTeal
```

## Components

### Bootstrap

Executable entrypoint and wiring

- [API CLI](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/cmd/api/main.go): entrypoint · Main executable and operational modes · `cmd/api/main.go`
- [Config](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/config/config.go): settings · Central environment and startup validation · `internal/config/config.go`

### HTTP/API

Public request/response boundary

- [Router](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/router/roteador.go): http routes · Top-level route assembly and endpoint groups · `internal/http/router/roteador.go`
- [Middleware](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/middleware/recuperar.go): http filters · CORS and panic recovery · `internal/http/middleware/recuperar.go`
- [Handlers](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/http/handler/chamado.go): http handlers · Translates HTTP inputs into service calls · `internal/http/handler/chamado.go`

### Auth

Login, JWT, LDAP, and authorization

- [Auth API](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/handler.go): auth handler · Login and token endpoints · `internal/auth/handler.go`
- [Auth Core](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/service.go): auth service · Credential validation and authorization logic · `internal/auth/service.go`
- [LDAP](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/ldap.go): directory adapter · Validates credentials against LDAP/AD · `internal/auth/ldap.go`
- [JWT](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/auth/jwt.go): token issuer · Creates and validates access tokens · `internal/auth/jwt.go`

### Use Cases

Application orchestration

- [Chamado](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/service/chamado.go): use case · Ticket lifecycle orchestration · `internal/service/chamado.go`
- [Usuario](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/service/usuario.go): use case · User management and lookup workflows · `internal/service/usuario.go`

### Domain

Core business model and rules

- [Chamado](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/chamado/chamado.go): aggregate · Ticket state and transition rules · `internal/domain/chamado/chamado.go`
- [Usuario](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/usuario/usuario.go): entity · User identity, email, and permissions · `internal/domain/usuario/usuario.go`
- [Log](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/domain/log/log.go): audit model · Auditing events and actions · `internal/domain/log/log.go`

### Infrastructure

Persistence, migrations, IDs, and assembly

- [Container](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/container/container.go): composition root · Wires handlers, services, repos, and config · `internal/infra/container/container.go`
- [MySQL Repos](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/mysql/mysql.go): persistence adapters · Concrete repository implementations · `internal/infra/mysql/mysql.go`
- [Migrations](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/migrations/migrador.go): schema management · Schema versioning and seed data · `internal/infra/migrations/migrador.go`
- [ID Gen](https://github.com/rogeriobgregorio/ticket-management-system/blob/main/internal/infra/id/uuidv7.go): uuidv7 · Application identifier generation · `internal/infra/id/uuidv7.go`

### External Systems

Datastores and identity providers

- **MySQL**: database · Primary persistent store
- **LDAP/AD**: identity provider · External directory for authentication

## Connections

- API CLI → Config: loads · Reads and validates runtime settings
- API CLI → Container: wires · Builds the application object graph
- API CLI → Migrations: runs · Executes migrate/seed modes
- API CLI → Router: starts · Boots the HTTP server mode
- Container → Router: injects · Provides handlers and middleware to the HTTP layer
- Container → Auth Core: injects · Composes auth dependencies
- Container → Chamado: injects · Composes ticket use cases
- Container → Usuario: injects · Composes user use cases
- Container → MySQL Repos: connects · Registers concrete persistence adapters
- Container → ID Gen: provides · Supplies identifier generation
- Router → Middleware: uses · Applies shared HTTP middleware
- Router → Handlers: routes · Dispatches API requests to handlers
- Router → Auth API: routes · Exposes auth endpoints
- Handlers → Chamado: calls · Invokes ticket workflows
- Handlers → Usuario: calls · Invokes user workflows
- Auth API → Auth Core: calls · Delegates login and authorization work
- Auth Core → LDAP: validates · Checks credentials against directory
- Auth Core → JWT: issues · Creates and parses tokens
- Auth Core → Usuario: loads · Resolves local user identity and permissions
- Chamado → Chamado: orchestrates · Applies ticket rules and state transitions
- Chamado → Log: audits · Records business events
- Usuario → Usuario: orchestrates · Applies user business rules
- MySQL Repos → MySQL: persists · Reads and writes application data
- Migrations → MySQL: migrates · Creates and seeds the schema
- LDAP → LDAP/AD: binds · Authenticates against directory service
