gogogofullstacktemplate

package module
v0.71.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 0 Imported by: 0

README

gogogo

gogogo

The foundation is done. Your agent ships the product.

Landing page · Docs · Live demo · Releases · CI


A complete Go product — backend, frontend, database, auth, jobs, realtime, durable workflows and offline writes — that compiles to one binary. Every slice is code you own and can delete; every heavy dependency has an off switch. A CLI and an MCP server let an agent change the tree and prove the build instead of guessing at it.

Not a framework. Nothing is versioned out from under you: the scaffold copies the tree, and git is the update path.

Quick start

curl -sSfL https://raw.githubusercontent.com/calionauta/gogogo/master/install.sh | sh -s -- --run
# Open http://localhost:8080  ·  demo1@demo.app / demo1234456

Manual: gh repo create my-app --template calionauta/gogogo --clone, then make rename NAME=my-app, make dev.

Try it live

Todo & Whiteboard https://gogogo.calionauta.com/
DagNats console https://gogogo.calionauta.com/dagnats/

What ships

One row per thing you get. The opt out column is the runtime switch — flip it and the binary still builds.

Capability Technology Opt out
Web UI Templ + Datastar (SSE), DaisyUI palettes —
Persistence Turso/SQLite via sqlc —
Auth Owned argon2id sessions, magic link, TOTP —
Access control Casbin v3 policy over users.role RBAC_ENABLED=false (prod)
Background jobs goqite + retry, queue-backed —
Durable workflows DagNats over NATS JetStream DAGNATS_ENABLED=false
Realtime fan-out SSE Hub + NATS JetStream NATS_ENABLED=false
Offline writes Write-ahead outbox, app-shell cache, leaf node OFFLINE_SYNC_ENABLED=false
Collaboration Loro CRDT (notes, whiteboard) delete by hand
Entity actors GoAkt grains (rooms, presence) GOAKT_ENABLED=false
AI GoAI (any provider) + Genkit flows GOAI_API_KEY unset
Metering Credits + BYOK CREDITS_ENABLED=false
Search Own layers: substring, fuzzy, BM25 delete by hand
Admin /config: audit trail, users, runtime switches —

Details per row, with the removal class of each unit and its exact removal path: docs/features.

Stack

language   Go 1.27
frontend   Templ · Datastar (SSE) · Tailwind v4 + DaisyUI v5
data       Turso/SQLite · sqlc · DB-backed sessions
security   argon2id · Casbin RBAC · security_events audit trail
async      goqite · DagNats · NATS JetStream · GoAkt · Loro CRDT
ai         GoAI (any provider) · Genkit flows · jev-like classifier seam
shipping   one binary · make build · env-var opt-outs

One make build compiles all of it: no build tags, no second boot path, no matrix, no runtime CSS or JS build, no service to operate.

App shapes: one template, five products

The same cmd/web binary ships as a full product, a web app, an API-only backend, or the server behind the desktop and mobile shells. APP_SHAPE (or the committed .gogogo/shape.yml record) picks the entrypoints and the surfaces.

APP_SHAPE=api make build   # one binary; page routes answer 404

api prunes page routes at mount, so the 404 comes from the route tree, not from a handler that runs and refuses. /api, /health and the static assets keep working. Enum, record and the check-shape gate: docs/shape.md.

Recipes: read one, then own one

A recipe is a working slice — pages, handlers, tables, jobs, policy rows — not a package you depend on. Two modes, and the difference is a receipt:

Read (default) Own (explicit)
recipe source <id> prints the code recipe install <id> copies it in
No receipt, no copy, no update debt Receipt at .recipes/<id>.yml
Adapt the pattern into your own slice Your edits survive: pristine hashes + git merge
Checked, not trusted recipe check scores it; recipe test runs its tests
What it declares routes, tables, jobs, slots, metrics, panel
Reviewed versions catalog/ — bytes, not names
What to read first catalog/reference.yml
What is installed here go run ./cmd/gogogo recipe list

