A production-ready Golang backend template built with Domain-Driven Design (DDD), Vertical Slice Architecture, CQRS, Clean Architecture, and Modular Monolith principles.

# Start all services (PostgreSQL, Redis, NATS, Jaeger, Prometheus, Grafana)
make docker-up

# Run database migrations
make migrate-up

# Generate SQLC code
make sqlc

# Seed default roles and permissions
make seed

# Start the API server
make run

The server starts at http://localhost:8080.

• Swagger UI: http://localhost:8080/swagger/index.html
• Health check: http://localhost:8080/health

# Install missing tools (golangci-lint, goimports, goose, sqlc, swag)
make install-tools

# Run all checks before committing
make precommit

# Install git pre-commit hook (runs make precommit automatically)
make install-hooks

# Lint
make lint

# Format code
make fmt

• DDD - Entities, Value Objects, Domain Services, Specifications, Domain Events
• CQRS - Separate Command and Query handlers
• Clean Architecture - Strict dependency direction
• Modular Monolith - Each module is independent
• Vertical Slice - Each feature is self-contained
• Loosely Coupled - Infrastructure implementations behind interfaces, swappable via DI
• Event-Driven - Domain events decouple side effects (e.g., email sending) from core business logic
• Unified API - Consistent response envelope and centralized error handling across all endpoints
• OpenTelemetry - Distributed tracing with trace/span IDs attached to every log entry

cmd/api/              - Entry point, router, swagger metadata
internal/
  core/domain/        - Shared interfaces (Entity, Cache, Messenger, TokenService, Logger)
  shared/             - Shared kernel (config, database, middleware, telemetry, utils)
  infrastructure/     - Loosely coupled implementations (Redis, NATS, JWT, Zap, Email)
  shared/             - Shared kernel (config, database, events, middleware, telemetry, utils)
  todo/               - Todo module (domain, application, infrastructure, interfaces)
  authentication/     - Auth module (register, login, refresh, logout, email verification)
  authorization/      - RBAC module (Casbin enforcer, roles, permissions)
  user/               - User module (admin user CRUD)
migrations/           - Database migrations
docs/                 - Documentation + generated Swagger output
pkg/                  - Public packages (password, slug)
scripts/              - Utility scripts (migrate, seed)
configs/              - Configuration files

All API responses share a unified envelope:

// Success (single resource)
{
  "success": true,
  "data": { ... },
  "meta": null
}

// Success (paginated list)
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

// Error
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "..."
  }
}

All logs include trace_id and span_id extracted from the OpenTelemetry context. See docs/API.md for the full list of error codes.

The application exposes Prometheus metrics at /metrics and traces via OpenTelemetry OTLP to Jaeger. Full observability stack runs in Docker Compose:

1. Go App RED — request rate, error rate, p50/p95/p99 latency, active requests, goroutines, memory
2. PostgreSQL — connections, tps, cache hit ratio, deadlocks
3. Redis — hit rate, memory, connected clients, commands/s
4. System Overview — all-services health, combined metrics, latency heatmap

• HighErrorRate — 5xx > 5% over 5 minutes
• HighLatency — p99 latency > 1s over 5 minutes
• ServiceDown — target unreachable for 1 minute
• HighMemoryUsage — Go RSS > 500MB
• DatabaseConnectionPoolExhaustion — active connections > 40

Configure Discord webhook and email recipients via environment variables:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
[email protected]

Email sending is decoupled from the authentication service through domain events. The service publishes UserRegistered, EmailVerified, and PasswordResetRequested events; an EmailHandler subscribes and calls the configured mailer (SMTP, SendGrid, or console). The EventBus is interface-based so an async adapter (RabbitMQ, Kafka, etc.) can be swapped in without changing services or handlers.

• GitHub Actions CI — lint, test (with PostgreSQL/Redis), build, and Docker image build on every push/PR
• GitHub Actions CD — build and push Docker image to GHCR, deploy to staging on main, deploy to production on version tags
• Kubernetes — Kustomize manifests in k8s/base/ with staging/production overlays

See Deployment for details.

• Architecture
• API
• Folder Structure
• Development
• Deployment
• Contributing

MIT