Blueprint

Blueprint is a modular Go framework for building web applications and services. It gives you an application container with graceful shutdown, configuration, structured logging, a Gin-based HTTP server with security middleware and sessions, typed database repositories, and providers for messaging, storage, authentication and observability.

Install only what you use

The core module holds the container, configuration, logging, the database layer (dbx, db) and utilities. Each provider is a separate Go module, so an application only pulls in the dependencies of the providers it imports:

go get github.com/oddbit-project/blueprint                        # core
go get github.com/oddbit-project/blueprint/provider/httpserver     # HTTP server
go get github.com/oddbit-project/blueprint/provider/pgsql          # PostgreSQL driver

Area	Modules (github.com/oddbit-project/blueprint/provider/...)
HTTP	httpserver
Databases	pgsql, sqlite, clickhouse
Messaging	franz (Kafka), kafka (legacy), mqtt, nats
Storage & cache	redis, etcd, s3
Authentication	jwtprovider, hmacprovider, htpasswd
Observability	metrics, prometheus
Email	smtp

TLS, the key-value store interface and the rate limiter live in the core module (provider/tls, provider/kv, provider/ratelimiter).

A minimal application

An HTTP server run by the application container, which stops it cleanly on SIGINT/SIGTERM:

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/oddbit-project/blueprint"
    "github.com/oddbit-project/blueprint/log"
    "github.com/oddbit-project/blueprint/provider/httpserver"
    "github.com/oddbit-project/blueprint/utils"
)

func main() {
    utils.PanicOnError(log.Configure(log.NewDefaultConfig()))
    logger := log.New("app")

    app := blueprint.NewContainer(nil)

    cfg := httpserver.NewServerConfig()
    cfg.Host = "localhost"
    cfg.Port = 8080
    server, err := cfg.NewServer(logger)
    app.AbortFatal(err)

    server.Route().GET("/hello", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "hello"})
    })

    // runs on shutdown, after the application context is cancelled; ShutdownContext
    // gives the server time to finish requests in flight
    blueprint.RegisterDestructor(func() error {
        return server.Shutdown(blueprint.ShutdownContext())
    })

    app.Run(func(any) error {
        go func() {
            app.AbortFatal(server.Start())
        }()
        return nil
    })
}

A fuller version reading its configuration from a JSON file is in samples/application; the samples directory has runnable programs for most providers.

Where to go next

Section	What's there
Getting Started	Application container, configuration, logging
Database	Overview: dbx repositories, the gohan query builder, migrations, drivers, and the db → dbx migration guide
HTTP Server	Server, routing and middleware, authentication, security headers and CSRF, sessions, validation
Security & Auth	Credentials, password hashing, TLS, JWT, HMAC, rate limiting
Integrations	Messaging (Franz/Kafka, MQTT, NATS), storage (Redis, etcd, S3), metrics, SMTP
Utilities	Periodic runner, batch writer, thread pool, helper packages