renatocaliari/cali-coding-go-stack

Datastar Go SDK v2 Watch

Monitor: Issue #8 (GET/POST SSE action options) and PR #18 (PatchElement* refactor) pending. Alert user if merged. Today: v1.2.2 stable.

Go Stack Web Application

Go boilerplate inspired by Northstar.

Engineering Standards

Stack patterns only. Concurrency/linting/security in cali-coding-go-standards.

• Local dev (Air, .air.toml, Makefile) also defined in cali-coding-go-standards.

⚠️ PocketBase hook wiring pitfall: app.OnServe().BindFunc(...) from inside another OnServe handler is a SILENT no-op. PocketBase's Hook.Trigger snapshots handlers before running them — nested BindFuncs never fire. Always register routes DIRECTLY on se.Router inside the existing top-level hook, or as a top-level app.OnServe().BindFunc registered before pb.Start(). Symptom: route returns 303 to /login indefinitely even though curl shows the bind ran.

⚠️ http.ServeMux Go 1.22+ subtree matching: registering GET / for an index handler matches every GET /<anything-not-explicit> until you add a more specific pattern. Order of registration doesn't matter (specificity wins). ⚠️ Datastar v1.0.2 Required — uses Datastar v1.0.2 (not RC.8).

• Datastar — Reactive hypermedia via SSE
• Templ — Go components → HTML
• DaisyUI + TailwindCSS — UI components
• NATS — Real-time messaging (JetStream for persistence)
• PocketBase — Database, auth, REST API, realtime, file storage (default)
  • sqlc — Typed Go from SQL (escape hatch when PB too narrow)
  • SQLite driver: ncruces/go-sqlite3 (pure Go, wasm2go, no CGO). Recommended over modernc for extension support (FTS5, spellfix1, unicode).
  • Extensions: ext/unicode (unaccent, pt_BR collation), ext/fts5, ext/spellfix1. ⚠️ ext/vec1 NOT supported.
• Fabric.js — Collaborative whiteboard (optional)
• LiveKit + Gemini — Voice AI (optional)
• GoAI — LLM SDK (tools, structured output, streaming, MCP) (optional)
• Zenflow — Declarative multi-agent harness, YAML workflows, LLM coordinator (optional)

Queue / Workflow Toolbox

| Tool | When | Key trait | |------|------|-----------| | goqite ★ | Default task queue — fire-and-forget, streaming (LLM SSE), short-lived jobs | SQLite queue, low-level control (Receive/Extend/Delete), permits streaming via SSE Hub | | turbine ★ | Default workflow engine — durable multi-step, resume after crash, embeds in PocketBase SQLite | Step replay safe against LLM rewrites, WithName() decoupling | | ebind v0.4 | Multi-worker, NATS-native task queue + DAG, same binary | Function-first (Register, Await[T]), requires NATS | | dagnats (experimental) | Multi-worker NATS-native DAG engine, needs console/triggers | JSON workflows, cron/webhook triggers, UI, sidecar | | go-workflows v1.4.2 | Full Temporal-like engine, needs signals/child-wf/tester | Mature (500★, 4.5y), SQLite/PG/Redis backend, diagnostics UI | | Hatchet | Multi-service, Postgres dashboard, advanced monitoring | External service, Postgres, DAG visualizer | | Rivet | Self-hosted Durable Execution platform, Temporal-compatible | External infra (Docker/Postgres), browser IDE |

(★) = recommended default for new blueprints. See Canonical Pattern below.

---

Canonical Pattern

┌──────────────────────┬─────────────────────┬──────────────────────────┐
│ Layer                │ Solves              │ Example                  │
├──────────────────────┼─────────────────────┼──────────────────────────┤
│ Task queue (goqite)  │ Fire-and-forget,    │ LLM call w/ SSE,         │
│                      │ streaming,          │ send email, resize image │
│                      │ short-lived jobs    │                          │
├──────────────────────┼─────────────────────┼──────────────────────────┤
│ Workflow engine      │ Multi-step durable  │ 5-step onboarding w/     │
│ (turbine)            │ w/ resume after     │ human approval, report   │
│                      │ crash               │ pipeline, multi-system   │
│                      │                     │ integration              │
└──────────────────────┴─────────────────────┴──────────────────────────┘

PocketBase app layout:

workflow engine (turbine, inside PocketBase)
  └── pt_* tables in same PB DB
       └── Onboarding multi-step (signup → email → config)
       └── Report generation pipeline (fetch → process → deliver)
       └── External webhook integration w/ durable retry

task queue (goqite + SSE Hub, queue.db separate from PB)
  └── LLM calls w/ streaming → Datastar (simulate, supervision, tips)
  └── Short-lived background jobs

Why it's expected: River (PG job queue) + Temporal coexist in production. SimpleQ (SQLite queue) + Temporal coexist. Temporal docs: "use Activity Task Queues for lightweight dispatch, Workflow Task Queues for orchestration."

Caveats:

1. DB isolation — turbine uses app.DB() (PB). goqite uses queue.db separate. Good: PB write lock doesn't affect streaming.
2. Complexity — turbine adds 10+ pt_* tables to PB DB. Only worth it when you truly need durable replay.
3. Atomicity — turbine gives transactional atomicity (same DB as PB data). goqite doesn't need it (fire-and-forget).
4. No LLM streaming in turbine — steps block. Streaming stays in goqite.

When to Use

| Intent | Prompt | |--------|--------| | Go web from scratch | "create a new go web app" | | New feature | "create a feature" | | Real-time/SSE | "add real-time updates" | | Hypermedia | "Datastar style app" | | Voice AI | "add voice assistant" | | LLM integration | "add LLM calls" | | Multi-agent | "coordinate agents in Go" | | Durable workflow | "add workflows to my Go app" | | Background queue | "add a queue to my app" | | Database | "add persistence" | | Whiteboard | "add collaborative whiteboard" |

🚨 templ for ALL HTML

Read: references/templ/rules.md No HTML in Go source. EVER.

---

Queue / Workflow Decision Tree

This tree covers the full stack context: PocketBase + Datastar + NATS.

┌─ Step 1 ─────────────────────────────────────────────────────────────┐
│  Just enqueue & run background jobs (single step, no resume after    │
│  crash, no DAG)?                                                     │
│  YES → goqite (default, simple SQLite queue, ~18.5k msg/s)          │
│         See references/queue/goqite-patterns.md                      │
│         *alt: ebind/dagnats if multi-worker NATS needed*            │
└──────────────────────────────────────────────────────────────────────┘
                                │ NO
                                ▼
┌─ Step 2 ─────────────────────────────────────────────────────────────┐
│  Need durable workflow (multi-step, resume after crash), single       │
│  process / few processes on same host, no external broker?            │
│  YES → turbine (default)                                              │
│         Embeds in PocketBase SQLite, `WithName()` decouples step name │
│         from Go function → safe against LLM rewriting handlers.       │
│         Step replay only re-executes incomplete steps.                │
│         *alt: go-workflows if need signals/child-wf/tester*          │
│         *alt: Hatchet/Rivet if external service OK*                   │
└──────────────────────────────────────────────────────────────────────┘
                                │ NO
                                ▼
┌─ Step 3 ─────────────────────────────────────────────────────────────┐
│  Multiple workers/processes/machines competing on same queue,         │
│  or need distributed async events (beyond PocketBase scope)?          │
│  YES → ebind OR dagnats (both NATS JetStream-native)                 │
│         JetStream handles ack/nak/redelivery/distribution natively.   │
│         SQLite is single-writer — doesn't scale here.                 │
└──────────────────────────────────────────────────────────────────────┘
                                │ NO → you likely already have an answer
                                ▼
┌─ Step 4 ─────────────────────────────────────────────────────────────┐
│  Between ebind and dagnats — what matters more?                      │
│                                                                       │
│  lightweight lib embedded in your binary?  → ebind                   │
│  platform with triggers/console/UI?        → dagnats (experimental)   │
│                                                                       │
│  See comparison table below.                                          │
└──────────────────────────────────────────────────────────────────────┘

┌─ Step 5 ─────────────────────────────────────────────────────────────┐
│  Need mature deterministic workflow primitives (signals, child        │
│  workflows, durable timers, diagnostics UI, determinism analyzer)     │
│  AND accept bringing an extra database (SQLite/PG/MySQL/Redis)        │
│  even though you already have NATS?                                   │
│  YES → go-workflows                                                    │
│         Most mature of the five (500★, 4.5y, Temporal-inspired).     │
│         No `GetVersion()` — requires manual discipline when LLM       │
│         rewrites workflow functions. Only worth it if you really      │
│         need those rich primitives.                                   │
└──────────────────────────────────────────────────────────────────────┘

