Architecture

This section contains the canonical specifications for each package and subsystem in common-fwk. These documents describe contracts, requirements, and behavior boundaries — they serve as the authoritative reference for both human contributors and AI agents working with the codebase.

Packages

Package Doc Description
config Config Core Typed, panic-free config model
config/viper Viper Adapter File/env config loading via Viper
app App Bootstrap Instance-scoped application lifecycle
security/jwt JWT Security JWT validation contracts
security/keys Key Resolvers RSA and static key resolver contracts
http/gin Gin Middleware JWT auth middleware for Gin
errors Error Codes Exported error code constants
logging Logging Registry Named slog logger registry
app (presets) Health & Readiness Opt-in health/readiness endpoints

Design Principles

  • Explicit over implicit: no global singletons, no hidden initialization.
  • Deterministic behavior: identical inputs always produce identical outputs.
  • Adapter boundary: core packages do not depend on adapters (config never imports config/viper).
  • Panic-free APIs: all expected failures return error; panics are reserved for programming errors.
  • AI-readable: docs include scenarios and acceptance criteria suitable for AI agent consumption.

Table of contents