powerman/go-service-example

This system is a Go-based address-book microservice that manages contact records using a MySQL backend with seek-based pagination. It exposes a secure HTTP API defined by an OpenAPI specification, featuring API key-based authentication and role-based authorization to restrict write access. The architecture follows Clean Principles, separating concerns into data access, application logic, and server layers, while providing comprehensive observability through Prometheus metrics and standardized error handling.

The service now supports configuring a MySQL database connection via environment variables (prefixed with EXAMPLE\_) and CLI flags. Users can set the host, port, database name, username, and password for MySQL, as well as the directory for database migrations. The configuration also includes settings for the main service API host/port and Prometheus metrics port, with defaults provided for local development.

internal/config · high confidence

The internal data access layer now supports MySQL as a persistent storage backend, complementing the existing in-memory implementation. This addition includes database schema migrations (creating a Contact table), SQL query definitions, and integration tests to verify functionality. For users, this enables the application to store contacts persistently using MySQL, with the listing endpoint supporting efficient seek-based pagination (filtering by ID) rather than simple offset-based paging.

internal/dal · high confidence

This change introduces the foundational business logic and supporting utilities for the service. It adds the \internal/app\ package, which defines the \Appl\ and \Repo\ interfaces along with the \App\ implementation for managing contacts (listing and adding) and health checks, including specific error handling for duplicate contacts. It also introduces \internal/apix\ to provide context helpers for propagating remote IP addresses. Additionally, Prometheus metrics initialization is added to the application package to support observability.

internal/app · high confidence

The repository has been initialized with the core structure for a Go service example, including a Dockerfile, docker-compose configuration for local development with MySQL, and environment variable templates. It introduces a strict golangci-lint configuration, a tools.go file to manage development dependencies (such as go-swagger and mockgen), and standard Git/Docker ignore attributes. The project also includes a comprehensive README detailing the Clean Architecture implementation, package structure, and usage instructions for running the service via Docker.

(repo-wide) · high confidence

The \cmd/address-book\ directory now contains the complete entry point for the example microservice. This includes the main executable logic with graceful shutdown handling, service initialization wiring (connecting the MySQL data access layer, application logic, and OpenAPI server), Prometheus metrics registration, and a CLI interface via Cobra. An integration test suite is also provided to verify the service's HTTP API behavior against a temporary MySQL database.

cmd · high confidence

The service now exposes an HTTP API using the OpenAPI (Swagger) specification, replacing or supplementing previous transport mechanisms. This new server layer implements API key-based authentication (distinguishing between admin and standard users) and authorization, ensuring that non-admin users cannot perform write operations. It includes a health check endpoint, contact listing with seek pagination, and contact creation, all wrapped in middleware for logging, access metrics (Prometheus), CORS, and error recovery. Error responses now follow a standardized format with both HTTP status codes and application-specific error codes, and internal errors are masked from clients to prevent information leakage.

internal/srv · high confidence

Added shell scripts to automate the development workflow: \scripts/build\ compiles Go binaries with version injection and builds Docker images; \scripts/test\ runs linting (hadolint, shellcheck, golangci-lint) and integration tests with race detection; \scripts/cover\ generates code coverage reports; \scripts/stat\ outputs source line counts; and \scripts/test-ci-circle\ facilitates local execution of CircleCI configurations.

scripts · high confidence

This change introduces a new \pkg/\ directory containing a collection of reusable utility packages designed to standardize common service patterns. Key additions include \pkg/def\ for centralized application initialization, logging configuration, and metrics setup; \pkg/migrate\ and \pkg/cobrax\ to provide a structured, type-safe interface for running database migrations (specifically MySQL via Goose) as CLI commands; \pkg/repo\ to offer a Data Access Layer wrapper that handles transaction management, schema version locking, and automatic instrumentation; and \pkg/serve\ to simplify starting and managing HTTP and OpenAPI servers with context-aware shutdown. These packages collectively reduce boilerplate for new services by providing pre-built components for dependency injection, database access, and server lifecycle management.

pkg · high confidence

The OpenAPI specification (swagger.yml) has been updated to version 0.2.0, introducing a new /health-check endpoint that returns a 200 status when the service is operational. Additionally, the /contacts GET endpoint now supports seek-based pagination via the SeekPagination model, requiring since\_id and limit parameters to return contacts ordered by ID. The spec also defines a standardized Error model for consistent error responses across the API.

api · high confidence

The project introduces a new go.mod file establishing the initial dependency set for the Go service. This includes core libraries for HTTP handling (go-openapi/runtime, swag, strfmt, validate, spec, loads, errors), database access (go-sql-driver/mysql, lib/pq, sqlx), CLI tools (spf13/cobra, pflag), and internal utility packages (powerman/structlog, dockerize, appcfg). The manifest also sets the Go version to 1.16 and includes development tools for linting, mocking, and testing.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 58 → 61 (+3.5)
• Rubric changed (rubric-2026.08.17 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 100 (+0.3)
• Architecture 100 → 92 (-7.8)
• Maturity 52 → 54 (+1.8)
• Readiness 52 → 58 (+6.0)
• Security 50 → 57 (+7.5)
• Domain Modelling 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — no supported dependency manifest was read
• Duplicated block (6 lines × 2) (internal/config/config.go)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 7 more

• Critical CVE: [GHSA redacted] (go.sum)
• Critical CVE: [GHSA redacted] (go.sum)
• Dependency pinned to a stale untagged commit: github.com/cheekybits/genny
• Dependency pinned to a stale untagged commit: github.com/sebest/xff
• Dependency pinned to a stale untagged commit: golang.org/x/net
• Duplicated block (5 lines × 2) (internal/config/config.go)
• High CVE: [GHSA redacted] (go.mod)
• High CVE: [GHSA redacted] (go.sum)
• High CVE: [GHSA redacted] (go.sum)
• High CVE: [GHSA redacted] (go.mod)
• High CVE: [GHSA redacted] (go.sum)
• High IaC: WD-DOCKER-0013 (Dockerfile)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 66 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

powerman/go-service-example was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.