Maintained by Swift Kimani

Build Go backends
the right way.

Production-ready scaffolding with CQRS, clean architecture, OpenTelemetry, MCP Server, and a full CRUD API. Clone it, extend it, ship it.

Read the Docs
terminal
$ npx github:swiftkimani/goolang-backend my-app
$ cd my-app && go mod tidy && make test
$ go run ./cmd/server start --env local
✓ Server running on http://localhost:8080
GET /health → 200 OK

Everything you need, nothing you don't

Battle-tested patterns for real production workloads

⚡

CQRS Architecture

Clean separation of Commands and Queries. Business logic stays isolated, testable, and maintainable.

app/users_commands.go
🔌

OpenAPI-First API

Define your API in YAML, get type-safe handlers generated automatically. Zero boilerplate, full validation.

internal/api/http/v1routes.yaml
📊

OpenTelemetry

Built-in distributed tracing, metrics, and structured logging. Plug in any OTLP-compatible backend.

internal/telemetry/
🤖

MCP Server

Model Context Protocol tools over stdio and HTTP. Ready for AI agent integrations out of the box.

cmd/mcp/
💾

SQLite (No CGO)

Pure-Go SQLite driver. Zero external dependencies. Perfect for single-node deployments.

internal/infrastructure/
🏗️

Layered Architecture

API → Application → Infrastructure. Consumer-defined interfaces, dependency inversion, DI via uber/dig.

internal/wireup.go
🐳

Multi-Platform Docker

Distroless runtime images for linux/amd64 and arm64. Minimal attack surface, maximum security.

build/docker/Dockerfile
📦

Helm + Kubernetes

Production Helm charts with Gateway API support. Deploy to any K8s cluster in minutes.

deploy/helm/
🧪

Test Infrastructure

Mock generation, faker data, time mocking, deterministic UUIDs. Every pattern you need for thorough testing.

doc/testing-best-practices.md

Up and running in 30 seconds

01

Scaffold a new project

npx github:swiftkimani/goolang-backend my-project
02

Install dependencies

cd my-project && go mod tidy
03

Run it

go run ./cmd/server start --env local
04

Test the API

curl http://localhost:8080/health

Prefer git clone instead of npx, or want the full CLI/config/deployment reference? Read the docs →

Try the endpoints

Interact with the running API directly from this page

health
echo
users
pets
GET
/health
Click "Send Request" to see the response
              

Pragmatic layered architecture

Every layer has a clear responsibility. Dependencies point inward only.

API Layer
HTTP, MCP — where the world meets your system
internal/api/http/ · internal/api/mcp/
↓ Consumer-Defined Interfaces
Application Layer
CQRS Commands & Queries — all business logic lives here
internal/app/
↓ Ports (Interfaces)
Infrastructure Layer
SQLite, Petstore API, HTTP clients — outbound adapters
internal/infrastructure/
↓
Cross-Cutting
Config, DI, Telemetry, Time, Identity
internal/config/ · internal/di/ · internal/telemetry/ · internal/system/
Go 1.26 SQLite uber/dig Cobra Viper OpenTelemetry mcp-go Docker Helm GitHub Actions
Copied to clipboard!