README
¶
go-core
Overview
go-core is a modular Go backend framework that provides a shared foundation for building production-grade services.
It standardizes:
- Authentication & authorization
- Database access & transactions
- Validation & binding
- Error handling
- Middleware & HTTP layer
- Audit logging
- Multi-tenancy
- Event system
- Worker processes
The goal is to eliminate boilerplate and enforce safe, predictable patterns across all services.
Key Principles
- Strong typing over dynamic behavior
- Explicit architecture (no hidden magic)
- Thin handlers, fat services
- Centralized error handling via
apperr - Context-driven request lifecycle
- Modular design (plug-and-play packages)
Project Structure
Core Packages
bootstrap→ application lifecycle, DI container, configweb→ HTTP handling, response format, helpersauth→ authentication, JWT, policies, middlewaredatabase→ repositories, transactions, typesvalidation→ input validation systembinders→ request binding (JSON, multipart)middlewares→ HTTP middleware (auth, logging, security)worker→ background workers
Feature Packages
audit→ audit logging and diff trackingdatatable→ filtering, pagination, query helperstenancy→ multi-tenant context + DB scopingevent→ event bus abstraction
Utility Packages
apperr→ structured application errorsi18n→ localization helpersgo2ts→ Go → TypeScript type generationutils→ generic helpers
Example App
go-core-example→ reference implementation
How It Works
Request Flow
- HTTP request enters via
engine/gin.go - Middleware chain executes (
middlewares) - Request is bound using
binders - Input validated via
validation - Handler calls service layer
- Service uses repositories (
database) - Errors returned as
apperr.AppError - Response formatted via
web/response
Error Handling
All errors use apperr.AppError:
- Structured error codes
- Log level hints
- Field-level validation errors
Example:
return apperr.BadRequest("invalid input")
Authentication
- JWT-based authentication
- Policy-based authorization (
namespace:action) - Context-based user injection
user := auth.MustGetUser[MyUser](ctx)
Database
- GORM-based repositories
- Transaction support via context
- Custom nullable & typed fields
Audit Logging
- Tracks entity changes
- Stores before/after state
- Uses reflection-based diff
Multi-Tenancy
- Context-based tenant resolution
- Optional DB query scoping
Rules
- Do not bypass
apperr - Do not access DB outside repositories
- Do not put business logic in handlers
- Always pass
context.Context - Prefer interfaces over concrete types
Purpose
This repository is a core library, not an application.
All business logic should live in consuming services.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apperr defines the standard structured error type used across go-core and all consuming services.
|
Package apperr defines the standard structured error type used across go-core and all consuming services. |
|
audit/diff.go
|
audit/diff.go |
|
server
Package server provides the authentication server implementation.
|
Package server provides the authentication server implementation. |
|
Package binders parses HTTP request bodies and coerces values into typed request structs.
|
Package binders parses HTTP request bodies and coerces values into typed request structs. |
|
Package bootstrap wires together the application lifecycle, dependency injection container, configuration loading, and HTTP server startup.
|
Package bootstrap wires together the application lifecycle, dependency injection container, configuration loading, and HTTP server startup. |
|
Package database provides GORM-based database access, connection registry, repository helpers, transaction management, and schema migration utilities.
|
Package database provides GORM-based database access, connection registry, repository helpers, transaction management, and schema migration utilities. |
|
sqlc
Package sqlc is a scaffold for integrating SQLC-generated query code with the go-core database infrastructure.
|
Package sqlc is a scaffold for integrating SQLC-generated query code with the go-core database infrastructure. |
|
Package event provides event bus, outbox, and deduplication primitives.
|
Package event provides event bus, outbox, and deduplication primitives. |
|
Package httpclient provides a reusable HTTP client for calling external APIs.
|
Package httpclient provides a reusable HTTP client for calling external APIs. |
|
go-core/i18n/i18n.go
|
go-core/i18n/i18n.go |
|
internal
|
|
|
depgraph
Package depgraph provides a simple directed graph implementation for validating dependency graphs for cycles and missing nodes.
|
Package depgraph provides a simple directed graph implementation for validating dependency graphs for cycles and missing nodes. |
|
reflectioncache
Package reflectioncache provides a concurrency-safe reflection metadata cache.
|
Package reflectioncache provides a concurrency-safe reflection metadata cache. |
|
Package middlewares provides HTTP middleware for the gin framework.
|
Package middlewares provides HTTP middleware for the gin framework. |
|
observability/observability.go
|
observability/observability.go |
|
Package resource provides a generic resource type for interacting with a database.
|
Package resource provides a generic resource type for interacting with a database. |
|
go-core/tenancy/context.go
|
go-core/tenancy/context.go |
|
Package utils provides utility functions for converting types to strings and integers.
|
Package utils provides utility functions for converting types to strings and integers. |
|
Package validation provides a lightweight, struct-tag-driven input validation system for request types.
|
Package validation provides a lightweight, struct-tag-driven input validation system for request types. |
|
worker/manager_metrics.go
|
worker/manager_metrics.go |
Click to show internal directories.
Click to hide internal directories.