# abufarhad/go-starter architecture

> Architecture diagram of the GitHub repository abufarhad/go-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abufarhad/go-starter
- Repository: https://github.com/abufarhad/go-starter

## Overview

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: [`internal/conn/db.go`](https://github.com/abufarhad/go-starter/blob/main/internal/conn/db.go) (Config & DB), [`docs/swagger.yaml`](https://github.com/abufarhad/go-starter/blob/main/docs/swagger.yaml) (API docs), [`user/service/user.go`](https://github.com/abufarhad/go-starter/blob/main/user/service/user.go) (User svc), [`auth/controller/auth.go`](https://github.com/abufarhad/go-starter/blob/main/auth/controller/auth.go) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_main(("main<br/>bootstrap<br/>[main.go]"))
  node_cmd_root["CLI root<br/>[root.go]"]
  node_cmd_serve["Serve cmd<br/>cli command<br/>[serve.go]"]
  node_cmd_migration["Migrate cmd<br/>cli command<br/>[migration.go]"]
end

subgraph group_features["Feature modules"]
  node_auth_controller["Auth API<br/>http controller<br/>[auth.go]"]
  node_auth_service["Auth svc<br/>[auth.go]"]
  node_jwt_mw{{"JWT mw<br/>middleware<br/>[jwt.go]"}}
  node_user_controller["User API<br/>http controller<br/>[user.go]"]
  node_user_service["User svc<br/>[user.go]"]
  node_user_repo[("User repo<br/>[user.go]")]
  node_clubs_controller["Clubs API<br/>http controller<br/>[clubs.go]"]
  node_clubs_service["Clubs svc<br/>[clubs.go]"]
  node_clubs_repo[("Clubs repo<br/>[clubs.go]")]
end

subgraph group_shared["Shared model"]
  node_domain_entities["Entities<br/>domain model<br/>[user.go]"]
  node_domain_dto["DTOs<br/>api contracts<br/>[user.go]"]
end

subgraph group_infra["Infrastructure"]
  node_config_conn[("Config & DB<br/>infra<br/>[db.go]")]
  node_errors_logger["Errors & logs<br/>infra<br/>[rest_error.go]"]
end

subgraph group_ops["Operations"]
  node_system_controller["System API<br/>http controller<br/>[http.go]"]
  node_system_service["System svc<br/>[system.go]"]
  node_system_repo[("System repo<br/>[system.go]")]
  node_docs["API docs<br/>documentation<br/>[swagger.yaml]"]
end

node_main -->|"boots"| node_cmd_root
node_cmd_root -->|"exposes"| node_cmd_serve
node_cmd_root -->|"exposes"| node_cmd_migration
node_cmd_serve -->|"uses"| node_config_conn
node_cmd_migration -->|"uses"| node_config_conn
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"uses"| node_domain_entities
node_auth_controller -->|"maps"| node_domain_dto
node_jwt_mw -->|"protects"| node_auth_controller
node_user_controller -->|"calls"| node_user_service
node_user_service -->|"uses"| node_user_repo
node_user_repo -->|"connects"| node_config_conn
node_user_service -->|"uses"| node_domain_entities
node_user_controller -->|"maps"| node_domain_dto
node_clubs_controller -->|"calls"| node_clubs_service
node_clubs_service -->|"uses"| node_clubs_repo
node_clubs_repo -->|"connects"| node_config_conn
node_system_controller -->|"calls"| node_system_service
node_system_service -->|"uses"| node_system_repo
node_system_repo -->|"connects"| node_config_conn
node_system_controller -->|"maps"| node_domain_dto
node_auth_service -->|"reports"| node_errors_logger
node_user_service -->|"reports"| node_errors_logger
node_clubs_service -->|"reports"| node_errors_logger
node_system_service -->|"reports"| node_errors_logger
node_docs -.->|"documents"| node_auth_controller
node_docs -.->|"documents"| node_user_controller
node_docs -.->|"documents"| node_clubs_controller
node_docs -.->|"documents"| node_system_controller

click node_main "https://github.com/abufarhad/go-starter/blob/main/main.go"
click node_cmd_root "https://github.com/abufarhad/go-starter/blob/main/cmd/root.go"
click node_cmd_serve "https://github.com/abufarhad/go-starter/blob/main/cmd/serve.go"
click node_cmd_migration "https://github.com/abufarhad/go-starter/blob/main/cmd/migration.go"
click node_auth_controller "https://github.com/abufarhad/go-starter/blob/main/auth/controller/auth.go"
click node_auth_service "https://github.com/abufarhad/go-starter/blob/main/auth/service/auth.go"
click node_jwt_mw "https://github.com/abufarhad/go-starter/blob/main/auth/middlewares/jwt.go"
click node_user_controller "https://github.com/abufarhad/go-starter/blob/main/user/controller/user.go"
click node_user_service "https://github.com/abufarhad/go-starter/blob/main/user/service/user.go"
click node_user_repo "https://github.com/abufarhad/go-starter/blob/main/user/repository/user.go"
click node_clubs_controller "https://github.com/abufarhad/go-starter/blob/main/clubs/controller/clubs.go"
click node_clubs_service "https://github.com/abufarhad/go-starter/blob/main/clubs/service/clubs.go"
click node_clubs_repo "https://github.com/abufarhad/go-starter/blob/main/clubs/repository/clubs.go"
click node_system_controller "https://github.com/abufarhad/go-starter/blob/main/system_check/controller/http.go"
click node_system_service "https://github.com/abufarhad/go-starter/blob/main/system_check/service/system.go"
click node_system_repo "https://github.com/abufarhad/go-starter/blob/main/system_check/repository/system.go"
click node_domain_entities "https://github.com/abufarhad/go-starter/blob/main/domain/user.go"
click node_domain_dto "https://github.com/abufarhad/go-starter/blob/main/domain/dto/user.go"
click node_config_conn "https://github.com/abufarhad/go-starter/blob/main/internal/conn/db.go"
click node_errors_logger "https://github.com/abufarhad/go-starter/blob/main/internal/errors/rest_error.go"
click node_docs "https://github.com/abufarhad/go-starter/blob/main/docs/swagger.yaml"

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_main,node_cmd_root,node_cmd_serve,node_cmd_migration toneBlue
class node_auth_controller,node_auth_service,node_jwt_mw,node_user_controller,node_user_service,node_user_repo,node_clubs_controller,node_clubs_service,node_clubs_repo toneAmber
class node_domain_entities,node_domain_dto toneMint
class node_config_conn,node_errors_logger toneRose
class node_system_controller,node_system_service,node_system_repo,node_docs toneIndigo
```

## Components

### Entrypoints

CLI and process startup

- [main](https://github.com/abufarhad/go-starter/blob/main/main.go): bootstrap · Process entrypoint · `main.go`
- [CLI root](https://github.com/abufarhad/go-starter/blob/main/cmd/root.go): cli · Command wiring · `cmd/root.go`
- [Serve cmd](https://github.com/abufarhad/go-starter/blob/main/cmd/serve.go): cli command · Starts HTTP server · `cmd/serve.go`
- [Migrate cmd](https://github.com/abufarhad/go-starter/blob/main/cmd/migration.go): cli command · Database migration command · `cmd/migration.go`

### Feature modules

HTTP-facing business modules

- [Auth API](https://github.com/abufarhad/go-starter/blob/main/auth/controller/auth.go): http controller · Authentication endpoints · `auth/controller/auth.go`
- [Auth svc](https://github.com/abufarhad/go-starter/blob/main/auth/service/auth.go): service · Authentication rules · `auth/service/auth.go`
- [JWT mw](https://github.com/abufarhad/go-starter/blob/main/auth/middlewares/jwt.go): middleware · Token validation · `auth/middlewares/jwt.go`
- [User API](https://github.com/abufarhad/go-starter/blob/main/user/controller/user.go): http controller · User endpoints · `user/controller/user.go`
- [User svc](https://github.com/abufarhad/go-starter/blob/main/user/service/user.go): service · User use cases · `user/service/user.go`
- [User repo](https://github.com/abufarhad/go-starter/blob/main/user/repository/user.go): repository · User persistence · `user/repository/user.go`
- [Clubs API](https://github.com/abufarhad/go-starter/blob/main/clubs/controller/clubs.go): http controller · Club endpoints · `clubs/controller/clubs.go`
- [Clubs svc](https://github.com/abufarhad/go-starter/blob/main/clubs/service/clubs.go): service · Club use cases · `clubs/service/clubs.go`
- [Clubs repo](https://github.com/abufarhad/go-starter/blob/main/clubs/repository/clubs.go): repository · Club persistence · `clubs/repository/clubs.go`

### Shared model

Domain entities and DTOs

- [Entities](https://github.com/abufarhad/go-starter/blob/main/domain/user.go): domain model · Core entities · `domain/user.go`
- [DTOs](https://github.com/abufarhad/go-starter/blob/main/domain/dto/user.go): api contracts · Request and response payloads · `domain/dto/user.go`

### Infrastructure

Cross-cutting runtime services

- [Config & DB](https://github.com/abufarhad/go-starter/blob/main/internal/conn/db.go): infra · Environment and database connection · `internal/conn/db.go`
- [Errors & logs](https://github.com/abufarhad/go-starter/blob/main/internal/errors/rest_error.go): infra · REST errors and logging · `internal/errors/rest_error.go`

### Operations

Health, docs, and migrations

- [System API](https://github.com/abufarhad/go-starter/blob/main/system_check/controller/http.go): http controller · Health checks · `system_check/controller/http.go`
- [System svc](https://github.com/abufarhad/go-starter/blob/main/system_check/service/system.go): service · Operational checks · `system_check/service/system.go`
- [System repo](https://github.com/abufarhad/go-starter/blob/main/system_check/repository/system.go): repository · Dependency checks · `system_check/repository/system.go`
- [API docs](https://github.com/abufarhad/go-starter/blob/main/docs/swagger.yaml): documentation · Swagger/OpenAPI assets · `docs/swagger.yaml`

## Connections

- 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
