llm-browser/backend/AGENTS.md

Backend — agent handbook

Go 1.27 API server: stdlib net/http (Go 1.22+ method patterns + r.PathValue), Bun ORM (SQLite file by default, Postgres via DSN), layered so each change touches a predictable set of files. Follow this handbook unless the user says otherwise.

Commands

Task	Command
Full gate: fmt-check + vet + tests	make check — run before declaring any change done
Dev server	make run from backend/ (SQLite: no setup, make migrate-up once)
Tests	make test (go test ./...; no database server required)
Optional Postgres up / down	make db-up / make db-down (set DATABASE_URL=postgres://…)
Migrations	make migrate-up / make migrate-down / make migrate-status
New migration	make migrate-new name=create_projects
Binaries	make build (writes bin/)

No linters beyond go vet and gofmt are configured — don't add config files for other tools unless asked.

Architecture — dependencies flow one way

cmd/api (wiring only)
   │
   ▼
internal/api ──HTTP──▶ internal/items.Service ──▶ items.Repository (interface)
(transport)              (business rules)              ▲
                                                  BunRepository (SQL)

• internal/api — transport only: route patterns, parse input, call the service, map errors to status codes. No SQL, no business rules.
• internal/items/service.go — validation and business rules. Depends on the Repository interface, never on *bun.DB; that is what makes the tests fake-backed.
• internal/items/repository.go — the only file speaking Bun/SQL.
• internal/config — the only file reading os.Getenv.
• cmd/* — wiring and process concerns (signals, exit codes). No logic.

Imports may only point rightward in the diagram. internal/api must never import internal/database, and nothing imports internal/api except cmd.

Adding a resource (the recipe)

items is the reference. For a new resource projects:

1. internal/projects/model.go — struct with bun:"table:…,alias:…" tags, json tags, Repository interface, ErrNotFound, ValidationError.
2. internal/projects/repository.go — BunRepository implementing it.
3. internal/projects/service.go — Service, CreateInput, pointer-field UpdateInput, validation.
4. make migrate-new name=create_projects, then fill in the generated Go migration in internal/database/migrations/ (model-driven DDL, plus a down migration).
5. internal/api/projects.go — handler struct + fail error mapping.
6. internal/api/server.go — register routes on the mux.
7. Tests: projects/service_test.go (fake repo) + extend api/server_test.go.
8. make check.

HTTP conventions

• Routes are method-prefixed ServeMux patterns ("PATCH /api/v1/projects/{id}"); read segments with r.PathValue("id"), parse via the pathID helper. Wrong methods get 405 + Allow — the jsonNotFounds wrapper in server.go keeps that mux behavior, so don't register catch-all routes.
• Success bodies are the resource JSON directly; lists are bare arrays. Create answers 201 + Location; delete answers 204.
• Errors are always {"error":{"code","message"}}. Codes live in internal/api/respond.go: invalid_json, validation_failed, not_found, invalid_id, method_not_allowed, internal_error, timeout, unavailable. Map domain errors only in the handler's fail — sentinel ErrNotFound → 404, *ValidationError → 400, everything else → 500 (logged, never leaked to the client).
• Decode request bodies with decodeJSON (strict: unknown fields and

  1 MiB bodies are 400s). List endpoints take ?limit=&offset= and resource-specific filters; defaults and caps live in the service.

• Middleware chain (outermost first): logging → recover → cors → timeout → requireAuth (only when OIDC is configured). Add transport-level concerns there, not in handlers.

Auth

OIDC authorization-code + PKCE against the issuer in OIDC_ISSUER (default https://users.k6n.net). Enabled iff OIDC_CLIENT_ID is set; otherwise the server runs standalone (no /api/auth routes, /api/v1 open) and logs that loudly. Pieces:

• internal/auth — the OIDC client (discovery-driven endpoints, never hardcoded paths) and the cookie layer: session + login-transaction values are <base64url(json)>.<base64url(hmac-sha256)> sealed by Signer. Tokens stay server-side; the browser only ever holds the session cookie.
• internal/api/auth.go — the four routes: GET /api/auth/session (always 200), GET /api/auth/login?returnTo=, GET /api/auth/callback, POST /api/auth/logout. The callback path /api/auth/callback is fixed; the redirect URI is derived per request from X-Forwarded-Host/Proto (set by the Vite proxy) so localhost, *.preview.k6n.net, and the API origin all work with one client registration.
• requireAuth guards /api/v1/* with the session cookie (unknown sub-routes answer 401, not 404). It is skipped in standalone mode and in api.New tests that omit Deps.Auth.
• Login failures redirect to /?auth_error=<code> — the SPA reads that; details go to server logs only. returnTo is sanitized to a relative path (no //, no control chars) to stay an internal redirect.

Migrations

• One Go file per migration in internal/database/migrations/, named <YYYYMMDDHHMMSS>_<snake_name>.go, registering itself via Migrations.MustRegister(up, down) in init(). make migrate-new name=<snake_name> scaffolds it with a fresh timestamp — never invent timestamps by hand. Apply with go run ./cmd/migrate up (also down, status).
• Prefer model-driven DDL (db.NewCreateTable().Model((*pkg.Thing)(nil))): bun emits dialect-correct SQL for SQLite and Postgres, so migrations stay portable across the default file database and a real Postgres. Use db.Exec with raw SQL only when a model can't express it.
• Never edit or reorder an applied migration — add a new one. Every migration gets a down migration.
• internal/database/database_test.go runs all migrations plus the items repository against in-memory SQLite — extend it when adding resources so dialect drift fails make check, not production.

Databases

• Default: DATABASE_URL=sqlite:dev.db — a local file (modernc pure-Go driver, no CGO, WAL + busy_timeout applied automatically unless the DSN carries its own _pragma params). Zero setup for iteration.
• Postgres: make db-up then DATABASE_URL=postgres://fullstack:fullstack@localhost:5432/fullstack?sslmode=disable. The repository layer uses portable queries (? placeholders, no dialect-specific SQL) — if you must, branch on db.Dialect().Name().

Testing

• Three layers: internal/<pkg>/service_test.go drives business rules through an in-memory fake of the Repository interface; internal/api/server_test.go drives the real mux + middleware with the same fake behind the real service; internal/database/database_test.go runs migrations + the real BunRepository against in-memory SQLite.
• Fakes are package-local and duplicated on purpose — don't build a shared testutil package until there are enough resources to justify it.
• Table-driven tests for error cases; one flow test per handler group.

Config

• Env-only; .env in backend/ is autoloaded by cmd/api. Add a field in internal/config/config.go, a line in .env.example, and a row in the README table.
• CORS allows the Vite dev server (http://localhost:5173) by default so the frontend can call this API during development.