go-performance-starter

Go Performance Starter is an opinionated, server-rendered starting point for small SaaS products, combining Go (Chi), templ templates, HTMX with Alpine.js, Tailwind CSS, Supabase (Auth + PostgreSQL) and Cloudflare. Its stated bet is server-rendered Go with minimal JavaScript, where performance budgets and AI-agent guardrails are enforced in CI rather than merely described. What it provides Authentication uses Supabase email/password with server-side JWT validation, and also supports anonymous guest sign-in so demo visitors receive a real identity without signing up. Multi-tenancy relies on PostgreSQL Row Level Security: request JWT claims are carried into every query through a scoped transaction (SET LOCAL ROLE plus request.jwt.claims), so auth.uid() resolves inside RLS policies and the repository layer cannot skip tenant scoping. The README notes this makes Supabase load-bearing rather than a pluggable adapter; vendor-neutral auth would require rewriting the auth middleware, the RLS scope helper and the policies. The included demo is intended to exercise the stack: a /patterns showcase of each supported HTMX/Alpine pattern with live demo and source, and an architecture quiz whose wrong answers become saveable, per-user flashcards stored as real RLS-protected rows. A background job expires inactive guests via the Supabase admin API. Developer tooling covers type-safe templ templates compiled to Go, sqlc code generation with a repository pattern, hot reload via air, Taskfile automation, golangci-lint, Prometheus metrics, structured logging with log/slog, health checks, and CI/CD. A role-based design system uses semantic tokens such as bg-surface and text-muted-foreground, with dark mode flipping tokens rather than components and CI checks against raw grays and dark: drift. Performance budgets The README lists enforced budgets: P95 response time under 100ms, binary size under 20MB, Docker image under 30MB, steady-state memory under 128MB, and startup under 500ms, validated by task test:performance and task test:binary-size. Agent-assisted development The project ships a layered AI constitution: CLAUDE.md holds halt-on-violation rules, while .claude/engineering.md, workflow.md and stack.md carry engineering defaults, process and stack facts. AGENTS.md is generated from those layers by task agents:build and CI fails if it drifts. Non-trivial features follow a three-pass Architect to Coder to Reviewer flow. The single definition of done is the task ci quality gate (formatting, lint, race tests, drift checks, binary size, vulnerability scan), which agents must clear without lowering thresholds. Architecture Decision Records (ADRs) each carry an Enforcement section mapping rules to checks. task check:adr runs a deterministic suite that verifies testable ADR consequences, including a secret scanner. Checks begin as warnings and are promoted to blocking after a clean period or a real catch. Two hooks are blocking: a Stop-gate preventing agents from ending a turn with failing tests or a blocker, and a PreToolUse guard preventing hand-edits to existing ADRs, AGENTS.md or generated code; both have kill-switches. The README marks which pieces are load-bearing and which are removable, including instructions for pruning the enforcement suite entirely. The root versions.json is described as a public consumption contract listing stack pins; task versions:check fails if any key disagrees with its in-repo source, and adding keys is fine while renaming or removing them is a breaking change. Getting started and scope Prerequisites are Go 1.26+, Docker and Docker Compose, Task, and Node.js 20+. Quick start covers cloning, copying .env.example, starting the database, running migrations, generating sqlc types, installing Go and npm dependencies, and launching the dev server with hot reload, which serves on port 4000 by default. A one-time Supabase password-reset template configuration is documented. Available tasks include dev, ci, build, test, coverage, performance and binary-size checks, lint, CSS build, Docker image build and vulnerability scanning. The project is released under the MIT license.