v0.0.3: Development (#3)

Release Notes

New Features

• User Create endpoint — POST /users with authorization check (user:create), supporting full CRUD lifecycle

Testing

• Handler unit tests — comprehensive test suites for all 5 modules:
  • Auth (38 tests): register, login, refresh, logout, verify/reset email, with 500/bus-error coverage
  • Authz (all endpoints): create/get/list/update/delete role + permission, assign/remove role + permission, check, with bus-error subtests
  • User (23 tests): create, get, list, me, update, delete — success + validation + not-found + bus-error
  • Todo (28 tests): create, get, update, delete, complete, search — bad JSON + repo error + not-found
  • Tenant (22 tests): create, get, list, update, delete — validation + bus-error + not-found
• Handler-level integration tests — 9–12 end-to-end tests per module wiring real DB repos through in-memory CQRS buses to HTTP handlers
• Repository integration tests — real-PostgreSQL CRUD tests for auth, authz, user, todo, tenant repositories
• Domain entity tests — unit tests for core domain entities, aggregates, value objects, and specifications across all modules
• Shared test DB helper (internal/testhelper/testdb.go) — goose-based migration runner, configurable via env vars (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_SSLMODE)

Bug Fixes

• User repo — error wrapping fixed: GetByID/Update/Delete now return domain.ErrNotFound, Create returns domain.ErrAlreadyExists on PG unique violation (code 23505)
• Auth & User repo — password column added to INSERT statements to fix NOT NULL constraint violations
• Authz handler integration test — AssignPermission request body now includes both role_id and permission_id
• Test data isolation — all integration test emails, slugs, names, token hashes, and todo titles use UUID suffixes to prevent cross-test collisions
• Lint fixes — checked goose.SetDialect return error, removed unused withUserID/middleware import, replaced string(w.Body.Bytes()) with w.Body.String()

CI / DX

• .devcontainer/ — VS Code dev container with Go 1.26, golangci-lint, sqlc, swag, psql client, Docker-from-Docker, and pre-configured test DB env vars
• docker-compose.test.yml — standalone PostgreSQL 16 service for running integration tests locally
• make test-unit / make test-integration — targets to run only unit or integration test packages
• CI — DB name aligned to codebase_testing (matching test helper default)

Dependency Changes

• go.mod / go.sum tidied (no new external dependencies)

v0.0.2

Release Notes

Commits since master (2c51273): 108

NATS Event Bus (New)

Switchable EventBus between in-memory and NATS JetStream via events.driver config:

• events.driver: memory (default) — existing synchronous in-memory bus, unchanged
• events.driver: nats — JetStream-backed with at-least-once delivery, queue groups, infinite retry on handler error

Components:

• Config structs: EventsConfig, StreamConfig, ConsumerConfig in internal/shared/config/config.go
• Type registry: Register/CreatePayload for JSON deserialization (internal/shared/events/registry.go)
• NATSEventBus with jetStreamer abstraction, adapters for nats.JetStreamContext/*nats.Msg
• JetStream stream "events" (file storage, interest retention) created at startup via ensureStream()
• Push consumer "event-bus" with queue group, MaxDeliver(-1), AckWait(30s), manual ACK
• Auth event structs gained JSON tags for serialization
• Events registered via fx.Invoke in todo/module.go and authentication/module.go
• New NewLoggingEventBus accepts EventBus interface (wraps both implementations)
• Docker Compose enables -js flag on NATS server

NATS Observability (New)

• Prometheus counters per NATS subject (nats_published_total, nats_received_total, etc.)
• NATS debug endpoint with in-memory ring buffer (toggled via nats.debug_endpoint)
• NATS Grafana dashboard (dashboards/nats.json) with publish/receive rates, bytes, and debug snapshots
• Infinity datasource for NATS debug endpoint in Grafana

Observability Stack (New)

• Prometheus, Grafana, Alertmanager in Docker Compose
• Grafana auto-provisioning: datasources and dashboards
• OpenTelemetry HTTP tracing middleware with span error recording
• Trace IDs propagated to logs

CQRS Standardization (Refactor)

• CommandBus/QueryBus interfaces and in-memory implementations in internal/shared/cqrs
• Auth, user, authorization, and tenant modules migrated to bus dispatch
• Auth handler tests rewritten for bus dispatch pattern
• Dead code (old application service directories) removed

Response Formatter & Middleware (Refactor)

• Unified response envelope (utils.APIResponse)
• MapError for standardized error codes
• RespondPaginated for cursor-based paginated responses
• Pure-function handler adapters in httpadapter package
• Response formatter middleware

SQLC Migration (Refactor)

• Multi-domain sqlc configuration with 5 generation targets
• All repositories migrated from database/sql to sqlc:
  • Todo, user, authentication (user + refresh_token), authorization (role, permission, role_permission, user_role), auditlog
• Pagination queries removed from sqlc (kept only CRUD)
• JSONB override for []byte in sqlc
• Cursor-based pagination with shared cursor package (CursorMeta, Before, After)

Multi-Tenancy (New)

• Row-level isolation with tenant context
• User normalization per tenant
• Config, context keys, and tenant resolver middleware
• TenantConfig with X-Tenant-ID header and JWT claim support

Email Service (New)

• Domain interface (domain.Mailer) with multiple providers
• Console, SMTP, and SendGrid providers with tests
• HTML template rendering with templates for verification, reset, welcome, invite
• Email verification and password reset flows in auth module
• Domain events (UserRegistered, EmailVerified, PasswordResetRequested) decouple auth from email
• LoggingEventBus decorator for event publish error logging

Error Hardening (Fix)

• Stack trace hidden on non-production 500 errors
• Error checking improvements
• Security fixes: SMTP STARTTLS, token hashing, template caching
• Remove pqtype dependency
• Sentry-style error handling patterns

CI/CD & Deployment

• Production Dockerfile and docker-compose.prod
• GitHub Actions workflow
• Kubernetes manifests
• Go 1.25 updated
• golangci-lint configuration fixes
• Script install hooks and pre-commit hooks

Other

• Cursor pagination in all repository implementations
• Shared pagination utilities (PaginatedPayload, PaginatedResult)
• Swagger/OpenAPI doc annotations updated
• Updated Fx wiring for shared EventBus and email handler
• Architecture, folder structure, and API documentation updates

v0.0.1

Release Notes - v1.0.0

Initial Release

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

Overview

• Module: github.com/IDTS-LAB/go-codebase
• Go Version: 1.25.0
• License: MIT

Features

Core Architecture

• DDD with Entities, Value Objects, Domain Events
• CQRS with CommandBus/QueryBus (in-memory, swappable to async)
• Clean Architecture with strict dependency direction
• Vertical Slice Architecture — each feature is self-contained
• Modular Monolith — independent modules wired via Uber Fx DI

Authentication

• User registration with email verification
• JWT-based authentication (access + refresh tokens)
• Login/logout with token refresh
• Forgot password / reset password flows
• Email verification resend
• Session management

Authorization (RBAC)

• Casbin-based role-based access control
• Role CRUD with permission assignments
• Permission CRUD with resource/action model
• User-role assignment and removal
• Permission checking on protected endpoints
• Policy synchronization from database to Casbin enforcer

Multi-Tenancy

• Row-level tenant isolation
• Configurable tenant header and JWT claim
• Automatic tenant filtering in all repository queries
• Tenant CRUD module

API

• Unified JSON response envelope ({ success, data, meta, error })
• Consistent error handling with HTTP status code mapping
• Cursor-based pagination across all list endpoints
• Swagger UI documentation
• Health and readiness checks

Infrastructure

• PostgreSQL — primary database with sqlc-generated type-safe queries
• Redis — caching, idempotency, rate limiting
• NATS — async messaging
• OpenTelemetry — distributed tracing (OTLP HTTP, W3C propagation)
• Zap Logger — structured logging with trace/span IDs
• Goose — database migrations

Cross-Cutting Concerns

• Idempotency middleware (POST endpoints)
• Rate limiting middleware
• CORS configuration
• Request ID propagation
• Audit logging
• Response formatting middleware (automatic envelope wrapping)
• Error handling with stack traces in development mode

Event-Driven Email

• Domain events for UserRegistered, EmailVerified, PasswordResetRequested
• Pluggable mailer providers: SMTP, SendGrid, Console
• HTML template rendering for emails
• In-memory EventBus (interface ready for RabbitMQ/Kafka)

Developer Experience

• make precommit — runs format check, lint, build, and tests
• make install-hooks — installs git pre-commit hook
• make install-tools — auto-installs golangci-lint, goimports, goose, sqlc, swag
• golangci-lint configured with errcheck, govet, staticcheck, gocritic, revive
• Docker Compose for local development (PostgreSQL, Redis, NATS, Jaeger, Prometheus, Grafana)
• Production Dockerfile with multi-stage build and non-root user

CI/CD

• GitHub Actions CI: lint, test, build, Docker image
• GitHub Actions CD: build/push to GHCR, deploy staging/production
• Kubernetes manifests with Kustomize overlays

Changelog (104 commits)

Features

• Initial project scaffold with DDD + Clean Architecture
• Authentication module with JWT tokens and email verification
• RBAC authorization with Casbin enforcer
• User CRUD module
• Todo module
• Multi-tenancy with row-level isolation
• CQRS with CommandBus/QueryBus
• sqlc repository migration across all modules
• Cursor-based pagination
• Error hardening and standardized error handling
• Email service with SMTP, SendGrid, Console providers
• Domain events and event-driven email
• Response formatter middleware and unified API envelope
• Telemetry with OpenTelemetry tracing
• Idempotency and rate limiting middleware

Infrastructure

• Go 1.25.0 upgrade
• golangci-lint CI with all checks passing
• Production Dockerfile and docker-compose
• GitHub Actions CI/CD pipelines
• Kubernetes manifests with staging/production overlays
• Module rename script

Quality

• Pre-commit hook with format, lint, build, and test checks
• Auto-install for development tools
• All linter issues resolved (errcheck, revive, gocritic, staticcheck, govet, gofmt)

Quick Start

# Start services
make docker-up

# Install tools (auto-detects missing binaries)
make install-tools

# Run migrations
make migrate-up

# Generate sqlc code
make sqlc

# Start server
make run

Requirements

• Go 1.25+
• Docker & Docker Compose