superapi

command module
v0.7.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

Go Version License Release

SuperAPI

Production-grade Go API template for SaaS backends.

IMPORTANT NOTICE

This is a TEMPLATE repository.

  • Do NOT install via go get
  • Use "Use this template" to create a new project
  • Generated projects are independent and do NOT auto-update

What This Is

SuperAPI is a modular Go API foundation focused on production use from day one.

It provides:

  • a module-oriented API architecture
  • policy-based middleware wiring
  • built-in auth, caching, rate limiting, and observability primitives
  • a store-first data layer with strict boundaries

Start here:

Data Layer Architecture

Enforced flow:

Service -> Repository -> Store -> Backend

Hard rules:

  • services call repositories for all data operations
  • services may call store.WithTx(...) only to define transaction boundaries for write operations; they must not call store execution methods (Execute, Query, etc.)
  • repositories own all data access logic and call store execution methods (Execute, Query, etc.)
  • repositories must not control transaction boundaries
  • handlers never call DB/store directly
  • one storage type per module (relational or document)
  • transaction API exists at store layer and is used only for write paths; services define the boundary via store.WithTx and repositories perform all store execution calls inside that scope

Features

  • Module system for explicit, composable API domains
  • Strict startup validation for runtime and policy configuration
  • goAuth integration for route-level authentication workflows
  • Redis-backed response cache with dynamic TagSpecs invalidation and Redis-backed rate limiting
  • Browser/proxy cache directives with policy.CacheControl(...)
  • Observability stack: metrics, tracing, and structured logs
  • Store-first data layer contracts in internal/core/storage
  • Built-in scaffolder for generating production-oriented modules

Acknowledgments

SuperAPI uses goAuth as its authentication engine.

goAuth is an open-source authentication framework that powers SuperAPI's route-level auth workflows and identity lifecycle integration.

Showcase

The following project uses SuperAPI as its backend foundation in production-oriented development:

Quick Start

1. Click "Use this template"
2. Clone your new repo
3. go run ./cmd/api

After startup:

  • Liveness: GET /healthz
  • Readiness: GET /readyz
Minimal mode (no external dependencies)

Use the profile that disables Postgres, Redis, auth, cache, and rate limiting:

cp .env.example .env
# edit .env and enable:
# APP_PROFILE=minimal

go run ./cmd/api
Full mode (Postgres + Redis + auth)

Use .env.example full-mode defaults, then run:

go run ./cmd/api

Required full-mode toggles are already shown in .env.example:

  • POSTGRES_ENABLED=true with valid POSTGRES_URL
  • REDIS_ENABLED=true with valid REDIS_ADDR
  • AUTH_ENABLED=true
  • RATELIMIT_ENABLED=true
  • CACHE_ENABLED=true

How To Build APIs

  1. Create a module
make module name=projects

Expected output:

generated module "projects" (package="projects" route=/api/v1/projects)
  1. Confirm module wiring

internal/modules/modules.go is updated automatically with import + projects.New() entry.

  1. Verify and run
go test ./internal/devx/modulegen ./internal/modules/projects
go run ./cmd/superapi-verify ./internal/modules/projects
go run ./cmd/api

  1. Add handlers and service logic in the generated module files.

  2. Add repositories that execute store operations and keep query logic inside repository.

Guides:

Docs Navigation

Philosophy

  • Secure by default in production-sensitive paths
  • Explicit policies over implicit behavior
  • Fail-fast validation at startup for unsafe configurations
  • One enforced data-layer architecture over compatibility layers

Versioning And Updates

  • This template is distributed as a snapshot.
  • Generated repositories do not receive automatic upstream updates.
  • Upgrades are manual: compare changes, port intentionally, and validate with tests/build.
  • Current public template baseline: v0.7.0 (pre-1.0 by intent).

Release Hygiene

Before publishing a downstream release:

go test ./...
go build ./...

Contributing

Contribution process and governance rules are documented in CONTRIBUTING.md.

Documentation

Overview

Package main provides the repository placeholder entrypoint.

Use cmd/api for the production server bootstrap.

Source Files

View all Source files

Directories

Path Synopsis
cmd
api command
Command api starts the SuperAPI HTTP server using environment-driven configuration.
 Command api starts the SuperAPI HTTP server using environment-driven configuration.
authgen command
Command authgen scaffolds goAuth bootstrap artifacts for SuperAPI projects.
 Command authgen scaffolds goAuth bootstrap artifacts for SuperAPI projects.
