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 unified marketplace of plugins, AI agents, skills, MCP tools and UI components, Supabase auth/dashboard by default, a fast togo deploy, 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
mcp	MCP server exposing generators to AI agents
claude-togo	The togo Claude Code plugin — agents, skills, rules, hooks + auto-wired MCP

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 migrate + OpenAPI
togo serve
togo install claude    # optional: add the togo AI agent team to Claude Code

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 + a .mcp.json wired to both the local and the web MCP; togo install claude adds the 15-agent togo team to Claude Code.

License

MIT

---

💎 Premium sponsors

togo is proudly sponsored by ID8 Media and One Studio.

      

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 RegisterDialect(driver string, d Dialect)
• func RegisterProvider(p Provider)
• func RegisterProviderFunc(name string, priority int, fn func(*Kernel) error)
• type Broker
• type Cache
• type Config
  • func LoadConfig() *Config
• type Dialect
  • func DialectFor(driver string) Dialect
• 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() Dialect
  • func (k *Kernel) Get(key string) (any, bool)
  • func (k *Kernel) Handler() http.Handler
  • 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
  • func (k *Kernel) UseMiddleware(m ...func(http.Handler) http.Handler)
• type Plugin
  • func Discovered() []Plugin
• type Provider
• type Queue
• type QueueHandler
• type Storage
• type Translator

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 RegisterDialect

func RegisterDialect(driver string, d Dialect)

RegisterDialect registers the SQL dialect for a database/sql driver name. DB driver plugins call this from init() for drivers the kernel doesn't ship.

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 Broker

type Broker interface {
	Publish(event, data string)
	Handler() http.HandlerFunc
}

Broker fans out server-push (realtime) messages to connected clients.

type Cache

type Cache interface {
	Get(key string) (any, bool)
	Set(key string, value any, ttl time.Duration)
	Delete(key string)
}

Cache is the key/value cache contract.

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 Dialect

type Dialect struct {
	Placeholder func(n int) string // 1-based positional placeholder
	ILike       string             // case-insensitive LIKE operator
}

Dialect captures the per-driver SQL differences the ORM needs. It lives in the kernel (not the orm plugin) so the kernel can expose Kernel.Dialect() without depending on the orm package — the orm plugin consumes togo.Dialect.

func DialectFor

func DialectFor(driver string) Dialect

DialectFor returns the dialect registered for a database/sql driver name, falling back to the SQLite dialect for unknown drivers.

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
	Queue    Queue
	Storage  Storage
	Realtime Broker
	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() 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) Handler

func (k *Kernel) Handler() http.Handler

Handler returns the kernel's HTTP handler: the router wrapped by every middleware registered via UseMiddleware (first-registered is outermost).

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

func (*Kernel) UseMiddleware

func (k *Kernel) UseMiddleware(m ...func(http.Handler) http.Handler)

UseMiddleware registers global HTTP middleware that wraps the whole router at serve time (outermost first-registered). Unlike chi's Router.Use — which a plugin can only call before ANY route is mounted — this can be called by any number of plugins at any provider priority: the middleware is applied as an outer wrapper in Handler(), after all providers have run. Prefer this over k.Router.Use for cross-cutting middleware (CORS, auth context, tracing).

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.

type Queue

type Queue interface {
	Handle(name string, h QueueHandler)
	Dispatch(ctx context.Context, name string, payload any) error
}

Queue dispatches named jobs to registered handlers.

type QueueHandler

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

QueueHandler processes a dispatched job payload.

type Storage

type Storage interface {
	Put(path string, data []byte) error
	Get(path string) ([]byte, error)
	Delete(path string) error
	Path(path string) string
}

Storage is the blob storage contract.

type Translator

type Translator interface {
	T(locale, key string) string
}

Translator resolves a key for a locale (trans()).