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

• Constants
• func Providers() []string
• func Register(p Plugin)
• func RegisterProvider(p Provider)
• func RegisterProviderFunc(name string, priority int, fn func(*Kernel) error)
• 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) Dialect() orm.Dialect
  • func (k *Kernel) Get(key string) (any, bool)
  • func (k *Kernel) Plugins() []Plugin
  • func (k *Kernel) ReportError(ctx context.Context, err error)
  • func (k *Kernel) SQL(ctx context.Context) (*sql.DB, error)
  • func (k *Kernel) Serve(ctx context.Context) error
  • func (k *Kernel) Set(key string, v any)
  • func (k *Kernel) T(key string) string
  • func (k *Kernel) Use(p Plugin) *Kernel
• type Plugin
  • func Discovered() []Plugin
• type Provider

Constants

const (
	PriorityCore    = 0  // log
	PriorityService = 50 // cache, storage, realtime, i18n
	PriorityLate    = 90 // queue (depends on log)
)

Priority bands (providers pick their own; built-in feature packages use these).

Functions

func Providers

func Providers() []string

Providers returns the names of registered providers in run order.

func Register

func Register(p Plugin)

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

func RegisterProvider

func RegisterProvider(p Provider)

RegisterProvider registers a service provider globally (call from init()). Higher Priority runs later and wins.

func RegisterProviderFunc

func RegisterProviderFunc(name string, priority int, fn func(*Kernel) error)

RegisterProviderFunc registers a provider from a func.

Types

type Config

type Config struct {
	Addr        string
	DBDriver    string // database/sql driver name (default "sqlite"); providers register others
	DatabaseURL string
	GraphQLPath string
	RESTPath    string
	DocsPath    string
	Locale      string
	LocaleDir   string
	StorageDir  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. SQLite is the default driver — no external database needed to get started.

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
	Cache    cache.Cache
	Queue    queue.Queue
	Storage  storage.Storage
	Realtime realtime.Broker
	I18n     i18n.Translator
	// 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 handle.

func (*Kernel) Dialect

func (k *Kernel) Dialect() orm.Dialect

Dialect returns the ORM dialect for the configured driver.

func (*Kernel) Get

func (k *Kernel) Get(key string) (any, bool)

Get retrieves a service registered via Set.

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) SQL

func (k *Kernel) SQL(ctx context.Context) (*sql.DB, error)

SQL returns a lazily-opened database/sql handle using Config.DBDriver (default "sqlite"). Driver registration is the app's responsibility (blank-import the driver, or a DB provider plugin) — SQLite is core; Postgres/MySQL/etc. are provider plugins that register their driver and set DB_DRIVER.

func (*Kernel) Serve

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

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

func (*Kernel) Set

func (k *Kernel) Set(key string, v any)

Set stores an arbitrary service in the kernel container, so any plugin can inject capabilities the core doesn't know about (e.g. auth).

func (*Kernel) T

func (k *Kernel) T(key string) string

T translates a key in the configured locale (trans() equivalent).

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.

type Provider

type Provider interface {
	ProviderName() string
	ProviderPriority() int
	Provide(k *Kernel) error
}

Provider contributes a service to the kernel. The kernel core is tiny (config, router, hooks, log, plugin lifecycle). Every OTHER capability — cache, queue, storage, realtime, i18n, db drivers — lives in its own provider package under togo/providers/* and self-registers in init(). A project opts into features by blank-importing those packages (chosen at `togo new`), so the core hard-codes nothing and any plugin can inject/override a provider globally.