Quick Start

Examples

1. Scaffold — answer decision tree above, follow generated structure. 2. Add features — GoAI for LLM, Zenflow for agents, choose queue/workflow from decision tree. 3. Sample — see each tool's README for runnable examples.

Checklist

- [ ] UI: DaisyUI (default)
- [ ] Real-time: NATS Core / JetStream / None
- [ ] Database: SQLite / PocketBase / None
- [ ] Hybrid search: Bleve / None
- [ ] Voice AI: LiveKit+Gemini / None
- [ ] AI/Agent: GoAI / GoAI+Zenflow / None
- [ ] Queue: NATS JetStream / goqite / None
- [ ] Durable workflow: turbine / ebind / dagnats / go-workflows / Hatchet / None
- [ ] Whiteboard: Fabric.js / None
- [ ] Secrets: age+~/.secrets/ / env vars / none
- [ ] Module: `github.com/user/project`
- [ ] Deploy: your-server.com / other / none

---

Detailed Decisions

UI: DaisyUI (default)

Ready-made Tailwind components. Zero JS for basic UI.

Real-time: NATS Core vs JetStream

| Need | Solution | |------|----------| | Broadcast (1→N) | NATS Core | | History | JetStream | | Work queues | JetStream Consumer | | Key-Value | JetStream KV | | Low latency | NATS Core |

Database: SQLite vs PocketBase

Simple, embedded → SQLite (ncruces)
Multi-instance, auth, REST → PocketBase

Embeddings, FTS5, Bleve — see references/database/ and references/embeddings/.

Queue / Workflow Engine Details

See references/queue/workflow-decision.md for full details on each tool:

• goqite, turbine, ebind, dagnats, go-workflows, Hatchet
• ebind vs dagnats comparison table
• LLM + versioning safety rules
• Code samples

goqite-specific references

See references/queue/goqite-patterns.md for:

• SSE Hub streaming pattern
• retry-go integration (or custom retry with SSE feedback)

---

LLM + Workflows: Versioning Safety

See references/queue/workflow-decision.md (section "LLM + Workflows: Versioning Safety") for full rules.

TL;DR: Use WithName() (turbine) or explicit versioning (MyWorkflowV2). Keep activities stable. Test with mocks. Avoid non-determinism inside workflow code.

---

Secrets: age + ~/.secrets/

3-layer model: env vars (runtime) → ~/.secrets/<project>.env.age (rest, age-encrypted) → provider dashboard (source of truth).

| Scenario | Approach | |----------|----------| | Single server, 1-2 devs, <20 secrets | ~/.secrets/ + age encryption (this stack) | | Secrets in git CI | SOPS + age | | Multi-team, audit | Doppler / Vault |

Setup: age CLI → bin/init-secrets → decrypts via AGE_SECRET_KEY env var or ~/.secrets/key.txt. See references/secrets/age-patterns.md.

Go integration: internal/secrets package, called by config.Load() before os.Getenv. Silent skip if ~/.secrets/ missing.

For full server-side audit hardening (UFW, SSH, Docker, Tailscale), see sibling skill cali-ops-server-security.

---

Datastar Patterns

⚠️ See references/datastar/patterns.md for complete patterns.

| Attribute | Example | Purpose | |-----------|---------|---------| | data-on:click | data-on:click="@post('/api/action')" | Click handler | | data-signals | data-signals={`{"count":0}`} 🔴 JSON only | Reactive state | | data-bind | data-bind="model" | Two-way binding | | data-text | data-text="$count" | Text content | | data-class | data-class="{'text-primary': $active}" | Conditional classes | | data-show | data-show="$visible" | Conditional visibility |

Key rules: Backend source of truth. Forms need name + {contentType: 'form'}.

---

References

