Overview
github.com/gp-system/framework is a thin chassis on top of 14 standalone Go modules: each module (error handling, config loading, the database layer, the async stack, auth, mail, notifications, storage, telemetry, ...) is its own repository and its own go.mod, versioned independently of the rest, usable on its own in any Go program. What's left in the framework is a scaffolding CLI and four runtime chassis packages that compose those modules into a running service.
What's in the framework
| Package | What it does |
|---|---|
app | the signal-driven graceful-shutdown process lifecycle every other chassis package sits on: drain, closers (LIFO), telemetry flush |
server | the chi-based HTTP chassis: Config, Run, RegisterFunc, StrictValidator |
worker | the background-processing chassis: asynq server + outbox relay + schedule runner, one binary |
realtime | the centrifuge-based WebSocket/SSE gateway that pushes notifications to connected clients |
cmd/gpsystem | the scaffolding CLI: new project, new module, add surface, add handler, and the rest of the generators |
Two more framework-generated (not standalone-module) topics live alongside them, because they don't have a module home of their own: migrations (the cmd/migrate convention, built on dbx/pg) and social login (OAuth2 provider wiring generated on top of the auth module).
A framework that composes, not wraps
The framework does not hide the modules behind an interface, a container or a facade: it composes them. server.Run, worker.Run and realtime.Run each wire a chosen subset of the 14 modules into a runnable process, and the CLI generates that wiring so you rarely write it by hand, but the wiring itself stays plain, explicit Go code in your main.go. This is the same "centralize, don't abstract" principle the whole project is built on: raw types from the underlying libraries (chi.Router, *asynq.Task, centrifuge.Node) are visible in the framework's own API rather than wrapped away. The Architecture page has the full module map this thin layer sits on top of.
Install
For the CLI:
go install github.com/gp-system/framework/cmd/gpsystem@latest
For using the chassis packages (app, server, worker, realtime) in a project:
go get github.com/gp-system/framework@latest
Scaffolding a new project with gpsystem new project adds this dependency to the generated go.mod automatically, so you rarely run the second command by hand; it matters mainly if you're wiring a chassis package into an existing, hand-rolled project.
Why use the framework at all
Nothing here is required. Every one of the 14 modules works standalone, in any Go program, with no framework installed: dbx/pg, auth, queue, and the rest have zero dependency on github.com/gp-system/framework. The framework exists to save you from hand-wiring lifecycle, telemetry bootstrap, HTTP routing, and worker/task dispatch yourself, and from writing the TypeSpec→OpenAPI→server-code generators that turn a spec into a runnable surface. If you don't want that (say, you're bolting one module onto an existing service), skip the framework and import the modules you need directly; see Getting started for how the pieces fit together either way.
Where to next
- Application lifecycle: the shared
app.Runskeleton. - Server: the HTTP chassis.
- Worker: the background-processing chassis.
- Realtime: the WebSocket/SSE gateway.
- Migrations: the
cmd/migrateconvention. - Social login: OAuth2 provider wiring.
- CLI overview: the scaffolding commands.