STACK IT FAST
ALL RULES & SKILLS

Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Raw .MD go-echo-sqlite
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

Architecture guidelines for single-binary Go services using the Echo framework, embedded SQLite, and minimal-JS server-rendered UI.

Go Echo SQLite Docker
CLI & AI Agent Import Verified in 4 production projects
AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/go-echo-sqlite
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·38 lines · 3.4 KB
1# Project Architecture & Guidelines (Go + Echo + SQLite)
2
3## 1. System Architecture
4- **Language**: Go 1.22+, compiled to a single static binary with no runtime dependencies.
5- **Web Framework**: Echo (lightweight HTTP router and middleware, `github.com/labstack/echo/v4`).
6- **Database**: Embedded SQLite (`modernc.org/sqlite` or `mattn/go-sqlite3`), file-based, no separate database server to deploy or back up.
7- **Frontend**: Server-rendered HTML via Go's `html/template` or a light templating library, with HTMX or minimal vanilla JS for interactivity — no separate SPA build.
8
9## 2. Single-Binary Deployment Model
10- Embed static assets (templates, CSS, migrations) into the binary with Go's `embed.FS` so deployment is copying one file, not a directory tree.
11- Store the SQLite database file in a configurable data directory (`--data-dir` flag or `DATA_DIR` env var), never hardcoded, so it's easy to volume-mount in Docker.
12- Enable SQLite's WAL (write-ahead log) mode at startup (`PRAGMA journal_mode=WAL;`) for concurrent read/write access without locking the whole database on every write.
13
14## 3. Echo Handler & Middleware Conventions
15- Group routes by resource with `e.Group("/api/projects")`; apply auth middleware at the group level, not per-handler.
16- Handlers return typed errors that a central `HTTPErrorHandler` maps to status codes — never `c.String(500, err.Error())` scattered across handlers, which leaks internal error detail to clients.
17- Use Echo's built-in request validation (`c.Bind()` + a `Validate()` method backed by `go-playground/validator`) before touching the database.
18
19## 4. Database Access & Migrations
20- Use a lightweight migration tool (`golang-migrate` or a hand-rolled versioned-SQL-files runner) that ships embedded in the binary and runs automatically on startup — self-hosted single-binary tools can't assume an operator will run a separate migration command.
21- Wrap multi-statement writes in an explicit `sql.Tx`; SQLite's single-writer model makes uncommitted long-lived transactions a common source of "database is locked" errors.
22- Keep the database package (`internal/db`) free of HTTP concerns — handlers call typed repository methods, not raw SQL.
23
24## 5. Common Pitfalls / Coding Standards
25- ❌ Leaving SQLite in the default `journal_mode=DELETE`, which serializes all writes and causes "database is locked" under any concurrent load.
26- ❌ Hardcoding file paths instead of reading from a configurable data directory, breaking Docker volume mounts.
27- ✅ Set `busy_timeout` on the SQLite connection so concurrent writers retry briefly instead of failing immediately.
28
29## 6. Testing Conventions
30- Standard `testing` package with table-driven tests; use an in-memory SQLite database (`:memory:`) per test for isolation and speed.
31- `httptest` for handler-level tests against the Echo instance without a real network listener.
32- Run `go vet` and `staticcheck` in CI; Go's compiler catches most type errors, so linting focuses on correctness patterns instead.
33
34## 7. Git Workflow & PR Conventions
35- Conventional Commits scoped to the package, e.g. `fix(db): use WAL mode to avoid write locking under load`.
36- New migrations ship in the same PR as the schema change; migration files are numbered and never edited after merge.
37- Require `go build ./...`, `go vet ./...`, and `go test ./...` green before merge.
38- Squash-merge; tag releases so the single-binary artifact is reproducible from a known commit.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

Architecture Overview

Standardized production guidelines for Go, the Echo web framework, and embedded SQLite — the pattern behind small, single-binary, self-hosted tools that a user can run with one command and no external database server.

Verified Real-World Adoption

PocketBase is the canonical example of this exact stack (Go + Echo + embedded SQLite, single binary). Gitea and Gatus follow the same single-binary, embeddable-SQLite philosophy, offering PostgreSQL as an opt-in upgrade path for larger deployments rather than a requirement.

Key Architectural Nuances

  • Zero External Dependencies by Default: The database ships inside the same process as the application, so “installing” the tool is copying one binary and pointing it at a data directory.
  • WAL Mode as a Non-Negotiable Default: Without it, SQLite’s exclusive write lock turns any concurrent access pattern into a source of “database is locked” errors under real usage.
FREQUENTLY ASKED QUESTIONS

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

How is this different from the Go + PostgreSQL + React rule?

That rule targets a full-throughput web dashboard with a separate React frontend and a managed PostgreSQL server. This rule targets single-binary, self-hostable tools -- status pages, git servers, embedded backends -- where the entire application, including its database, ships as one file an operator runs with zero external dependencies.

Why WAL mode instead of the SQLite default?

SQLite's default rollback-journal mode takes an exclusive lock on the whole database file for the duration of a write, so any concurrent read blocks until it finishes. WAL (write-ahead log) mode lets readers continue against the last-committed state while a write is in progress, which is the difference between a tool that handles a handful of concurrent requests and one that locks up under them.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Astro, Tailwind CSS

Astro SSR + Tailwind CSS + Cloudflare

Architecture rules for Astro server-side rendering, React client islands, Tailwind CSS, and Cloudflare Pages/Workers edge deployment.

5 techs Copy Rules
4 FILE FORMATS Bun, Hono

Bun + Hono + SQLite (libSQL & Drizzle ORM)

Ultra-fast edge API architecture using Bun.serve(), Hono v4, Drizzle ORM with embedded SQLite / Turso libSQL, and Zod OpenAPI validation.

6 techs Copy Rules
4 FILE FORMATS Django, Python

Django + PostgreSQL + Redis + Celery

Production guidelines for Django 5 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules