How hpaes/go-api-project works
Project Type and Purpose
• This is a backend API service written in Go.
• It follows a Clean/Hexagonal architecture with clearly separated layers:
• API (controllers/handlers)
• Application (use cases)
• Domain (entities, value objects, domain errors)
• Infrastructure (database adapters, repositories, logging)
File Structure
• src/api
• controller – HTTP controllers (account_controller.go) and tests
• handler – generic HTTP handler for routing and error mapping
• response – structs for shaping JSON success responses
• src/core
• application/usecase – “interactors” (signup, get_account) and tests
• domain – core entities (Account) and value objects (Name, CPF, Email, CarPlate), plus domain‐specific errors
• errors – custom error types representing domain & HTTP error conditions
• src/infrastructure
• database – adapter interface and Postgres implementation (pq_adapter.go)
• repository – account repository implementation of domain interface
• logger – logging handler
• main.go – composition root: wire dependencies, start HTTP server
README
• Confirms: “Development of an API using golang”
Main Components & Their Interactions
a. Components
1. HTTP Client / External Consumer (Postman, Frontend)
2. API Layer
• Controllers (AccountController)
• Handlers (HTTP routing, error‐to‐response mapping)
• Response objects (SuccessResponse)
3. Application Layer
• Use cases (SignupUseCase, GetAccountUseCase)
4. Domain Layer
• Entities (Account)
• Value Objects (CPF, Email, Name, CarPlate)
• Domain Errors (AccountAlreadyExists, AccountNotFound, etc.)
5. Infrastructure Layer
• Repository interface (defined in domain or core)
• Repository implementation (AccountRepositoryImpl)
• Database adapter (DatabaseAdapter interface, PqAdapter)
• Logger (LoggerHandler)
6. External Systems
• PostgreSQL database
b. Relationships & Data Flow
1. HTTP Client → Controller
• HTTP POST /signup or GET /account
2. Controller → Handler
• Handler parses request, validates HTTP method & query/body, transforms to domain payload or returns HTTP error
3. Handler → Use Case
• Calls appropriate use case method with domain/value‐object parameters
4. Use Case → Repository Interface
• E.g., SignupUseCase calls AccountRepository.Save()
5. Repository Impl → Database Adapter
• AccountRepositoryImpl uses PqAdapter to execute SQL against PostgreSQL
6. Database ↔ PqAdapter
• Executes queries, returns results or DB‐level errors
7. Use Case → Domain Errors
• Throws domain errors on duplicates/not found, propagates up
8. Handler → Response
• Maps success or error into HTTP response (SuccessResponse or error JSON)
9. Controller → HTTP Client
• Returns JSON response
c. Architectural Patterns & Principles
• Clean (Hexagonal) Architecture separating core business logic from delivery and infrastructure.
• Dependency Inversion: use cases depend on repository interfaces, not implementations.
• Single Responsibility: each layer has a clear responsibility.
d. Key Technologies & Frameworks
• Go standard library (net/http) for HTTP server
• pq or pgx for PostgreSQL adapter
• Custom logger (could be wrapped around logrus or zap)