pkg — Shared Utility Libraries
Under Reviewv0.1.0-alpha
The pkg/ directory contains framework-agnostic, reusable Go packages that provide cross-cutting infrastructure to the rest of the application. These packages have no knowledge of domain logic and can be imported by any layer (internal/core, internal/gateway, adapters, etc.) without creating circular dependencies.
Package Index
| Package | Purpose | Key Exports |
|---|---|---|
ctxkeys | Type-safe context key constants | UserIDKey, UserRoleKey, CorrelationIDKey |
errors | Domain-aware HTTP error type | AppError, NewBadRequest, NewInternal, … |
idgen | Cryptographically secure UUIDv7 ID generation | Generate, MustGenerate, ToUUID, FromUUID |
logger | Structured logging with OTel trace correlation | Logger, NewLogger, ECSHandler, context-aware methods |
response | JSON API envelope + RFC 7807 Problem Details | APIResponse, ProblemDetail, GinOK, GinWriteError |
telemetry | OpenTelemetry tracing bootstrap | Config, ReadConfigFromEnv, Init |
token | Internal HMAC token manager + OIDC validator | JWTManager, OIDCValidator |
validator | Input validation helpers | ValidateStruct, ValidateEmail, ValidatePassword |
db | Database connection interface and adapters | Connection, SQLConnection, MongoConnection |
metrics | Prometheus metrics registration | HTTP metrics, DB pool collector, cache metrics |
Design Principles
- No domain imports — packages under
pkg/never import frominternal/coreorinternal/infra(with the exception ofmetrics, which references an infra interface for pool stats — see the metrics doc for details). - Minimal coupling — each package is independently importable with no hard dependencies on sibling packages.
- Env-driven config — runtime behaviour (log format, telemetry sampling, etc.) is controlled via environment variables.
- OTel-first observability — logging and response writing integrate natively with OpenTelemetry trace context, attaching
trace_idandspan_idto every log record and error response automatically.