This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Sign in to like and favorite skills
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is a go-bricks demo project demonstrating production-ready patterns for building modular Go applications. It uses the
go-bricks../go-bricksgo.modKey characteristics:
Requirements:
This repository is the public showcase for GoBricks. It exists so external engineers can clone the project, run it locally, and experience core framework capabilities—configuration, observability, secrets, jobs, messaging—without reverse engineering. Every contribution should sharpen that first-hour experience.
GoBricks is a production-grade framework for building MVPs fast. It provides enterprise-quality tooling (validation, observability, tracing, type safety) while enabling rapid development velocity. The framework itself maintains high quality standards so applications built with it can move quickly with confidence.
Success Criteria: Visitors should be able to say, "I stood up a tenant-aware API with tracing, secrets, jobs, and database access in under an hour using GoBricks," and they should leave confident they can repeat that pattern in their own domain.
When working in this codebase, follow these principles from the developer manifesto:
context.ContextWhereRaw()ClientAMQPClient# 1. Start infrastructure services make docker-up # 2. Run database migrations make migrate # 3. Build and run application make run # 4. Test the API curl http://localhost:8080/health curl http://localhost:8080/api/v1/products
make dev # Full dev environment: docker-up + migrate (recommended first step) make build # Build application binary to bin/go-bricks-demo-project make run # Build + run (requires services to be running) make test # Run all tests with race detector make check # Run fmt + lint + test (pre-commit checks)
make docker-up # Start PostgreSQL + RabbitMQ + observability stack make docker-down # Stop all services and remove volumes make status # Show running service status make logs # Follow logs from all services
Note: All docker-compose files are located in
etc/docker/make migrate # Run Flyway migrations (uses --profile migrations) make migrate-info # Show migration status
make fmt # Format code with gofmt make lint # Run golangci-lint make coverage # Generate HTML coverage report
make loadtest-install # Install k6 load testing tool make loadtest-smoke # Quick validation (30 seconds) - run this first! make loadtest-crud # Realistic CRUD mix test (~15 min) make loadtest-read # Read-only baseline test (~12 min) make loadtest-ramp # Find breaking points (~17 min) make loadtest-spike # Test resilience under traffic spikes (~6 min) make loadtest-sustained # Detect memory/connection leaks (~17 min) make loadtest-all # Run all tests sequentially (~60 min)
See wiki/LOAD_TESTING.md for detailed load testing guide.
The application uses
go-bricks/app.New()config.yamlEntry point: cmd/api/main.go
app.New()getModulesToLoad()application.Run()Modules must implement
app.Moduletype Module interface { Name() string Init(*app.ModuleDeps) error RegisterRoutes(*server.HandlerRegistry, server.RouteRegistrar) DeclareMessaging(*messaging.Declarations) Shutdown() error }
Module structure pattern (see internal/modules/products/):
products/ ├── module.go # Module implementation, wires dependencies ├── domain/ # Domain models (Product) ├── repository/ # Data access layer (ProductRepository) ├── service/ # Business logic (ProductService) └── http/ # HTTP handlers (ProductHandler)
Dependency injection flow:
module.Init(deps *app.ModuleDeps)deps.GetDBdeps.GetMessagingRegisterRoutes()go-bricks config uses
koanfUnmarshal(key, &struct)mapstructure:InjectInto(&struct)config:Environment-based config:
APP_ENV=developmentconfig.yamlconfig.development.yamlconfig.{env}.yamlAPP_NAMEapp.nameIMPORTANT: The
DEBUGdebugunset DEBUG && make run
Modules receive context-aware database access via
deps.GetDBfunc (m *Module) Init(deps *app.ModuleDeps) error { m.getDB = deps.GetDB // Store function, don't call yet m.repo = repository.NewSQLProductRepository(m.getDB) // ... }
In repository methods:
func (r *Repository) GetByID(ctx context.Context, id string) (*Product, error) { db, err := r.getDB(ctx) // Get DB for this request's context if err != nil { return nil, err } // Use type-safe Filter API qb := database.NewQueryBuilder(database.PostgreSQL) f := qb.Filter() query, args, err := qb.Select("id", "name", "price"). From("products"). Where(f.Eq("id", id)). ToSQL() if err != nil { return nil, err } // Execute query... }
Why context-aware? Enables multi-tenant mode where
ctxCurrent mode: Single-tenant (see
config.yaml: multitenant.enabled: falseMulti-tenant mode (can be enabled):
X-Tenant-IDdeps.GetDB(ctx)The project supports two observability stacks that can be switched using Docker Compose profiles:
Best for: Local development with immediate feedback (< 30 seconds vs. 10-15 min cloud delay)
Start:
cd etc/docker docker-compose --profile local up -d
Access:
Features:
The local stack includes two production-ready dashboards:
1. Application Overview (
Go Bricks - Application OverviewOTel Runtime Metrics Support: The dashboard now uses OpenTelemetry semantic conventions for Go runtime metrics:
gobricks_go_memory_usedgobricks_go_memory_limitgobricks_go_memory_allocatedgobricks_go_goroutine_countgobricks_go_memory_gc_goalgo_gc_duration_secondsgobricks_go_processor_limitgobricks_go_config_gogcgobricks_go_schedule_durationgobricks_go_memory_allocationsgo_memstats_*2. Error Analysis (
Go Bricks - Error AnalysisAccess dashboards:
Dashboard features:
Best for: Production-like monitoring and APM
Setup:
.envNEW_RELIC_LICENSE_KEY=your_license_key_here NEW_RELIC_REGION=US # or EU
make docker-up-newrelic # Or manually: cd etc/docker docker-compose --profile newrelic up -d
Access:
go-bricks-demo-project# Stop current stack cd etc/docker && docker-compose down # Start desired stack docker-compose --profile local up -d # For Prometheus/Grafana/Loki/Tempo docker-compose --profile newrelic up -d # For New Relic
Note: Application doesn't need restart when switching - it always sends to
localhost:4317Planned implementation (OTLP export via Grafana Alloy):
Application (zerolog) → OTel SDK → Grafana Alloy → Loki → Grafana ↓ (also exports to Tempo & Prometheus)
Current Status:
mode="stdout+OTLP"volume_enabled: trueWhen OTLP logs work, you'll get:
LogQL query examples:
# All error-level logs {container_name=~".*"} |= "level" | json | level="error" # Logs for a specific trace {container_name=~".*"} |= "trace_id" | json | trace_id="abc123" # HTTP errors (status >= 400) {container_name=~".*"} | json | http_status >= 400 # Search for specific text in messages {container_name=~".*"} |= "database connection failed" # Rate of error logs (errors per second) sum(rate({container_name=~".*"} | json | level="error" [5m]))
Tip: Use Explore view in Grafana for ad-hoc log queries, or use pre-built dashboard panels.
# HTTP server metrics (namespace: gobricks_) gobricks_http_server_request_duration_seconds_bucket gobricks_http_server_request_body_size_bytes_bucket gobricks_http_server_response_body_size_bytes_bucket # Example queries: rate(gobricks_http_server_request_duration_seconds_count[5m]) # RPS histogram_quantile(0.95, rate(...[5m])) # p95 latency
See wiki/PROMETHEUS_GRAFANA_SETUP.md for complete observability guide.
This is a demo application built with GoBricks, not production code. Testing strategy reflects this:
Coverage Target: 60-70% on core business logic (repository queries, service methods, HTTP handlers)
Testing Focus:
Quality Gate: Run
make checkgo test ./internal/modules/products/... # Test specific module go test -v -race ./... # All tests with race detector go test -run TestProductService_Create ./... # Run specific test make test # Run all tests (uses race detector)
make test-products-api # Uses scripts/test-products-api.sh
Manual API testing:
# Ensure services are running make docker-up # Start app make run # Test endpoints curl http://localhost:8080/health curl http://localhost:8080/api/v1/products
The project includes comprehensive k6 load testing scripts. See wiki/LOAD_TESTING.md for details.
Quick start:
# Install k6 make loadtest-install # Run quick smoke test make loadtest-smoke # Run realistic CRUD test make loadtest-crud
Available tests:
TypeScript Support: All load tests are written in TypeScript for better type safety and IDE support. k6 v1.3.0+ has native TypeScript support, so tests run directly without any build step:
# Type check tests (optional - for catching errors before running) npm run type-check # Run tests directly - k6 handles TypeScript transpilation k6 run loadtests/products-crud.ts make loadtest-smoke # No webpack or build step needed!
Performance tuning:
config.development.yamldatabase.pool.max.connectionsconfig.development.yamlapp.rate.limit/burstdatabase.query.slow.thresholdCreate module directory structure:
mkdir -p internal/modules/mymodule/{domain,repository,service,http}
Implement
interface in app.Module
module.gotype Module struct { deps *app.ModuleDeps // ... your fields } func (m *Module) Init(deps *app.ModuleDeps) error { m.deps = deps // Wire up repository → service → handler return nil } func (m *Module) RegisterRoutes(hr *server.HandlerRegistry, r server.RouteRegistrar) { // Register HTTP routes }
Register in cmd/api/main.go:
func getModulesToLoad() []ModuleConfig { return []ModuleConfig{ {Name: "products", Enabled: true, Module: products.NewModule()}, {Name: "mymodule", Enabled: true, Module: mymodule.NewModule()}, } }
go-bricks location:
../go-bricksWhen modifying go-bricks:
cd ../go-bricks # Make changes cd ../go-bricks-demo-project make build # Automatically picks up local changes
go-bricks provides:
appconfigdatabasemessagingserverloggerobservabilityBase path:
/api/v1config.yaml: server.path.baseHealth checks:
GET /healthGET /readyProducts module:
GET /api/v1/productsGET /api/v1/products/:idPOST /api/v1/productsPUT /api/v1/products/:idDELETE /api/v1/products/:idconfig.yaml.env.env.exampleFollow these engineering principles when contributing:
Security is mandatory, not optional:
WhereRaw()// SECURITY: Manual SQL review completed - identifier quoting verified query := qb.WhereRaw("custom_condition")
Use go-bricks structured errors where possible. Handlers should return appropriate HTTP status codes.
Use structured logging via
deps.Loggerm.logger.Info(). Str("product_id", id). Msg("Product created successfully")
Use go-bricks type-safe Filter API for all queries:
qb := database.NewQueryBuilder(database.PostgreSQL) f := qb.Filter() // SELECT with filters query, args, err := qb.Select("id", "name", "price"). From("products"). Where(f.Eq("status", "active")). Where(f.Gt("price", 10.0)). ToSQL() // UPDATE with filters query, args, err := qb.Update("products"). Set("status", "inactive"). Where(f.Eq("id", productID)). ToSQL() // DELETE with filters query, args, err := qb.Delete("products"). Where(f.Eq("id", productID)). ToSQL()
Filter methods:
EqNotEqLtLteGtGteInNotInLikeNullNotNullBetweenAndOrNotRawImportant: Always use
ToSQL()ToSql()V1__description.sqlV2__another.sqlmake migrateAll Docker-related files are in etc/docker/ directory:
docker-compose.ymlotel/prometheus/promtail/loki/grafana/provisioning/datasources/dashboards/dashboards/json/alloy/Service profiles:
--profile local--profile newrelic--profile migrationsWhen contributing to this showcase project, follow this workflow to maintain quality and consistency:
.env.exampleBefore pushing to
mainmake check # Runs: fmt + lint + test
Required checks:
make fmtmake lintmake testRecommended checks:
make coveragemake loadtest-smokeNew to this codebase? Follow this tour to understand how everything fits together.
Explore the code in this order:
cmd/api/main.go - Application entry point
app.New()getModulesToLoad()internal/modules/products/module.go - Module implementation
app.ModuleInit(deps *app.ModuleDeps)RegisterRoutes()internal/modules/products/http/ - HTTP handlers
internal/modules/products/repository/ - Data access layer
getDB(ctx)SelectWhereToSQL()internal/modules/shared/ - Shared bricks
secrets/config.development.yaml - Configuration
Experience the application running:
Bootstrap environment:
make dev # Starts docker-up + runs migrations
Start application:
make run # Build and start the API server
Exercise endpoints:
# Health checks curl http://localhost:8080/health curl http://localhost:8080/ready # Products CRUD curl http://localhost:8080/api/v1/products curl http://localhost:8080/api/v1/products/1 # Or use the test script make test-products-api
Review telemetry:
gobricks_Inspect generated metrics:
# See what metrics are being emitted curl http://localhost:8889/metrics | grep gobricks_
Run load test:
make loadtest-smoke # 30-second quick validation # Watch metrics in Grafana update in real-time
After this tour, you'll understand the module system, dependency injection, observability integration, and how to extend the showcase with new capabilities.
# Symptom: Configuration error on startup # Solution: Unset DEBUG environment variable unset DEBUG && make run
# Stop all services and remove orphaned containers make docker-down docker ps -a | grep go-bricks | awk '{print $1}' | xargs docker rm -f make docker-up
# Symptom: "no connections available" errors under load # Solution: Increase pool size in config.development.yaml database.pool.max.connections: 50 # Increase from default 25
# Enable slow query logging in config.development.yaml database.query.slow.threshold: 100ms database.query.slow.enabled: true # Run application and check logs for slow queries make run
# Symptom: Loki datasource works but no logs appear in dashboards # Solution 1: Check Promtail is running and collecting logs docker logs go-bricks-promtail # Solution 2: Verify Loki is receiving data curl http://localhost:3100/ready curl http://localhost:3100/metrics | grep loki_ingester_streams_created_total # Solution 3: Ensure application is running and generating logs docker ps | grep go-bricks # Solution 4: Test Loki query manually curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={container_name=~".*"}' | jq
# This is expected behavior - collector may show "unhealthy" but still works # Check if it's actually processing telemetry: curl http://localhost:8889/metrics | grep gobricks_ # Should show metrics docker logs go-bricks-otel-collector-local | tail -20 # Should show trace/metric processing