A fresh scaffold drops the demo slices (--recipes none is the default): chat, kiosk, notes, review, room, whiteboard. --recipes all keeps them, --recipes <ids> drops exactly those. todo is removable on the same terms but stays today: internal/desktopboot (the native shells' shared boot), cmd/gui and two test files import it, and the plan prints that list rather than removing a package something still uses. Read one with recipe source; copy one with recipe install when you want it owned.

Languages are one tracked record, not a flag per command:

go run ./cmd/gogogo locales            # what this product ships, and why
go run ./cmd/gogogo locales --set en,pt-BR

new feature seeds one catalog per recorded tag, recipe check grades coverage against it, and make check-locales fails a branch where a recipe translates one shipped language but not another. A metric label is translated in the declaration's own translations: block (it is data, so it cannot live in the app catalog), and en is the fallback spelling — never a required entry.

Contract: skills/gogogo-recipe-authoring · Taxonomy: docs/scope-taxonomy.

For AI agents

  • llms.txt — what to read per task.
  • go run ./cmd/gogogo advise|doctor|generate|shape|recipe|export|new feature — the same evolution engine the MCP server (cmd/gogogo-mcp) exposes.
  • Those tools build and evolve a checkout. A product's users and their agents call the running server (POST /api/ext/invoke) under session and RBAC, never the installer MCP. See docs/mcp.md.

Commands

make dev       # live reload
make build     # one binary
make ci-local  # the full gate (= CI)
make site      # rebuild the docs site

More: getting-started.

License

MIT — see LICENSE. Feedback and PRs welcome.

Documentation

Overview

Package gogogofullstacktemplate is the module root.

This file exists so the module root package is never empty: some Go toolchains treat an empty root package as a hard "no Go files" error when running `go test ./...`, which aborts the whole test gate. With this file present the root reports "[no test files]" instead.

The package name intentionally has no underscore: golangci-lint's revive linter rejects underscore-separated package names, and the module import path (github.com/calionauta/gogogo) is independent of the package name, so renaming is safe.

Directories

Path Synopsis
Package catalog is the reviewed set of recipes this template can install — entries plus the one list of which entries it recommends.
Package catalog is the reviewed set of recipes this template can install — entries plus the one list of which entries it recommends.
cmd
bump-go-toolchain command
Bump the pinned Go toolchain across every file that names it.
Bump the pinned Go toolchain across every file that names it.
check-classes command
Stylesheet reading for the repo class gate.
Stylesheet reading for the repo class gate.
check-docs command
Bare repo paths in the index pages.
Bare repo paths in the index pages.
check-domains command
Command check-domains is the gate for the per-slice domain cards.
Command check-domains is the gate for the per-slice domain cards.
check-flatdeps command
Flat-stack dependency guard (framework-free, one SQLite driver, no cross-feature domain imports, owned sql.Open sites)
Flat-stack dependency guard (framework-free, one SQLite driver, no cross-feature domain imports, owned sql.Open sites)
check-product-boundary command
Command check-product-boundary is the "not a framework" tripwire.
Command check-product-boundary is the "not a framework" tripwire.
check-prompts command
Command check-prompts is the deterministic half of the prompt-as-data rule.
Command check-prompts is the deterministic half of the prompt-as-data rule.
check-secrets-env command
Secrets-env site guard (secret env reads stay on the rails)
Secrets-env site guard (secret env reads stay on the rails)
check-shape command
Command check-shape is the gate for the app-shape record.
Command check-shape is the gate for the app-shape record.
check-skill-frontmatter command
Reference links inside skills (part of the skill-frontmatter gate).
Reference links inside skills (part of the skill-frontmatter gate).
check-test-value command
Test-value detection: helpers that can fail, and the two verdicts.
Test-value detection: helpers that can fail, and the two verdicts.
check-typed-states command
Command check-typed-states is the "no stringly-typed state" gate.
Command check-typed-states is the "no stringly-typed state" gate.
desktop command
Command desktop builds the Wails v3 native app shell around the exact same Go backend the web app uses (goqite queue + handlers + the flat chi router).
Command desktop builds the Wails v3 native app shell around the exact same Go backend the web app uses (goqite queue + handlers + the flat chi router).
gogogo command
Command gogogo scaffolds a new project from gogogo.
Command gogogo scaffolds a new project from gogogo.
gogogo-mcp command
MCP tool: desktop/mobile build prerequisites.
MCP tool: desktop/mobile build prerequisites.
gui command
Entitlement gate for the native window.
Entitlement gate for the native window.
license command
Command license mints and inspects the offline entitlement tokens verified by internal/license.
Command license mints and inspects the offline entitlement tokens verified by internal/license.
mygo command
Command mygo is the MyGo peer shell over the exact same flat stack the web app uses.
Command mygo is the MyGo peer shell over the exact same flat stack the web app uses.
prompt-eval command
Command prompt-eval reports what a candidate prompt tree changes.
Command prompt-eval reports what a candidate prompt tree changes.
ui-registry command
The UI registry reader (agent-facing).
The UI registry reader (agent-facing).
web command
GoAkt lifecycle (room actor system)
GoAkt lifecycle (room actor system)
Single source of truth for the optional Chat decision router (JEV_ROUTER_* env).
Single source of truth for the optional Chat decision router (JEV_ROUTER_* env).
features
account/components
templ: version: v0.3.1070
templ: version: v0.3.1070
account/handlers
Authenticated account security page.
Authenticated account security page.
app
Package app provides the cross-cutting "application core" pattern for projects built on top of gogogo.
Package app provides the cross-cutting "application core" pattern for projects built on top of gogogo.
authviews
templ: version: v0.3.1070
templ: version: v0.3.1070
chat/components
Chat page signals.
Chat page signals.
chat/handlers
HTTP chat slice (conversation demo)
HTTP chat slice (conversation demo)
chat/store
Chat demo store (in-memory)
Chat demo store (in-memory)
config/components
Auth-gated read-only /config view (masked secrets)
Auth-gated read-only /config view (masked secrets)
config/handlers
HTTP config view (admin-only, secrets masked)
HTTP config view (admin-only, secrets masked)
credits
The credits Service implements the llm.Biller seam so every Chat/ChatStream call (the internal/llm choke point) is metered.
The credits Service implements the llm.Biller seam so every Chat/ChatStream call (the internal/llm choke point) is metered.
credits/handlers
HTTP credits slice (AI credits + BYOK)
HTTP credits slice (AI credits + BYOK)
dashboard/handlers
HTTP dashboard page: the host for the `dashboard.card` slot.
HTTP dashboard page: the host for the `dashboard.card` slot.
genui/components
The action catalog: what a model-authored component may offer to DO in this app.
The action catalog: what a model-authored component may offer to DO in this app.
graph
System panorama graph (canvas).
System panorama graph (canvas).
graph/handlers
graph feature (scaffolded by `gogogo new`)
graph feature (scaffolded by `gogogo new`)
graph/native
Native (gogpu/ui) twin of the graph presence source: one room as a list.
Native (gogpu/ui) twin of the graph presence source: one room as a list.
kiosk
The decision engine: a jev-like classifier settles the order.
The decision engine: a jev-like classifier settles the order.
kiosk/components
The menu as a catalogue: what the counter sells, rendered as choices.
The menu as a catalogue: what the counter sells, rendered as choices.
kiosk/handlers
The kiosk recipe's HTTP slice: one page, two POSTs.
The kiosk recipe's HTTP slice: one page, two POSTs.
kiosk/service
The kiosk recipe's write half.
The kiosk recipe's write half.
license/handlers
Activation page for the distribution gate.
Activation page for the distribution gate.
notes
Shared notes (server-owned Loro Text) Embedded static assets for the notes feature: notes.js (textarea op wiring + SSE stream).
Shared notes (server-owned Loro Text) Embedded static assets for the notes feature: notes.js (textarea op wiring + SSE stream).
notes/components
templ: version: v0.3.1070
templ: version: v0.3.1070
notes/handlers
HTTP notes slice (server-owned Loro Text)
HTTP notes slice (server-owned Loro Text)
notifications
Notifications: in-process inbox change fan-out.
Notifications: in-process inbox change fan-out.
notifications/components
Notifications page helpers.
Notifications page helpers.
notifications/handlers
Notifications: the inbox page and its actions.
Notifications: the inbox page and its actions.
onboarding
DagNats onboarding workflow (durable run + stepper fan-out)
DagNats onboarding workflow (durable run + stepper fan-out)
review/components
Review loop page signals.
Review loop page signals.
review/handlers
Review loop (Genkit + goai + jev judge).
Review loop (Genkit + goai + jev judge).
room/handlers
HTTP room slice (GoAkt presence demo)
HTTP room slice (GoAkt presence demo)
sounds
templ: version: v0.3.1070
templ: version: v0.3.1070
todo
Todo event bus (one publish, adapters per transport)
Todo event bus (one publish, adapters per transport)
todo/components
The todo list's Datastar wiring, in the slice that owns it.
The todo list's Datastar wiring, in the slice that owns it.
todo/handlers
Todo NATS bridge (cross-instance convergence)
Todo NATS bridge (cross-instance convergence)
todo/service
Transport-free todo domain service — one rule, every frontend.
Transport-free todo domain service — one rule, every frontend.
whiteboard
Collaborative whiteboard (Loro CRDT canvas) Embedded static assets for the whiteboard feature: rough.min.js (Rough.js hand-drawn canvas rendering) and whiteboard.js (Datastar/SSE canvas wiring).
Collaborative whiteboard (Loro CRDT canvas) Embedded static assets for the whiteboard feature: rough.min.js (Rough.js hand-drawn canvas rendering) and whiteboard.js (Datastar/SSE canvas wiring).
whiteboard/handlers
HTTP whiteboard slice (Loro CRDT canvas)
HTTP whiteboard slice (Loro CRDT canvas)
internal
analytics
Analytics as a provider seam, not a vendor script in every template.
Analytics as a provider seam, not a vendor script in every template.
auth
Account-management operations shared by the JSON API and the /account page.
Account-management operations shared by the JSON API and the /account page.
authpages
The app's sign-in surfaces: login, signup, logout and the recovery forms.
The app's sign-in surfaces: login, signup, logout and the recovery forms.
capabilities
Capability registry: single source of truth for ids, kinds, runtime switches, and owned paths (consumed by cmd/gogogo, docs, and --help).
Capability registry: single source of truth for ids, kinds, runtime switches, and owned paths (consumed by cmd/gogogo, docs, and --help).
cloudcfg
Local cloud-connection settings (sync.json, 0600).
Local cloud-connection settings (sync.json, 0600).
collab
Loro CRDT + DocStore + sync workers + presence To remove: delete internal/collab/ + features/whiteboard/ and drop the whiteboard roots from buildChiMux in internal/server/chi.go.
Loro CRDT + DocStore + sync workers + presence To remove: delete internal/collab/ + features/whiteboard/ and drop the whiteboard roots from buildChiMux in internal/server/chi.go.
components
templ: version: v0.3.1070
templ: version: v0.3.1070
dagnats
DagNats durable workflow engine To remove: delete internal/dagnats/, cmd/web/dagnats.go, features/onboarding/, features/todo/handlers/onboarding.go and the bootOnboarding call in internal/server/chi.go.
DagNats durable workflow engine To remove: delete internal/dagnats/, cmd/web/dagnats.go, features/onboarding/, features/todo/handlers/onboarding.go and the bootOnboarding call in internal/server/chi.go.
datastar
Datastar rendering helpers (RenderAndPatch, MergeSignals)
Datastar rendering helpers (RenderAndPatch, MergeSignals)
db
Application database: the one place that knows the Turso Database connection string, file layout, and pragmas.
Application database: the one place that knows the Turso Database connection string, file layout, and pragmas.
dbschema
ID and timestamp helpers shared by every store.
ID and timestamp helpers shared by every store.
delivery
Delivery transport seam.
Delivery transport seam.
delivery/notify
Delivery transport: notify (an external delivery engine).
Delivery transport: notify (an external delivery engine).
demo
Demo-user seed for fresh installs
Demo-user seed for fresh installs
desktopboot
Shared desktop/gui boot helpers — one bootstrap, every native shell.
Shared desktop/gui boot helpers — one bootstrap, every native shell.
events
Domain events: the one seam hooks and analytics subscribe to.
Domain events: the one seam hooks and analytics subscribe to.
goakt
GoAkt document-presence actor (whiteboard/notes roster).
GoAkt document-presence actor (whiteboard/notes roster).
graph
Graph panorama: reads the installed system (capabilities + recipes) and answers with a node/edge document the canvas can draw.
Graph panorama: reads the installed system (capabilities + recipes) and answers with a node/edge document the canvas can draw.
hostgate
Host gate for heavy Go tests (skip on saturated boxes)
Host gate for heavy Go tests (skip on saturated boxes)
i18n
Localization seam: embedded JSON catalogs plus resolution.
Localization seam: embedded JSON catalogs plus resolution.
icon
Vendored SVG path catalog for the Icon component.
Vendored SVG path catalog for the Icon component.
installer
Installer engine: opinionated stack guidance, reads nothing, changes nothing
Installer engine: opinionated stack guidance, reads nothing, changes nothing
instance
Stable instance identity (durable names + event origin)
Stable instance identity (durable names + event origin)
license
Offline entitlement tokens (license / account activation).
Offline entitlement tokens (license / account activation).
llm
GoAI LLM client (used by Suggest) To remove: delete internal/llm/ + features/todo/handlers/llm_suggest.go.
GoAI LLM client (used by Suggest) To remove: delete internal/llm/ + features/todo/handlers/llm_suggest.go.
llm/fakeserver
Package fakeserver provides an httptest-compatible OpenAI Chat Completions fake for end-to-end tests of the GoAI integration without burning real tokens.
Package fakeserver provides an httptest-compatible OpenAI Chat Completions fake for end-to-end tests of the GoAI integration without burning real tokens.
nats
NATS JetStream + Leaf Node + CRUD proxy Starts embedded NATS server or connects as Leaf Node.
NATS JetStream + Leaf Node + CRUD proxy Starts embedded NATS server or connects as Leaf Node.
natswire
Todo CRUD wire protocol (shared vocabulary, no framework types)
Todo CRUD wire protocol (shared vocabulary, no framework types)
observability
Observability core: structured logging (slog)
Observability core: structured logging (slog)
perf
Opt-in operator diagnostics: statsviz at /debug/statsviz and the stdlib pprof index at /debug/pprof.
Opt-in operator diagnostics: statsviz at /debug/statsviz and the stdlib pprof index at /debug/pprof.
projectlocales
The languages a product ships, recorded once and read by everyone.
The languages a product ships, recorded once and read by everyone.
prompts
Package prompts owns every model-facing instruction as data.
Package prompts owns every model-facing instruction as data.
queue
Package queue implements the background job subsystem: a goqite-backed SQLite queue, an SSE hub for streaming progress to the browser, and a worker pool that dispatches messages through a typed HandlerRegistry.
Package queue implements the background job subsystem: a goqite-backed SQLite queue, an SSE hub for streaming progress to the browser, and a worker pool that dispatches messages through a typed HandlerRegistry.
rbac
DB-backed Casbin policy source (persist.Adapter).
DB-backed Casbin policy source (persist.Adapter).
recipe
The action table: the invocable surface, as data.
The action table: the invocable surface, as data.
recipe/register
The wiring contract between installed recipe code and the composition root.
The wiring contract between installed recipe code and the composition root.
recipestate
Package recipestate is the one place the recipe_state table becomes a predicate: the boot switch (which recipes mount and start workers) and the admin Units table (which rows read "disabled") both ask it, so the missing-row rule cannot drift between them.
Package recipestate is the one place the recipe_state table becomes a predicate: the boot switch (which recipes mount and start workers) and the admin Units table (which rows read "disabled") both ask it, so the missing-row rule cannot drift between them.
search
The BM25 layer: an inverted index in SQL, scored in Go.
The BM25 layer: an inverted index in SQL, scored in Go.
secrets
Package secrets decrypts a per-project environment file using age (https://age-encryption.org).
Package secrets decrypts a per-project environment file using age (https://age-encryption.org).
server
The UI affordance for analytics: one declarative attribute, one endpoint.
The UI affordance for analytics: one declarative attribute, one endpoint.
shape
Package shape owns the one answer to "which product is this tree?"
Package shape owns the one answer to "which product is this tree?"
themes
The shipped theme catalog: the one list the UI, the pre-paint bootstrap and theme.js all read.
The shipped theme catalog: the one list the UI, the pre-paint bootstrap and theme.js all read.
ui
The analytics beacon is page-scoped, like the operator and perf flags.
The analytics beacon is page-scoped, like the operator and perf flags.
uiregistry
The UI registry schema, shared by the gate and the reader.
The UI registry schema, shared by the gate and the reader.
scripts
agehelper command
Command agehelper is a tiny stand-in for the `age` / `age-keygen` CLIs, used by bin/init-secrets when neither binary is installed.
Command agehelper is a tiny stand-in for the `age` / `age-keygen` CLIs, used by bin/init-secrets when neither binary is installed.
web
resources
Embedded static assets (CSS, JS, etc.).
Embedded static assets (CSS, JS, etc.).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL