How abufarhad/go-starter works
1. Overall shape
This is a Go backend API scaffold organized around clean architecture. The code is split into feature modules (user, clubs, auth, system_check) plus shared infrastructure under internal/ and shared business types under domain/.
2. Request entrypoints
The runtime starts in main.go, with CLI wiring in cmd/. Two explicit commands exist:
- serve to start the HTTP server
- migrate to initialize/update the database
This makes startup and schema management separate concerns.
3. HTTP delivery layer
Each feature has a controller/ package that owns HTTP handlers:
- user/controller
- clubs/controller
- auth/controller
- system_check/controller
These controllers are the outermost API boundary and likely map routes, decode requests, and return responses.
4. Application/business layer
Each feature also has a service/ package:
- user/service
- clubs/service
- auth/service
- system_check/service
These services hold the business rules and orchestrate work between controllers and repositories. This is the main place where use cases live.
5. Persistence layer
Modules that persist data also have repository/ packages:
- user/repository
- clubs/repository
- system_check/repository
Repositories isolate database access from business logic, which is the key boundary for the architecture diagram.
6. Shared domain model
The domain/ directory contains the cross-module model:
- core entities such as user, club, post, system, users_club
- DTOs in domain/dto/ for request/response payloads
This separation suggests controllers should use DTOs at the API boundary while services/repositories operate on domain entities.
7. Authentication and authorization
auth/ contains both the auth service/controller and JWT middleware in auth/middlewares/.
The middleware layer is important because it sits between the HTTP router and protected controllers, validating tokens before requests reach business logic.
8. Cross-cutting infrastructure
Shared runtime concerns live in internal/:
- internal/config for environment/config loading
- internal/conn for database connection management
- internal/logger for logging
- internal/errors for standardized REST error handling
- internal/service likely for dependency wiring / service composition
- internal/utils for helpers like hashing, constants, HTTP method helpers, and message utilities
These are infrastructure services consumed by feature modules.
9. Database lifecycle
Database setup is first-class:
- scripts/initialdb.sql suggests bootstrap schema/data
- cmd/migration.go provides a migration command
- Dockerfile.db and docker-compose.yml indicate the database can be started locally via containers
The architecture therefore assumes a persistent relational backing store, even though the exact vendor is not explicit here.
10. Observability and API docs
internal/logger handles logs, and docs/ contains Swagger/OpenAPI assets (swagger.yaml, swagger.json, generated docs code).
This means the API surface is documented and likely served under a docs route for interactive exploration.
11. Validation / health checking
system_check/ is a dedicated subsystem for operational checks, probably exposing a health endpoint and checking core dependencies such as database connectivity. In architecture diagrams, this is a lightweight operational slice separate from business modules.
12. Testing and quality
Tests exist alongside controllers, e.g. auth/controller/auth_test.go and user/controller/user_test.go, indicating the API layer is tested directly. GitHub Actions CI (.github/workflows/ci.yml) suggests automated validation in the repository lifecycle.
13. Deployment/runtime
The repo supports both local and containerized execution:
- Dockerfile, Dockerfile.db
- docker-compose.yml
- Makefile, run.sh
This makes the system portable across local development and container deployment.
14. How data flows through the system
The typical path is:
HTTP request → middleware (JWT/auth if needed) → controller → service → repository → database → service → controller → HTTP response
Shared DTOs shape the request/response boundary, while domain entities carry the core data model internally.
Main entry points: db.go Config & DB · swagger.yaml API docs · user.go User svc · auth.go Auth API
Components 21
Entrypoints
CLI and process startup
- main · Process entrypoint
main.go - CLI root · Command wiring
cmd/root.go - Serve cmd · Starts HTTP server
cmd/serve.go - Migrate cmd · Database migration command
cmd/migration.go
Feature modules
HTTP-facing business modules
- Auth API · Authentication endpoints
auth/controller/auth.go - Auth svc · Authentication rules
auth/service/auth.go - JWT mw · Token validation
auth/middlewares/jwt.go - User API · User endpoints
user/controller/user.go - User svc · User use cases
user/service/user.go - User repo · User persistence
user/repository/user.go - Clubs API · Club endpoints
clubs/controller/clubs.go - Clubs svc · Club use cases
clubs/service/clubs.go - Clubs repo · Club persistence
clubs/repository/clubs.go
Shared model
Domain entities and DTOs
Infrastructure
Cross-cutting runtime services
- Config & DB · Environment and database connection
internal/conn/db.go - Errors & logs · REST errors and logging
internal/errors/rest_error.go
Operations
Health, docs, and migrations
- System API · Health checks
system_check/controller/http.go - System svc · Operational checks
system_check/service/system.go - System repo · Dependency checks
system_check/repository/system.go - API docs · Swagger/OpenAPI assets
docs/swagger.yaml
Connections 29
- main → CLI root: boots · Process startup initializes CLI wiring
- CLI root → Serve cmd: exposes · Serve command starts the API runtime
- CLI root → Migrate cmd: exposes · Migration command manages schema lifecycle
- Serve cmd → Config & DB: uses · Server startup reads config and opens DB
- Migrate cmd → Config & DB: uses · Migrations connect to the database
- Auth API → Auth svc: calls · Authentication requests delegate to business logic
- Auth svc → Entities: uses · Auth logic works with core user/domain data
- Auth API → DTOs: maps · HTTP payloads are shaped by DTOs
- JWT mw → Auth API: protects · JWT middleware gates protected routes
- User API → User svc: calls · User endpoints delegate to service layer
- User svc → User repo: uses · User use cases persist through repository
- User repo → Config & DB: connects · Repository uses shared DB connection
- User svc → Entities: uses · User business logic manipulates domain entities
- User API → DTOs: maps · User API requests and responses use DTOs
- Clubs API → Clubs svc: calls · Club endpoints delegate to service layer
- Clubs svc → Clubs repo: uses · Club use cases persist through repository
- Clubs repo → Config & DB: connects · Repository uses shared DB connection
- System API → System svc: calls · Health endpoint delegates to operational checks
- System svc → System repo: uses · Health checks read dependency state
- System repo → Config & DB: connects · System checks query the shared database connection
- System API → DTOs: maps · Health responses use DTOs
- Auth svc → Errors & logs: reports · Services use standardized errors and logging
- User svc → Errors & logs: reports · Shared error handling and logging
- Clubs svc → Errors & logs: reports · Shared error handling and logging
- System svc → Errors & logs: reports · Shared error handling and logging
- API docs → Auth API: documents · Swagger describes API surface
- API docs → User API: documents · Swagger describes API surface
- API docs → Clubs API: documents · Swagger describes API surface
- API docs → System API: documents · Swagger describes API surface