goplt/docs/content/adr/0006-http-framework.md

ADR-0006: HTTP Framework

Status

Accepted

Context

The platform needs an HTTP framework for:

• REST API endpoints
• Middleware support (auth, logging, metrics)
• Request/response handling
• Route registration from modules
• Integration with observability tools

Options considered:

1. gin-gonic/gin - Fast, feature-rich HTTP web framework
2. gorilla/mux - Lightweight router
3. go-chi/chi - Lightweight, idiomatic router
4. net/http (standard library) - No external dependency

Decision

Use gin-gonic/gin (v1.9.1+) as the HTTP framework.

Rationale:

• Fast performance (comparable to net/http)
• Rich middleware ecosystem
• Excellent for REST APIs
• Easy route grouping (useful for modules)
• Good OpenTelemetry integration support
• Widely used and well-documented
• Recommended in playbook-golang.md

Consequences

Positive

• High performance
• Easy middleware chaining
• Route grouping supports module architecture
• Good ecosystem support

Negative

• Additional dependency (though lightweight)
• Slight learning curve for developers unfamiliar with Gin

Implementation Notes

• Install: go get github.com/gin-gonic/gin@v1.9.1
• Create router in internal/server/server.go
• Use route groups for module isolation: r.Group("/api/v1/blog")
• Add middleware stack: logging, recovery, metrics, auth (later)
• Support graceful shutdown via fx lifecycle