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) 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
	// 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, creates the router 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) 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.