README
¶
📦 go-foundation
The shared, domain-agnostic foundation kit for modern Go services
CI / CD
|
|
Quality
|
|
Security
|
|
Community
|
|
Project Navigation
🚀 Installation
|
🧪 Examples & Tests
|
📚 Documentation
|
🤝 Contributing
|
🛠️ Code Standards
|
⚡ Benchmarks
|
🤖 AI Usage
|
⚖️ License
|
👥 Maintainers
|
🧩 About
go-foundation is the shared, domain-agnostic foundation kit used across several Go services and projects. It exists to kill drift: instead of every service re-implementing the same configuration, HTTP, persistence, and observability plumbing, that plumbing lives here once and is consumed everywhere.
The module carries only generic building blocks — no business domain, no project-specific naming. As the kit is assembled it exposes focused sub-packages:
config— application, database, logging, and AWS configuration typeslambda— AWS Lambda (API Gateway v2) ⇄net/httpadaptermiddleware— logging, recovery, and request-ID HTTP middlewarehttputil— JSON response and error helperspagination— cursor-based list paginationrecurrence— DST-correct next-occurrence calculator for weekly recurring event patternsmodels— genericBaseModel,Repository,Clock, and transaction helperssecrets— pluggable secret providers (env, AWS, mock)db— database connection helpershealth— health-check helpersobservability— structured logging initializationtestutil— generic test helpers (test database, fixed clock, containers)
Project-specific naming — environment prefixes, database names, health messages, and infrastructure constants — intentionally stays in the consuming services, never in this module.
📦 Installation
go-foundation requires a supported release of Go.
go get -u github.com/mrz1836/go-foundation
Get the MAGE-X build tool for development:
go install github.com/mrz1836/mage-x/cmd/magex@latest
📚 Documentation
- API Reference – Dive into the godocs at pkg.go.dev/github.com/mrz1836/go-foundation
- Benchmarks – Check the latest numbers in the benchmark results
- Test Suite – Review both the unit tests (powered by
testify)
Repository Features
This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.
Library Deployment
This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:
brew install goreleaser
The release process is defined in the .goreleaser.yml configuration file.
Then create and push a new Git tag using:
magex version:bump push=true bump=patch branch=master
This process ensures consistent, repeatable releases with properly versioned artifacts and metadata.
Pre-commit Hooks
Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:
go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install
The system is configured via modular env files in .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.
GitHub Workflows
All workflows are driven by modular configuration in .github/env/ — no YAML editing required.
Updating Dependencies
To update all dependencies (Go modules, linters, and related tools), run:
magex deps:update
This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.
Build Commands
View all build commands
magex help
🧪 Examples & Tests
All unit tests run via GitHub Actions and use Go version 1.25.x. View the configuration file.
Run all tests (fast):
magex test
Run all tests with race detector (slower):
magex test:race
⚡ Benchmarks
Run the Go benchmarks:
magex bench
Benchmarks for the foundation sub-packages are added as those packages are extracted.
🛠️ Code Standards
Read more about this Go project's code standards.
🤖 AI Usage & Assistant Guidelines
Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.
👥 Maintainers
 |
|---|
| MrZ |
🤝 Contributing
View the contributing guidelines and please follow the code of conduct.
How can I help?
All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀
📝 License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides a lightweight, type-safe configuration layer for serverless and HTTP services.
|
Package config provides a lightweight, type-safe configuration layer for serverless and HTTP services. |
|
Package constants provides shared, domain-agnostic HTTP constants — header names, content types, CORS values, and standardized error codes and messages — used by the foundation HTTP, Lambda, and response helpers.
|
Package constants provides shared, domain-agnostic HTTP constants — header names, content types, CORS values, and standardized error codes and messages — used by the foundation HTTP, Lambda, and response helpers. |
|
Package db provides GORM database connection management for serverless and HTTP services.
|
Package db provides GORM database connection management for serverless and HTTP services. |
|
Package health provides health check services for database connections.
|
Package health provides health check services for database connections. |
|
Package httputil provides shared HTTP response helpers.
|
Package httputil provides shared HTTP response helpers. |
|
Package lambda provides a lightweight AWS API Gateway v2 ↔ net/http adapter.
|
Package lambda provides a lightweight AWS API Gateway v2 ↔ net/http adapter. |
|
Package middleware provides production-ready HTTP middleware for serverless Lambda functions and local HTTP servers.
|
Package middleware provides production-ready HTTP middleware for serverless Lambda functions and local HTTP servers. |
|
Package models provides core infrastructure for GORM-based domain models.
|
Package models provides core infrastructure for GORM-based domain models. |
|
Package observability centralizes log/metric/trace setup so every binary (local server, Lambda, daemon, snapshot tool, build tooling) configures slog the same way.
|
Package observability centralizes log/metric/trace setup so every binary (local server, Lambda, daemon, snapshot tool, build tooling) configures slog the same way. |
|
Package pagination provides cursor-based pagination utilities.
|
Package pagination provides cursor-based pagination utilities. |
|
Package recurrence computes next occurrences of weekly recurring event patterns expressed as JSON.
|
Package recurrence computes next occurrences of weekly recurring event patterns expressed as JSON. |
|
Package secrets provides a unified interface for retrieving secrets from various sources.
|
Package secrets provides a unified interface for retrieving secrets from various sources. |
|
Package testutil provides generic, domain-agnostic test helpers for services built on go-foundation: in-memory SQLite databases, ready-made test configurations, and (behind the "integration" build tag) a PostgreSQL testcontainers harness.
|
Package testutil provides generic, domain-agnostic test helpers for services built on go-foundation: in-memory SQLite databases, ready-made test configurations, and (behind the "integration" build tag) a PostgreSQL testcontainers harness. |