| Reference | What it contains | |-----------|-----------------| | references/templ/rules.md | Zero-tolerance templ rules, CI | | references/datastar/patterns.md | Signals, SSE, events, indicators | | references/datastar/pitfalls.md | Known Datastar pitfalls | | references/datastar/toast.md | Backend-driven toasts | | references/datastar/versus_javascript.md | JS vs Datastar decision matrix | | references/daisyui/datastar-integration.md | DaisyUI + Datastar rules | | references/nats/when-to-use-jetstream.md | NATS Core vs JetStream | | references/voice-ai/when-to-use.md | LiveKit + Gemini setup | | references/whiteboard/fabric_patterns.md | Fabric.js sync | | references/pii-masking/cloakpipe.md | PII masking for LLM | | references/context-management/strategy.md | Context window strategy | | references/embeddings/README.md | ONNX, SBD, embeddings | | references/queue/goqite-patterns.md | goqite ctx rules, SSE Hub, retry with SSE feedback, canonical layer diagram | | references/queue/nats-workflow-patterns.md | NATS delay/retry/rate-limit/concurrency patterns | | references/queue/workflow-decision.md | Full details: goqite, turbine, ebind, dagnats, go-workflows, Hatchet, Rivet + ebind vs dagnats table + LLM versioning safety | | references/database/ | SQLite vs PB decision, CRUD | | references/examples/ | UI pattern examples | | references/datastar/ | Datastar patterns, pitfalls, DaisyUI integration | | bin/datastar-lint (cali-go-stack) | Wrapper that installs + runs github.com/calionauta/datastar-lint | | references/ci/docker-cache.md | Fast Docker builds | | references/deploy.md | CI/CD, Docker, versioning | | references/llm-streaming.md | LLM + SSE streaming (Datastar throttling, visible/hidden mode) | | references/troubleshooting.md | Error diagnostics | | references/queue/sse-hub-patterns.md | SSE Hub usage with goqite workers: register-before-enqueue, replay buffer, backpressure | | references/secrets/age-patterns.md | age + ~/.secrets/ setup, troubleshooting |

---

Datastar Lint (datastar-lint)

Validate Datastar data-* attributes against the spec. Use the public binary — do NOT vendor a local copy.

• Repo: github.com/calionauta/datastar-lint (language-agnostic: html, htm, templ)
• Install: go install github.com/calionauta/datastar-lint@latest
• Run (after templ generate): datastar-lint -r ./features/
• Flags: -r recursive, -e "html,htm,templ" extensions, -s strict (Pro attrs error)
• Exit 0 clean, 1 issues.

The cali-go-stack project wires this via bin/datastar-lint (pre-commit + make datastar-lint); the pi pre-commit hook installs and runs it automatically. Do not reintroduce a skill-local references/datastar-lint/main.go.

---

Common Pitfalls

| Pitfall | Fix | |---------|-----| | data-signals JSON escaping | Use json.Marshal | | Form data not sending | Add name to inputs | | Textareas not syncing | Use data-bind | | Tabs not working | Use data-show only | | Loading state stuck | MarshalAndPatchSignals | | go-workflows non-determinism | Use workflow.SideEffect, workflow.Select | | Activity retries not idempotent | Wrap with workflow.NewPermanentError | | LLM renamed handler, replay broken | Use WithName() (turbine) or rename function explicitly | | NATS + go-workflows stack confusion | go-workflows uses its own DB, not NATS. NATS is separate for messaging. |

---

Best Practices

1. Self-contained features — each in own directory
2. KISS (SSE) — prefer SSE over WebSockets for one-way updates
3. Indicators — always show loading states
4. DRY SSE — extract renderAndPatch helper
5. LoC — prefer Datastar signals over JS DOM manipulation
6. No HTML in Go — use Templ components
7. Idempotent activities — always, retry is automatic
8. Workflow determinism — no rand, time.Now, map range
9. Decouple step names from Go function names — especially when LLM generates workflows

---

Testing Protocol

After any browser-facing change:

1. Load agent-browser skill — navigate, verify no JS errors
2. Load dogfood skill — systematic edge case exploration

---

Test Cases

Should activate

• "Create a new Go web app with Datastar and Templ"
• "Add real-time updates to my Go project using SSE"
• "Add LLM calls with GoAI and multi-agent workflows with Zenflow"
• "Add a background queue with goqite"
• "Add a durable workflow with turbine/ebind/dagnats/go-workflows"
• "Set up a Hatchet workflow for job execution"
• "Add voice AI with LiveKit to my Go app"
• "Create a new feature module"
• "Migrate existing project to Datastar"
• "Set up Postgres with sqlc and golang-migrate"

Should NOT activate

• "Write a Go CLI tool" (use cali-coding-go-standards)
• "Review my Go code for bugs" (use cali-coding-go-standards)
• "Debug a goroutine leak" (use cali-coding-go-standards)
• "Set up golangci-lint" (use cali-coding-go-standards)