togo

README

togo

Go, the artisan way.

togo is an open-source, API-first application framework for the Go + sqlc + Atlas + GraphQL/OpenAPI + Next.js stack. It brings a Laravel-artisan-like developer experience to Go: a powerful CLI, code generators, a plugin marketplace, Supabase auth/dashboard by default, built-in Terraform deploys, and first-class Claude Code / MCP integration.

This repository is the microkernel — the thin core every togo app builds on. The kernel provides configuration, a priority-ordered hook/event bus, a plugin loader + registry, a database driver registry, and server bootstrap. Everything else (REST, GraphQL, auth, dashboard, resources) is a plugin installed by the CLI.

The togo organization

Repo	Role
togo	Microkernel (this repo)
cli	The togo binary — generators, db, install, mcp, deploy
create-togo-app	Project template rendered by togo new
plugin-template	Starter for togo plugins
togo-mcp	MCP server exposing generators to AI agents

Quickstart

go install github.com/togo-framework/cli@latest   # installs the `togo` binary
togo new myapp && cd myapp
togo make:resource Post title:string body:text:nullable
togo generate          # sqlc + gqlgen + atlas + openapi
togo migrate && togo serve

Principles

• API-first — every resource is exposed over GraphQL and REST/OpenAPI 3.1.
• Everything is a plugin — the core is a microkernel; capabilities are installed.
• Generator-first — togo make:resource scaffolds across six targets from one manifest.
• Dynamic by default — connections, URLs, endpoints come from togo.yaml + .env + hooks.
• AI-native — projects ship .claude/ skills/agents + .mcp.json for Claude Code.

License

MIT

Documentation

Overview

Package togo is the microkernel of the togo framework. The kernel is deliberately thin: configuration, a hook/event bus, a plugin loader+registry, a database pool, and server bootstrap. Every capability — REST, GraphQL, auth, dashboard, resources — ships as a Plugin installed by the CLI and discovered here.

Index

• func Register(p Plugin)
• type Config
  • func LoadConfig() *Config
• type HookFunc
• type Hooks
  • func (h *Hooks) Fire(ctx context.Context, event string, payload any) error
  • func (h *Hooks) On(event string, priority int, fn HookFunc)
• type Kernel
  • func New() *Kernel
  • func (k *Kernel) Boot(ctx context.Context) error
  • func (k *Kernel) Close()
  • func (k *Kernel) DB(ctx context.Context) (*pgxpool.Pool, error)
  • func (k *Kernel) Plugins() []Plugin
  • func (k *Kernel) ReportError(ctx context.Context, err error)
  • func (k *Kernel) Serve(ctx context.Context) error
  • func (k *Kernel) Use(p Plugin) *Kernel
• type Plugin
  • func Discovered() []Plugin

Functions

func Register

func Register(p Plugin)

Register adds a plugin to the global auto-discovery registry.

Types

type Config

type Config struct {
	Addr        string
	DatabaseURL string
	GraphQLPath string
	RESTPath    string
	DocsPath    string
}

Config holds runtime configuration resolved from the environment, so connections/URLs/endpoints stay dynamic (togo convention: .env + hooks).

func LoadConfig

func LoadConfig() *Config

LoadConfig reads configuration from environment variables with sane defaults.

type HookFunc

type HookFunc func(ctx context.Context, payload any) error

HookFunc handles a fired event. Returning an error stops the chain.

type Hooks

type Hooks struct {
	// contains filtered or unexported fields
}

Hooks is a priority-ordered event bus for lifecycle events (resource CRUD, auth, plugin load). Listeners run in ascending priority (0 first).

func (*Hooks) Fire

func (h *Hooks) Fire(ctx context.Context, event string, payload any) error

Fire invokes every listener for an event in priority order, stopping on the first error.

func (*Hooks) On

func (h *Hooks) On(event string, priority int, fn HookFunc)

On registers a listener for an event at the given priority (0–100).

type Kernel

type Kernel struct {
	Config *Config
	Router chi.Router
	Hooks  *Hooks
	Log    *slog.Logger
	// contains filtered or unexported fields
}

Kernel is the shared runtime handed to every plugin and used by the app's entrypoint to mount REST/GraphQL and serve.

func New

func New() *Kernel

New constructs a kernel: loads config, logger, router (with recovery + request-logging middleware) and hook bus, and seeds the plugin list from auto-discovery (blank-imported plugin packages).

func (*Kernel) Boot

func (k *Kernel) Boot(ctx context.Context) error

Boot runs Register then Boot for every plugin in priority order. Safe to call once; subsequent calls are no-ops.

func (*Kernel) Close

func (k *Kernel) Close()

Close releases the DB pool.

func (*Kernel) DB

func (k *Kernel) DB(ctx context.Context) (*pgxpool.Pool, error)

DB returns a lazily-opened Postgres pool from Config.DatabaseURL. Any database driver is supported via the connection string; Postgres (pgx) is the default.

func (*Kernel) Plugins

func (k *Kernel) Plugins() []Plugin

Plugins returns the registered plugins sorted by boot priority.

func (*Kernel) ReportError

func (k *Kernel) ReportError(ctx context.Context, err error)

ReportError logs an error and fires the "error" hook so trackers (Sentry, GlitchTip, …) shipped as plugins can capture it. This is togo's central error reporting path — call it from anywhere with an error worth surfacing.

func (*Kernel) Serve

func (k *Kernel) Serve(ctx context.Context) error

Serve boots plugins and starts the HTTP server on Config.Addr.

func (*Kernel) Use

func (k *Kernel) Use(p Plugin) *Kernel

Use explicitly registers a plugin (in addition to auto-discovered ones).

type Plugin

type Plugin interface {
	// Name uniquely identifies the plugin (e.g. "rest-huma", "auth-supabase").
	Name() string
	// Priority controls boot order; lower boots first. Infrastructure plugins
	// (config, db) use low values; feature plugins use higher ones.
	Priority() int
	// Register binds services, config, and hooks. No I/O or route mounting here.
	Register(k *Kernel) error
	// Boot starts the plugin: mount routes, register schema, run migrations.
	Boot(ctx context.Context, k *Kernel) error
}

Plugin is the contract every togo capability implements. The runtime boots plugins in ascending Priority order (0–100), mirroring laravilt's ordered service-provider lifecycle.

func Discovered

func Discovered() []Plugin

Discovered returns a copy of the auto-registered plugins.