Everything Backend Starter Kit

Table of Contents

• Overview
• Tech Stack
• Architecture at a Glance
• Quick Start
• Documentation
• License

Overview

This repository is a production-oriented Go backend starter that brings together authentication, authorization, observability, and delivery tooling in one baseline:

• Google OAuth login
• Cookie-based JWT session flow (access + refresh)
• Session/device management APIs (/api/v1/me/sessions)
• RBAC authorization
• Redis-backed caching for admin list, RBAC permission, and negative lookup flows
• Redis-backed rate limiting and abuse-protection controls
• OpenTelemetry metrics, traces, and logs
• Local tri-signal stack (Grafana + Tempo + Loki + Mimir + OTel Collector)
• Bazel + Gazelle + Task + Wire development workflow
• API server in cmd/api
• Operational CLIs in cmd/migrate, cmd/seed, cmd/loadgen, cmd/obscheck
• Layered internal packages (internal/*) with DI composition through Wire
• Docker Compose local stack for DB + observability
• CI + local hooks enforcing build/test/generation hygiene

Tech Stack

• Language/runtime:
• HTTP framework:
• Persistence:
• Cache/rate limiting/idempotency backend:
• Object storage:
• Auth:
• Observability:
• Tooling:

Architecture at a Glance

• Request path: internal/http ==> internal/service ==> internal/repository ==> internal/database
• Cross-cutting concerns: internal/security, internal/observability, middleware, and Redis-backed controls
• Dependency injection: internal/di (Wire-generated injectors validated in CI)

flowchart LR
    User[Web or API Client] --> Router[Chi Router + Middleware]
    Router --> Handlers[HTTP Handlers]
    Handlers --> Services[Service Layer]
    Services --> Repos[Repository Layer]
    Repos --> DB[(PostgreSQL)]
    Services --> Redis[(Redis)]
    Services --> MinIO[(MinIO/S3)]

    Handlers --> OAuth[Google OAuth Provider]
    OAuth --> Handlers

    Router -. request logs, metrics, traces .-> OTelSDK[OTel SDK]
    Services -. cache and auth metrics .-> OTelSDK
    Repos -. db telemetry .-> OTelSDK

    OTelSDK --> Collector[OTel Collector]
    Collector --> Tempo[Tempo Traces]
    Collector --> Loki[Loki Logs]
    Collector --> Mimir[Mimir Metrics]

    Grafana[Grafana] --> Tempo
    Grafana --> Loki
    Grafana --> Mimir

    Loadgen[cmd/loadgen] --> Router
    Obscheck[cmd/obscheck] --> Grafana

Loading

Quick Start

Prerequisites:

• Go 1.26.0
• Task
• Bazelisk (uses Bazel 9.0.0 from .bazelversion)
• Docker + Docker Compose

Clone the repo and cd into it

git clone git@github.com:sandeepkv93/everything-backend-starter-kit.git
cd everything-backend-starter-kit

Configure environment

cp .env.example .env

Start local dependencies and run API

task docker-up
task migrate
task seed
task run

Database reset/backup/restore (local)

These commands operate on the Docker Compose-managed Postgres service (db) and its data volume.

# reset Postgres container + DB volume and start fresh db service
task integration:reset-db

# create SQL backup (default: backups/backup_<timestamp>.sql)
task integration:backup-db

# restore from backup file
task integration:restore-db FILE=backups/backup_20260217_103000.sql

Expected success checks

curl -sSf http://localhost:8080/health/live
curl -sSf http://localhost:8080/health/ready

REST Client Collection (Manual API Verification)

Use the checked-in VS Code REST Client collections to exercise all APIs (including detailed RBAC/admin flows) end-to-end.

1. Install the REST Client extension: https://marketplace.visualstudio.com/items?itemName=humao.rest-client
2. Open the detailed split collections in api/rest-client/ (recommended):
   • 00-quickstart.rest
   • 01-auth.rest
   • 02-user-me-sessions-avatar.rest
   • 03-products.rest
   • 04-feature-flags.rest
   • 05-admin-rbac.rest
3. Optionally use api/everything-backend-starter-kit.rest as a monolithic fallback
4. Update variables at the top (@baseUrl, user credentials, IDs) for your local environment
5. Run requests in sequence:
   • health checks
   • local login/register
   • CSRF-protected endpoints (/auth/refresh, /auth/logout, /auth/local/change-password, /me/* mutating routes)
   • admin RBAC endpoints with a user that has required permissions

Notes:

• Cookie-based auth is used, so enable REST Client cookie persistence (rest-client.rememberCookiesForSubsequentRequests).
• Idempotency-key headers are included for routes that can be wrapped by idempotency middleware.
• When routes change in internal/http/router/router.go, update api/rest-client/*.rest (and monolithic file if used) in the same PR.

Pre-commit workflow

Install hooks and local tooling:

task hooks-install

Run the full hook suite manually:

task hooks-run-all
# or, if pre-commit is already on PATH:
pre-commit run --all-files

Hook coverage includes Go formatting/linting (gofmt, goimports, golangci-lint, go mod tidy), Dockerfile linting (hadolint), YAML linting (yamllint), and secret scanning (detect-secrets).

Mock Generation

Deterministic gomock files are generated from exported interfaces in key packages.

task mockgen:install
task mockgen
task mockgen-check

Generated output directories:

• internal/repository/gomock
• internal/service/gomock
• internal/health/gomock
• internal/http/middleware/gomock

CI enforces drift checks by re-running the generator.

Feature flags

Runtime feature toggles support user evaluation and RBAC-gated admin management.

• User evaluation endpoints:
  • GET /api/v1/feature-flags
  • GET /api/v1/feature-flags/{key}
• Admin endpoints (require feature_flags:read / feature_flags:write):
  • GET|POST /api/v1/admin/feature-flags
  • GET|PATCH|DELETE /api/v1/admin/feature-flags/{id}
  • GET|POST /api/v1/admin/feature-flags/{id}/rules
  • PATCH|DELETE /api/v1/admin/feature-flags/{id}/rules/{rule_id}

Rule matching precedence during evaluation: user > role > org > environment > percent > flag default.

Products Blueprint Module

Sample products CRUD module demonstrates domain/repository/service/handler layering with RBAC-protected routes and paginated list responses.

• Endpoints:
  • GET /api/v1/products (requires products:read)
  • GET /api/v1/products/{id} (requires products:read)
  • POST /api/v1/products (requires products:write)
  • PUT /api/v1/products/{id} (requires products:write)
  • DELETE /api/v1/products/{id} (requires products:delete)
• Pagination defaults:
  • page=1, page_size=20, max page_size=100

Endpoints:

• API base URL: http://localhost:8080
• Grafana UI: http://localhost:3000 (admin / admin)
• MinIO Console: http://localhost:9001 (minioadmin / minioadmin)

Documentation

• Project guide (full documentation)
• Architecture and flow diagrams
• Kubernetes deployment guide
• Audit Taxonomy

License

MIT. See LICENSE for details.