An AI-native software factory for cloud-hosted Go + SolidJS apps.
Production harness — plans, module specs, 45 Cursor rules, drift CI, integration test harness — plus a runnable starter app and GCP deploy scripts.
Live example: golid.ai — marketing site built with this factory; clone the repo for the harness and template app.
Factory · Quick Start · Fork · Why Golid · Deploy · Docs
| Layer | Technology | Layer | Technology |
|---|---|---|---|
| Backend | Go 1.26 · Echo v4 · pgx/v5 | Frontend | SolidJS · SolidStart · Tailwind CSS 4 |
| Database | PostgreSQL 16 | Infrastructure | Cloud Run · Cloud SQL · GCS |
| Auth | JWT rotation · selector/verifier tokens | Real-time | SSE hub with ticket auth |
Mailgun (IsConfigured()) |
Job Queue | asynq + Redis (goroutine fallback) | |
| Observability | OpenTelemetry · Prometheus (opt-in) | Feature Flags | DB-backed with 30s cache |
| Hot Reload | Air (Go) + Vite HMR | DevContainer | One-click setup, zero config |
| Testing | 995 tests (353 Go unit + 622 Vitest + 20 E2E) | Factory harness | Plans · spec-drift · rule-health · plan loop |
| AI Rules | 45 Cursor rules (auto-activate on edit) | Integration | TEST_DATABASE_URL · per-package schemas (separate go test -tags integration run) |
Agents and humans share the same production contract — not prompt memory, not ad-hoc CI.
1. Classify & plan — workflow-routing picks risk tier (T0–T3). Write slices in docs/plans/ under planning-standards guardrails: verify schema and file claims against migrations and source; acceptance criteria per slice. New modules: plan-feature. Calibration: golden-slices.
2. Execute slices — slice-and-ship per slice: implement → test → spec/OpenAPI sync → audit-bugs pre-merge gate → commit. For multi-slice plans, invoke plan-execution-loop to orchestrate subagents: implement → audit (≥90/100) → fix → re-audit before the next slice. Archive completed plans under docs/plans/archive/.
| Step | What | Where |
|---|---|---|
| Spec | Current behavior (updated as slices land) | docs/modules/*/spec.md |
| Build | Rules + scaffold enforce patterns | .cursor/rules/ · make new-module |
| Verify | Unit + integration harness, race detector | Per-package it_<pkg>_<pid> schemas · sharded CI |
| Gate | Spec + rules stay aligned with code | check_spec_drift.sh · check_citation_freshness.sh · check_rule_health.sh on every PR |
| Ship | Cloud deploy + full rebrand | ./scripts/deploy.sh · make rename (20+ file categories) |
vs blank repo + AI: OpenAPI + module specs + drift CI (not prompt memory) · planning-standards → slice-and-ship / plan-execution-loop · path-filtered CI + E2E + Codecov 80% gate · make rename rebrands the whole factory.
Full map: Organism Pattern · Plans · routing eval
Starter modules the factory extends — use make new-module or follow example-module.md.
| Module | What it does |
|---|---|
| Auth | Registration, login, JWT refresh rotation, password reset, email verification |
| Users | Profile (/me), settings, admin user_type gates |
| Feature flags | Public GET /features, admin CRUD, cached reads |
| SSE | Per-user channels, one-time ticket auth, reconnect + backpressure |
| Components | 70+ atoms/molecules/organisms — charts, grids, date pickers, modals |
| Opt-in infra | Email, queue, Redis rate limiting, tracing, metrics — off by default |
Also included: OpenAPI 3.1 + TypeScript codegen, sqlc queries, golang-migrate (with down migrations), CSRF + dual-tier rate limiting, scaffold generator, domain-safe rename tool, GCP deploy/teardown scripts.
Prerequisites: Docker 24+, Node.js 24+, Go 1.26+
git clone https://github.com/golid-ai/golid.git my-project && cd my-project
# Open in VS Code/Cursor → "Reopen in Container"Migrations and seed data run automatically (entrypoint.dev.sh). Backend starts on 8080. Frontend starts as a VS Code task — open the Terminal tab and wait until the frontend dev server prints its local URL before opening http://localhost:3000.
git clone https://github.com/golid-ai/golid.git my-project && cd my-project
make setup
# First run only — migrate + seed the dev database
export DATABASE_URL=postgres://dev:dev@localhost:5432/golid?sslmode=disable
make migrate-up seed
docker compose up # DB + backend on :8080
cd frontend && npm run dev # frontend on :3000Test accounts (after seed): admin@example.com / Password123! (admin) · user@example.com / Password123! (user)
Guides: Quick Start · Start Here · Forking? make rename · Upgrading? CHANGELOG (0.3.x breaking changes in 0.3.0)
golid/
├── backend/
│ ├── cmd/server/main.go # Bootstrap, shutdown, background jobs
│ ├── internal/
│ │ ├── wire/ # BuildServices, BuildHandlers, RegisterRoutes
│ │ ├── service/ # Business logic (auth, user, feature, sse, email)
│ │ ├── handler/ # HTTP handlers
│ │ ├── middleware/ # JWT, CSRF, rate limiting, security
│ │ ├── pagination/ # Query normalization
│ │ ├── retry/ # Exponential backoff for fire-and-forget
│ │ └── apperror/ # Typed error responses
│ ├── migrations/ # SQL migration pairs (up + down)
│ ├── openapi.yaml # REST API contract (OpenAPI 3.1)
│ └── seeds/ # Development seed data
├── frontend/
│ └── src/
│ ├── components/ # 70+ components (atoms/molecules/organisms)
│ ├── lib/ # api.ts, auth.ts, constants, validation
│ └── routes/
│ ├── (public)/ # login, signup, forgot-password, verify-email
│ └── (private)/ # dashboard, settings, component showcase
├── docs/
│ ├── modules/ # Auth, users, feature specs (+ drift CI)
│ ├── plans/ # Feature plans (active + archive/)
│ ├── architecture.md # Layers, auth, SSE, wire
│ └── patterns/ # Stack quick references (Go, SolidJS, …)
├── .cursor/rules/ # 45 AI coding rules
├── config/ # Environment files
├── scripts/ # Deploy, drift checks, init-test-db, teardown
└── infra/ # Cloud Run, Cloud Build configs
# First run: make setup && migrate-up seed (see Quick Start)
make dev # DB + backend (docker compose up)
cd frontend && npm run dev # Frontend dev server (port 3000)
make test # Backend + frontend unit tests
make check # lint + test + build (local CI parity)
export TEST_DATABASE_URL='postgres://dev:dev@localhost:5432/golid_test?sslmode=disable'
scripts/init-test-db.sh
cd backend && TEST_MIGRATIONS_PATH="$(pwd)/migrations" \
go test -tags integration ./internal/handler/... ./internal/service/... -race
make new-module name=notes # Scaffold CRUD module
make rename name=myapp module=github.com/user/myapp/backend domain=myapp.com
make help # All Makefile targets
./scripts/deploy.sh # Deploy to QA (Cloud Run)
./scripts/deploy.sh check # Validate config before deployIntegration test setup: CLI Reference (init-test-db.sh, TEST_DATABASE_URL).
| Golid | Blank repo + AI | |
|---|---|---|
| Contract | OpenAPI + module specs + drift CI | Prompt memory |
| Integration safety | TEST_DATABASE_URL, isolated schemas |
Easy to wipe dev DB |
| Agent ops | workflow-routing → planning-standards → slice-and-ship / plan-execution-loop (45 rules) |
Ad-hoc |
| Production CI | Path-filtered, E2E, Codecov 80% gate | Often none |
| Fork factory | make rename rebrands harness + app |
Manual find-and-replace |
| Golid | Next.js + API | Go-only starters | |
|---|---|---|---|
| Full-stack type safety | Go + TypeScript (OpenAPI → generated types) | TypeScript (tRPC/Zod) | Go only |
| Production UI | 70+ components | BYO | None |
| SSR + real-time | SolidStart SSR + SSE | Partial | None |
| Deploy | One-command GCP (deploy.sh); Docker elsewhere |
Vercel-centric | BYO |
| Memory | ~30MB binary | ~200MB+ | ~30MB |
Opt-in complexity: docker compose up works with zero Redis, Mailgun, or OTEL. Set one env var per module when you need it — see Opt-In Modules below.
| Module | Trigger | Zero-config | Production |
|---|---|---|---|
MAILGUN_API_KEY |
Logs to stdout | Mailgun delivery | |
| Job Queue | REDIS_URL |
Goroutine + Retry | asynq + Redis |
| Rate Limiting | REDIS_URL |
In-memory | Redis fixed-window |
| Tracing | OTEL_ENDPOINT |
No tracing | OTLP export |
| Metrics | METRICS_ENABLED |
No /metrics |
Prometheus |
| Feature Flags | Always on | PostgreSQL + cache | Same |
docker compose --profile production up adds Redis + worker (see CHANGELOG).
Handlers → Middleware → Services → PostgreSQL. Wiring lives in internal/wire/ (BuildServices, BuildHandlers, RegisterRoutes); business logic in internal/service/<pkg>/. Frontend uses SolidStart SSR with file-based routing.
API surface today: /api/v1 (versioning middleware + migration path in api-versioning.md).
Full breakdown: architecture.md — auth flow, SSE ticket exchange, shutdown order, observability.
git clone https://github.com/YOUR_USER/my-app.git && cd my-app
make rename name=myapp module=github.com/YOUR_USER/my-app/backend domain=myapp.com
git diff && make checkThe rename tool updates 20+ file categories (imports, Docker, CI, Cursor rules, branding, OpenAPI) with domain-safe replacements. Details: cmd/rename.
./scripts/deploy.sh # QA (default)
./scripts/deploy.sh prod # Production (confirmation gate)
./scripts/deploy.sh qa api # Backend only
./scripts/teardown.sh # Teardown QA resourcesscripts/README.md · deployment-options.md (Fly.io, Railway, Render, bare metal)
| Pattern | Backend | Frontend |
|---|---|---|
| Error handling | apperror, no leaked internals |
alive guard + batch() on async |
| Content states | — | Switch/Match, no nested <Show> |
| SQL | Parameterized queries, rows.Err(), transactions |
— |
| Auth | TOCTOU-safe refresh, selector/verifier | SSR redirects, reactive 401 logout |
| Linting | golangci-lint (see backend/.golangci.yml) |
ESLint + eslint-plugin-solid |
| Testing | Unit + integration (real DB), race tests | Vitest 4 + axe-core + Playwright E2E |
| Coverage | Codecov project (see badge); target: 80% gate |
Vitest floors 75/54/78/75 (included files) |
| Pre-merge | audit-bugs / audit-codebase before declaring done |
Same checklists; T2+ and security slices mandatory |
| CI | Path filters, spec-drift, rule-health, sharded coverage | lint, typecheck, build, audit (non-blocking) |
| Guide | What it covers |
|---|---|
| Start Here | Orientation: app flow, directories, devcontainer, rules |
| Architecture | Layers, auth flow, SSE, wire, observability |
| Module Specs | Auth, users, feature — rules, API surface, test scenarios |
| Quick Start | Setup in 5 minutes |
| CLI Reference | Make targets, health endpoints, TEST_DATABASE_URL |
| Example Module | Build a feature end-to-end |
| Best Practices | Coding standards with real examples |
| Components | 70+ UI components reference |
| Organism Pattern | How rules, specs, plans, and drift checks connect |
| GCP Networking | Cloud Run frontend/API network diagram |
| Deployment Options | Cloud Run, Fly.io, Railway, Render |
| API Reference | OpenAPI 3.1 — paste into Swagger Editor |
| Changelog | Release history (latest: 0.3.2; breaking changes in 0.3.0) |
| Full Index | Complete documentation map |
Cursor rules: 45 rules in .cursor/rules/ — full index in cursor-rules.md. Factory workflow: workflow-routing → planning-standards → slice-and-ship / plan-execution-loop; pre-merge audit-bugs before declaring slices done. Split examples: solidjs-pages + solidjs-data-fetching, go-service + go-service-errors.
MIT. Some frontend dependencies (AG Grid Community, Observable Plot, Three.js) have their own licenses — review frontend/package.json before commercial use.
Docker or DevContainer won't start? Docker Desktop → Troubleshoot → Clean / Purge data, then retry.
See CONTRIBUTING.md.