migrate command
Command migrate applies and manages database migrations for SuperAPI.
 Command migrate applies and manages database migrations for SuperAPI.
modulegen command
Command modulegen creates new module scaffolds with optional policy and DB wiring.
 Command modulegen creates new module scaffolds with optional policy and DB wiring.
modulesync command
Command modulesync syncs module-level schema/query files into shared sqlc directories.
 Command modulesync syncs module-level schema/query files into shared sqlc directories.
perftoken command
Command perftoken generates auth tokens for load and performance testing workflows.
 Command perftoken generates auth tokens for load and performance testing workflows.
superapi-verify command
Command superapi-verify runs static route and policy validation across the codebase.
 Command superapi-verify runs static route and policy validation across the codebase.
internal
core/app
Package app wires the HTTP server, module registration, and lifecycle management.
 Package app wires the HTTP server, module registration, and lifecycle management.
core/auth
Package auth provides authentication context types and goAuth provider integration.
 Package auth provides authentication context types and goAuth provider integration.
core/cache
Package cache implements Redis-backed response caching and cache key generation utilities.
 Package cache implements Redis-backed response caching and cache key generation utilities.
core/config
Package config loads, normalizes, and validates runtime configuration from environment variables.
 Package config loads, normalizes, and validates runtime configuration from environment variables.
core/db
Package db provides Postgres connectivity and migrations for storage backends.
 Package db provides Postgres connectivity and migrations for storage backends.
core/db/sqlcgen
core/errors
Package errors defines typed application errors used for consistent API responses.
 Package errors defines typed application errors used for consistent API responses.
core/httpx
Package httpx contains HTTP adapters, middleware, and router helpers used by modules.
 Package httpx contains HTTP adapters, middleware, and router helpers used by modules.
core/logx
Package logx wraps structured logging setup and logger configuration.
 Package logx wraps structured logging setup and logger configuration.
core/metrics
Package metrics provides Prometheus instrumentation for HTTP, readiness, and policy signals.
 Package metrics provides Prometheus instrumentation for HTTP, readiness, and policy signals.
core/modulekit
Package modulekit provides module-safe accessors for runtime dependencies.
 Package modulekit provides module-safe accessors for runtime dependencies.
core/netx
Package netx contains network helpers such as trusted client IP extraction.
 Package netx contains network helpers such as trusted client IP extraction.
core/params
Package params provides normalized request parameter helper functions.
 Package params provides normalized request parameter helper functions.
core/policy
Package policy provides route-level middleware for auth, RBAC, tenant checks, rate limiting, and cache control.
 Package policy provides route-level middleware for auth, RBAC, tenant checks, rate limiting, and cache control.
core/ratelimit
Package ratelimit implements Redis-backed rate limiting primitives and keying strategies.
 Package ratelimit implements Redis-backed rate limiting primitives and keying strategies.
core/readiness
Package readiness aggregates dependency health into a sanitized readiness report.
 Package readiness aggregates dependency health into a sanitized readiness report.
core/requestid
Package requestid defines request-id context storage and retrieval helpers.
 Package requestid defines request-id context storage and retrieval helpers.
core/response
Package response writes API envelopes and error payloads with centralized sanitization.
 Package response writes API envelopes and error payloads with centralized sanitization.
core/storage
Package storage defines the enforced data-layer contracts used by repositories.
 Package storage defines the enforced data-layer contracts used by repositories.
core/tenant
Package tenant provides tenant-scope utilities used by auth and policy layers.
 Package tenant provides tenant-scope utilities used by auth and policy layers.
core/tracing
Package tracing configures OpenTelemetry provider lifecycle for the API process.
 Package tracing configures OpenTelemetry provider lifecycle for the API process.
devx/modulegen
Package modulegen provides scaffolding utilities for creating new API modules.
 Package modulegen provides scaffolding utilities for creating new API modules.
devx/modulesync
Package modulesync syncs module-local SQL assets into global sqlc input folders.
 Package modulesync syncs module-local SQL assets into global sqlc input folders.
modules
Package modules registers built-in runtime modules for the API process.
 Package modules registers built-in runtime modules for the API process.
modules/health
Package health exposes liveness and readiness endpoints as an app module.
 Package health exposes liveness and readiness endpoints as an app module.
modules/system
Package system provides system-level example routes, auth demos, and utility endpoints.
 Package system provides system-level example routes, auth demos, and utility endpoints.
tools/validator
Package validator statically validates route policy wiring for SuperAPI modules.
 Package validator statically validates route policy wiring for SuperAPI modules.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.