How rogeriobgregorio/ticket-management-system works
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: container.go Container · roteador.go Router · service.go Auth Core · main.go API CLI
Components 20
Bootstrap
Executable entrypoint and wiring
HTTP/API
Public request/response boundary
- Router · Top-level route assembly and endpoint groups
internal/http/router/roteador.go - Middleware · CORS and panic recovery
internal/http/middleware/recuperar.go - Handlers · Translates HTTP inputs into service calls
internal/http/handler/chamado.go
Auth
Login, JWT, LDAP, and authorization
Use Cases
Application orchestration
Domain
Core business model and rules
Infrastructure
Persistence, migrations, IDs, and assembly
- Container · Wires handlers, services, repos, and config
internal/infra/container/container.go - MySQL Repos · Concrete repository implementations
internal/infra/mysql/mysql.go - Migrations · Schema versioning and seed data
internal/infra/migrations/migrador.go - ID Gen · Application identifier generation
internal/infra/id/uuidv7.go
External Systems
Datastores and identity providers
- MySQL · Primary persistent store
- LDAP/AD · External directory for authentication
Connections 25
- 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