Architecture

The library half of gpsystem is not a monolithic framework but a collection of Go packages organized into eight capability groups. Each package is usable, and understandable, on its own; this page gives you the map: what lives where, what builds on what, and the principle the whole thing is assembled by. Its role in this sense is a microservice chassis (Richardson): cross-cutting infrastructure (lifecycle, HTTP layer, telemetry, error model) that you import as a library. There is no container and no facade invisibly stitching the parts together: whatever connects, connects in your main.go, in explicit code.

Package map

Foundations

HTTP layer

Security

Database & storage

Async processing

Observability

Mail

Tooling

The generators and templates live in the kit's internal/. Consumer projects only ever see their output, plus the TypeSpec→OpenAPI→server-code pipeline.

The lifecycle of a service

The server package itself only provides server.Config; the process lifecycle lives in the app package, and the engines (fiberx.Run and chix.Run) delegate to the same app.Run. The sequence is therefore identical regardless of engine:

The worker chassis (worker.Run) is built on exactly the same app.Run: instead of HTTP, it shuts down an asynq server, the outbox relay and the schedule runner in the same order. The Application lifecycle page describes the internals in detail.

Options

The two engines' option sets mirror each other:

Centralize, don't abstract

The kit's design principle: access to external dependencies is concentrated in one kit package each, but their types flow freely through the public API. There is no "gpsystem router interface" and no "gpsystem query abstraction". The signatures openly carry the third-party types:

// server/fiberx: register receives a *fiber.App
func Run(ctx context.Context, cfg server.Config, register func(app *fiber.App) error, opts ...Option) error

// server/chix: register receives a chi.Router
func Run(ctx context.Context, cfg server.Config, register func(r chi.Router) error, opts ...Option) error

// dbx/pg: hands you a raw pgxpool.Pool and pgx types
func MustNewPool(ctx context.Context, cfg dbx.Config) *pgxpool.Pool
func (d *DB) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)

// dbx/bunx: hands you a *bun.DB over the same pool
func Open(pool *pgxpool.Pool) *bun.DB

// worker: the escape hatch hands you raw asynq
func WithMux(fn func(mux *asynq.ServeMux)) Option

This is deliberate. The Fiber, chi, pgx, bun and asynq documentation, Stack Overflow answers and upstream sample code all apply to your project verbatim. You are not learning a kit-specific wrapper API, you are learning the Go ecosystem's established libraries, curated in one place. The generated project, in this sense, is a service template (Richardson): runnable scaffolding you're handed and that's yours from that point on, not a runtime layer living above your app.

The three deliberate exceptions

In three places the kit does hide the dependency behind an interface, each time for a stated reason:

• storage.Store hides the AWS SDK: your app code should not have to import the AWS SDK to upload a file, and the implementation (AWS, MinIO, RustFS) is swappable via env configuration.
• sentryx wraps sentry-go: Sentry is switchable from the environment (SENTRY_DSN empty = fully off, every hook a no-op), and nothing outside the telemetry facade imports it: a consumer of otelx alone (a CLI, a migration tool) never even links sentry-go into its binary.
• mail's Mailer interface fronts go-mail and mjml-go, so tests can swap in an in-memory mailer.

Swappable and omittable parts

The other side of centralizing is that the parts don't fuse together:

• dbx/dbx/pg work without server: a CLI tool or the cmd/migrate binary uses the same pool and transactor with no HTTP layer.
• Sentry is fully omittable: with SENTRY_DSN empty the integration is dead code.
• OTel runs without exporters in dev mode (OTEL_DEV_MODE=true), or is skipped entirely with WithoutTelemetry().
• The engine is chosen per project (new project --engine fiber|chi, recorded in gpsystem.yaml); business code (handler, service, repository) is engine-independent, only the entry point, register.go and the generated gen/ package differ.
• The DB implementation is decided by import: a repository imports dbx/pg (SQL) or dbx/bunx (query builder); the dbx.Transactor interface and the context-carried transaction are shared.

Where the line is

The kit deliberately doesn't introduce a few things that would tip it toward framework territory (Fowler: Inversion of Control): no Module interface that a bootstrap discovers and orders; no kit-owned lifecycle hook inside business code; no runtime DI container resolving the dependency graph for you. If any of those showed up, the honest name from that point on would be "framework," not "toolkit"; this is a deliberate guardrail, not an accidental omission.

Shared code: a decision ladder

Every project eventually needs code used by more than one surface, or more than one module. Where it goes depends on how widely it's actually shared. It's a decision ladder, not a single rule:

A worked example of the whole ladder: the kit's mail/mail/smtp packages are the transport (kit-level: every project needs an SMTP client). A module's recipient list and email templates are business content (module-level: internal/modules/contact/mail/). Composed MAIL_* config lives in internal/platform/config. See Mail for the full example.

Where to next

• The shop sample app shows how all of this composes into a project: entry points, worker, events.
• Application lifecycle opens up the inside of app.Run.
• Error model follows the errs → httperr chain end to end.
• Codegen pipeline takes you from TypeSpec to generated server code.
• Design patterns catalogs the recurring design patterns across the packages above, with code and external sources.
• External dependencies lists every underlying library with its version and official documentation.