XRAPH/Work/Go framework
Go · since 2025

Forge

An opinionated Go framework: DI container, router, layered config, health checks, migrations and ordered shutdown, plus around twenty extensions you switch on when you need them: Postgres and Mongo, Kafka, MQTT, gRPC, GraphQL, WebRTC, Raft consensus, MCP. `forge init` scaffolds, `forge dev` hot-reloads. Everything else at xraph is built on it.

Language
Go
Category
Go framework
Since
2025
Stars
7
In production
03+
Repository Docs
01

Highlights

3 claims
H.01
Twentyextensions
Shipping in-tree

AI, auth, cache, consensus, database, events, GraphQL, gRPC, Kafka, MQTT, queue, search, storage and streaming. Every one registers the same way, so learning the first teaches you the rest.

H.02
Onemethod
The extension interface

Migrations, health and route registration are optional interfaces found by type assertion. The first version required seven methods, and most implementations satisfied five of them with empty bodies.

H.03
Bootorder
Computed from the graph

Services declare what they depend on and the container derives a start order, then reverses it for shutdown. A failed start halts the boot naming the dependency it needed.

03

What it does

5 entries

The decisions every backend service makes before it serves a request, made once and applied the same way in every service that adopts the framework.

03.1
Vessel

Dependency injection

Generic type-safe resolution with uber/dig-style constructor injection, and circular-dependency detection at registration time rather than at first resolve. It is the same container every extension registers into, so a service and a framework module look identical to it.

Type-safeCycle detection
Injection reference
03.2
Lifecycle

Lifecycle as a graph

Services declare what they depend on. The container computes a start order from the graph and reverses it for shutdown, so nothing is torn down while something still needs it. A failed start halts the boot naming the dependency it needed, which is the error message I wanted every time I wrote this by hand.

Ordered startReverse shutdown
Lifecycle reference
03.3
Confy

Configuration

YAML, JSON or TOML with environment overrides and hot reload. Auto-discovery walks up the tree to find a monorepo’s config, which removes the one piece of per-service boilerplate that never survived a directory move.

Hot reloadMonorepo aware
Confy reference
03.4
Health

Health without a registry

Any service implementing the interface appears at /_/health with no list to maintain. The registry that used to hold that list was the thing most often out of date in the services this replaced.

/_/health
Health reference
03.5
Telemetry

Observability from the first handler

Structured logs, Prometheus at /_/metrics and trace propagation are mounted before any application code runs, so there is no version of the service that exists without them.

PrometheusTrace propagation
Observability reference
05

Anatomy

4 modules
01

Container

Type-safe dependency injection with cycle detection at registration.

02

Lifecycle

Services declare dependencies; start and shutdown order is computed, not written.

03

Configuration

Layered sources with typed access and hot reload.

04

Extensions

Everything beyond the core is opt-in behind one interface.

06

Why it exists

Design notes

#What it is

Forge is the Go framework the rest of this stack is built on. It bundles the decisions every backend service makes before it serves a request, covering dependency injection, routing, configuration, health checks, migrations, observability and shutdown ordering, then puts everything else behind an extension interface you opt into.

The premise is that those decisions are not interesting and I had made all of them before, slightly differently each time. Deciding them once and living with the consequences across every service turned out to be worth more than the flexibility I gave up.

#The core

  • Dependency injection through Vessel: generic type-safe resolution, uber/dig-style constructor injection, and circular-dependency detection at registration time.
  • Lifecycle as a graph. Services declare what they depend on; the container computes a start order and reverses it for shutdown. A failed start halts the boot naming the dependency it needed.
  • Configuration through Confy: YAML, JSON or TOML, environment overrides, hot reload, and auto-discovery that walks up the tree to find a monorepo's config.
  • Health discovered rather than registered. Any service implementing the interface shows up at /_/health without a list to maintain.
  • Observability from the first handler: structured logs, Prometheus at /_/metrics, and trace propagation.

#Extensions

Around twenty ship in-tree, each with the same registration and lifecycle shape, so learning one teaches you the others: AI (LLM integration, agents, inference), Auth (OAuth, JWT, SAML), Cache (Redis, Memcached, in-memory), Consensus (Raft), Database (Postgres, MySQL, SQLite, MongoDB), Events (bus and sourcing), GraphQL, gRPC with reflection, HLS, Kafka, MCP, MQTT, oRPC, Queue, Search (Elasticsearch, Typesense), Storage (S3, GCS, local), Streaming (WebSocket, SSE, WebRTC).

The extension interface has one required method. Anything else, including migrations, health and route registration, is an optional interface detected by type assertion. That was a correction: the first version required seven methods and most implementations satisfied five of them with empty bodies.

#The CLI

forge init scaffolds a project from a template. forge dev runs it with hot reload. There is code generation for handlers, controllers and services, a migration runner with versioning and cross-module ordering, and a test runner with coverage.

#Where it fits

The industrial work I do runs on it, with each capability as a separate extension so a deployment only starts the parts it uses. Bastion, Authsome, Cortex, Weave, Warden, Vault, Keysmith, Chronicle, Ledger, Dispatch and Relay all ship a Forge extension alongside a standalone constructor.

The standalone path is not a courtesy. If those libraries only worked inside Forge, Forge's assumptions would leak into their designs without anything failing to warn me.

07

Signals

GitHub
Stars
7
Language
Go
Since
2025
Adopters
03