---
name: Andromeda Stack
description: Scaffold a Go CRUD web app using net/http + html/template + modernc.org/sqlite + the shared andromeda pkg packages (auth, web, config, sqlite, darkmatter). Use when the user wants to build a new Go web server with CRUD operations in the andromeda monorepo.
---

# Go Andromeda Web App

## Overview

Scaffold and build Go CRUD web apps in the andromeda workspace using the
standard library `net/http` mux, `html/template`, `modernc.org/sqlite` (pure
Go, no cgo) and the shared `pkg/*` packages. Each app ships a single Go
binary with HTML pages, a JSON API, optional session or API key auth, embedded
templates + static assets via `embed.FS`, and Docker deployment.

Apps live under `apps/<name>/`. Each app is its own Go module. Shared packages
live under `pkg/` and are each their own module, wired in via local
`replace` directives.

Shared crates:

- `pkg/auth` — session `Store`, `RequireSession` / `RequireAPIKey` /
  `RequireBearerOrSession` middleware, `SecureEqual`, `VerifyPassword`
  (bcrypt or plaintext), `GenerateSessionToken`, `GenerateShortID`.
- `pkg/web` — `Render`, `WriteJSON`, `WriteError`, `DecodeJSON`,
  `EmbeddedHandler`, `RedirectWithError`, `RedirectWithSuccess`, `PathInt64`.
- `pkg/config` — `LoadDotEnv`, `Getenv`, `GetenvInt`, `GetenvBool`.
- `pkg/sqlite` — `Open(path, schema)` opens SQLite with the project
  defaults (`PRAGMA foreign_keys=ON`, `SetMaxOpenConns(1)`).
- `pkg/darkmatter` — embedded shared CSS + fonts plus `Mount(mux,
  "/assets")` to register routes on any `*http.ServeMux`.

## Project Structure

```
apps/app-name/
├── main.go              # entry point; loads env, opens DB, builds App, starts server
├── app.go               # App struct + embed.FS + page-data structs
├── routes.go            # *http.ServeMux wiring + middleware
├── db.go                # schema, model, CRUD funcs (or thin wrapper around internal/store)
├── handlers_web.go      # HTML handlers (login, index, CRUD pages)
├── handlers_api.go      # JSON API handlers
├── templates/           # html/template files
│   ├── base.html        # layout with {{ block "title" . }} / {{ block "content" . }}
│   └── *.html           # pages that {{ template "base" . }} or define blocks
├── static/              # CSS, JS, images embedded via embed.FS
├── .env.example
├── Dockerfile           # multi-stage Go build, built from repo root
├── docker-compose.yml   # app-local dev compose
├── go.mod / go.sum
└── README.md
```

Apps with extra surface (e.g. `jotts` has `tui/` + `cmd_*.go` subcommands,
`feeds` has `subscriptions.go` + background poller) layer files on top of this
shape; do not invent new layers unless the app needs them.

## go.mod

Module path: `github.com/stevedylandev/andromeda/apps/<app-name>`. Pin
`go 1.25` (match other apps). Pull the shared crates by their canonical paths
and add `replace` directives for the local checkout:

```go
module github.com/stevedylandev/andromeda/apps/APP_NAME

go 1.25

require (
	github.com/stevedylandev/andromeda/pkg/auth v0.0.0
	github.com/stevedylandev/andromeda/pkg/config v0.0.0
	github.com/stevedylandev/andromeda/pkg/darkmatter v0.0.0
	github.com/stevedylandev/andromeda/pkg/sqlite v0.0.0
	github.com/stevedylandev/andromeda/pkg/web v0.0.0
)

replace (
	github.com/stevedylandev/andromeda/pkg/auth       => ../../pkg/auth
	github.com/stevedylandev/andromeda/pkg/config     => ../../pkg/config
	github.com/stevedylandev/andromeda/pkg/darkmatter => ../../pkg/darkmatter
	github.com/stevedylandev/andromeda/pkg/sqlite     => ../../pkg/sqlite
	github.com/stevedylandev/andromeda/pkg/web        => ../../pkg/web
)
```

Add `pkg/tui` only if the app ships a TUI. Add `golang.org/x/crypto`,
`yuin/goldmark`, etc. only when the specific app needs them. The Dockerfile
must copy `pkg/` into the build context for the replace directives.

Do NOT add ORMs, web frameworks (gin, echo, chi), connection pools, or HTTP
client libs unless explicitly requested. The stdlib `net/http` mux (with
method-prefixed patterns like `GET /notes/{short_id}`) is sufficient.

## main.go

Minimal — loads env, sets up logging + DB + sessions, starts the server.

```go
package main

import (
	"html/template"
	"log"
	"log/slog"
	"net/http"
	"os"

	"github.com/stevedylandev/andromeda/pkg/auth"
	"github.com/stevedylandev/andromeda/pkg/config"
)

func main() {
	config.LoadDotEnv(".env")
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))

	dbPath := config.Getenv("APP_DB_PATH", "app.sqlite")
	db, err := openDB(dbPath)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	sessions := &auth.Store{
		DB:           db,
		CookieName:   "session",
		CookieSecure: config.GetenvBool("COOKIE_SECURE", false),
	}
	if err := sessions.EnsureSchema(); err != nil {
		log.Fatal(err)
	}
	sessions.PruneExpired()

	tmpl := template.Must(template.ParseFS(appFS, "templates/*.html"))

	password := os.Getenv("APP_PASSWORD")
	if password == "" {
		logger.Warn("APP_PASSWORD not set, using default 'changeme'")
		password = "changeme"
	}
	apiKey := os.Getenv("APP_API_KEY")
	if apiKey == "" {
		logger.Info("APP_API_KEY not set, /api/* will return 403")
	}

	app := &App{
		DB:           db,
		Log:          logger,
		Templates:    tmpl,
		Sessions:     sessions,
		Password:     password,
		APIKey:       apiKey,
		CookieSecure: sessions.CookieSecure,
	}

	addr := config.Getenv("HOST", "127.0.0.1") + ":" + config.Getenv("PORT", "3000")
	logger.Info("APP_NAME server running", "addr", addr)
	if err := http.ListenAndServe(addr, app.routes()); err != nil {
		log.Fatal(err)
	}
}
```

Apps that also expose CLI subcommands (e.g. `jotts`, `sipp`) keep `main.go`
as a dispatcher and move `runServer` into `cmd_server.go`.

## app.go — App struct + embed

Holds dependencies, embedded FS, and per-page data structs.

```go
package main

import (
	"database/sql"
	"embed"
	"html/template"
	"log/slog"

	"github.com/stevedylandev/andromeda/pkg/auth"
)

//go:embed templates/*.html static/*
var appFS embed.FS

type App struct {
	DB           *sql.DB
	Log          *slog.Logger
	Templates    *template.Template
	Sessions     *auth.Store
	Password     string
	APIKey       string
	CookieSecure bool
}

type indexPageData struct {
	Items []Item
}

type loginPageData struct {
	Error string
}
```

Page-data structs go here too. Keep names like `<page>PageData`.

## routes.go

Wire routes on a `*http.ServeMux` using method-prefixed patterns. Mount
darkmatter assets and static files. Wrap protected routes with
`Sessions.RequireSession` / `auth.RequireAPIKey`.

```go
package main

import (
	"net/http"

	"github.com/stevedylandev/andromeda/pkg/auth"
	"github.com/stevedylandev/andromeda/pkg/darkmatter"
	"github.com/stevedylandev/andromeda/pkg/web"
)

func (a *App) routes() *http.ServeMux {
	mux := http.NewServeMux()

	mux.HandleFunc("GET /static/", web.EmbeddedHandler(appFS, "static"))
	darkmatter.Mount(mux, "/assets")

	requireSession := func(next http.HandlerFunc) http.HandlerFunc {
		return a.Sessions.RequireSession("/login", next)
	}
	requireAPIKey := func(next http.HandlerFunc) http.HandlerFunc {
		return auth.RequireAPIKey(a.APIKey, next)
	}

	mux.HandleFunc("GET /login", a.loginGetHandler)
	mux.HandleFunc("POST /login", a.loginPostHandler)
	mux.HandleFunc("GET /logout", a.logoutHandler)

	mux.HandleFunc("GET /{$}", requireSession(a.indexHandler))
	mux.HandleFunc("GET /items/new", requireSession(a.newItemGetHandler))
	mux.HandleFunc("POST /items", requireSession(a.createItemHandler))
	mux.HandleFunc("GET /items/{short_id}", requireSession(a.viewItemHandler))
	mux.HandleFunc("GET /items/{short_id}/edit", requireSession(a.editItemGetHandler))
	mux.HandleFunc("POST /items/{short_id}", requireSession(a.updateItemHandler))
	mux.HandleFunc("POST /items/{short_id}/delete", requireSession(a.deleteItemHandler))

	mux.HandleFunc("GET /api/items", requireAPIKey(a.apiListItems))
	mux.HandleFunc("POST /api/items", requireAPIKey(a.apiCreateItem))
	mux.HandleFunc("GET /api/items/{short_id}", requireAPIKey(a.apiGetItem))
	mux.HandleFunc("PUT /api/items/{short_id}", requireAPIKey(a.apiUpdateItem))
	mux.HandleFunc("DELETE /api/items/{short_id}", requireAPIKey(a.apiDeleteItem))

	return mux
}
```

Notes:
- `GET /{$}` matches exactly `/` (no prefix matching).
- Path params extracted with `r.PathValue("short_id")`.
- For HTML forms (no JS), delete via `POST /items/{short_id}/delete`. The
  `/api/*` routes use real `DELETE`/`PUT`.

## db.go (or internal/store)

Single-file module: schema, model, CRUD. `pkg/sqlite.Open` handles the
driver, pragmas, and schema bootstrap.

```go
package main

import (
	"database/sql"
	"errors"

	"github.com/stevedylandev/andromeda/pkg/auth"
	"github.com/stevedylandev/andromeda/pkg/sqlite"
)

type Item struct {
	ID        int64  `json:"id"`
	ShortID   string `json:"short_id"`
	Title     string `json:"title"`
	Content   string `json:"content"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

type ItemInput struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

const itemColumns = `id, short_id, title, content, created_at, updated_at`

const schema = `
CREATE TABLE IF NOT EXISTS items (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    short_id   TEXT NOT NULL UNIQUE,
    title      TEXT NOT NULL,
    content    TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);
`

func openDB(path string) (*sql.DB, error) { return sqlite.Open(path, schema) }

func scanItem(s interface{ Scan(...any) error }) (*Item, error) {
	var it Item
	err := s.Scan(&it.ID, &it.ShortID, &it.Title, &it.Content, &it.CreatedAt, &it.UpdatedAt)
	if errors.Is(err, sql.ErrNoRows) {
		return nil, nil
	}
	if err != nil {
		return nil, err
	}
	return &it, nil
}

func createItem(db *sql.DB, title, content string) (*Item, error) {
	shortID, err := auth.GenerateShortID(10)
	if err != nil {
		return nil, err
	}
	res, err := db.Exec(`INSERT INTO items (short_id, title, content) VALUES (?, ?, ?)`, shortID, title, content)
	if err != nil {
		return nil, err
	}
	id, err := res.LastInsertId()
	if err != nil {
		return nil, err
	}
	return scanItem(db.QueryRow(`SELECT `+itemColumns+` FROM items WHERE id = ?`, id))
}

func getItemByShortID(db *sql.DB, shortID string) (*Item, error) {
	return scanItem(db.QueryRow(`SELECT `+itemColumns+` FROM items WHERE short_id = ?`, shortID))
}

func listItems(db *sql.DB) ([]Item, error) {
	rows, err := db.Query(`SELECT ` + itemColumns + ` FROM items ORDER BY id DESC`)
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	var out []Item
	for rows.Next() {
		var it Item
		if err := rows.Scan(&it.ID, &it.ShortID, &it.Title, &it.Content, &it.CreatedAt, &it.UpdatedAt); err != nil {
			return nil, err
		}
		out = append(out, it)
	}
	return out, rows.Err()
}

func updateItemByShortID(db *sql.DB, shortID, title, content string) (*Item, error) {
	res, err := db.Exec(`UPDATE items SET title=?, content=?, updated_at=datetime('now') WHERE short_id=?`, title, content, shortID)
	if err != nil {
		return nil, err
	}
	if n, _ := res.RowsAffected(); n == 0 {
		return nil, nil
	}
	return getItemByShortID(db, shortID)
}

func deleteItemByShortID(db *sql.DB, shortID string) (bool, error) {
	res, err := db.Exec(`DELETE FROM items WHERE short_id = ?`, shortID)
	if err != nil {
		return false, err
	}
	n, _ := res.RowsAffected()
	return n > 0, nil
}
```

Conventions:
- Short IDs via `auth.GenerateShortID(10)`.
- Model fields use `json:"..."` tags so the same struct serializes for the API.
- "Not found" returns `(nil, nil)`, not an error — handlers check `if x == nil`.
- DB path comes from `<APP>_DB_PATH` env (e.g. `JOTTS_DB_PATH`).
- For more complex apps, move this into `internal/store/` and keep `db.go` as
  thin pass-through wrappers (see `apps/jotts`).

## handlers_web.go

HTML handlers. Use `web.Render` for templates and `web.RedirectWithError` for
flash-style errors via query params.

```go
package main

import (
	"net/http"
	"strings"

	"github.com/stevedylandev/andromeda/pkg/auth"
	"github.com/stevedylandev/andromeda/pkg/web"
)

func (a *App) loginGetHandler(w http.ResponseWriter, r *http.Request) {
	web.Render(a.Templates, w, "login.html", loginPageData{Error: r.URL.Query().Get("error")}, a.Log)
}

func (a *App) loginPostHandler(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		web.RedirectWithError(w, r, "/login", "Invalid request")
		return
	}
	if !auth.SecureEqual(r.FormValue("password"), a.Password) {
		web.RedirectWithError(w, r, "/login", "Invalid password")
		return
	}
	token, err := a.Sessions.Create()
	if err != nil {
		a.Log.Error("create session failed", "err", err)
		web.RedirectWithError(w, r, "/login", "Server error")
		return
	}
	http.SetCookie(w, a.Sessions.SessionCookie(token))
	http.Redirect(w, r, "/", http.StatusSeeOther)
}

func (a *App) logoutHandler(w http.ResponseWriter, r *http.Request) {
	if c, err := r.Cookie(a.Sessions.CookieName); err == nil && c.Value != "" {
		a.Sessions.Delete(c.Value)
	}
	http.SetCookie(w, a.Sessions.ClearCookie())
	http.Redirect(w, r, "/login", http.StatusSeeOther)
}

func (a *App) createItemHandler(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		web.RedirectWithError(w, r, "/items/new", "Invalid request")
		return
	}
	title := strings.TrimSpace(r.FormValue("title"))
	if title == "" {
		web.RedirectWithError(w, r, "/items/new", "Title is required")
		return
	}
	it, err := createItem(a.DB, title, r.FormValue("content"))
	if err != nil {
		a.Log.Error("create item failed", "err", err)
		web.RedirectWithError(w, r, "/items/new", "Failed to create item")
		return
	}
	http.Redirect(w, r, "/items/"+it.ShortID, http.StatusSeeOther)
}
```

Patterns:
- Always `auth.SecureEqual` for password compare (constant-time).
- Use `http.StatusSeeOther` (303) for POST-redirect-GET.
- Pre-rendered HTML (e.g. markdown) goes through `template.HTML` in the
  page-data struct, not via `|safe`-style filters.

## handlers_api.go

JSON API handlers. Use `web.WriteJSON`, `web.WriteError`, `web.DecodeJSON`.

```go
package main

import (
	"net/http"

	"github.com/stevedylandev/andromeda/pkg/web"
)

func (a *App) apiListItems(w http.ResponseWriter, r *http.Request) {
	items, err := listItems(a.DB)
	if err != nil {
		a.Log.Error("list items failed", "err", err)
		web.WriteError(w, http.StatusInternalServerError, "internal error")
		return
	}
	web.WriteJSON(w, http.StatusOK, items)
}

func (a *App) apiCreateItem(w http.ResponseWriter, r *http.Request) {
	var in ItemInput
	if !web.DecodeJSON(w, r, &in) {
		return
	}
	if in.Title == "" {
		web.WriteError(w, http.StatusBadRequest, "title is required")
		return
	}
	it, err := createItem(a.DB, in.Title, in.Content)
	if err != nil {
		a.Log.Error("create item failed", "err", err)
		web.WriteError(w, http.StatusInternalServerError, "internal error")
		return
	}
	web.WriteJSON(w, http.StatusCreated, it)
}

func (a *App) apiGetItem(w http.ResponseWriter, r *http.Request) {
	it, err := getItemByShortID(a.DB, r.PathValue("short_id"))
	if err != nil {
		web.WriteError(w, http.StatusInternalServerError, "internal error")
		return
	}
	if it == nil {
		web.WriteError(w, http.StatusNotFound, "not found")
		return
	}
	web.WriteJSON(w, http.StatusOK, it)
}
```

## Authentication

`pkg/auth` provides three middleware patterns. Pick based on app shape:

### Session/cookie auth (web-facing apps)

Use `*auth.Store` for password-login web apps (jotts, feeds, bookmarks, etc).
Sessions stored in the same SQLite DB via `EnsureSchema()`. Routes guarded
with `store.RequireSession("/login", handler)`.

Key API:
- `store.Create() (token, err)` — issue new session row.
- `store.SessionCookie(token) *http.Cookie` — `HttpOnly`, `SameSite=Strict`,
  7-day MaxAge.
- `store.ClearCookie()` — `MaxAge=-1` cookie for logout.
- `store.HasValid(r)` — check the incoming request's cookie.
- `store.PruneExpired()` — call at boot to GC stale rows.

### API key auth (header-based)

`auth.RequireAPIKey(expectedKey, next)`. Reads `X-API-Key` header,
`SecureEqual` compare. Returns 403 if `expectedKey` is empty (auth disabled by
config), 401 on mismatch. Use this for `/api/*` routes when there's also a
session-cookie web UI.

### Bearer-or-Session (mixed surfaces)

`auth.RequireBearerOrSession(store, expectedBearer, next)` — accepts either
`Authorization: Bearer <token>` or a valid session cookie. Used by apps that
expose the same endpoint to a CLI client AND a logged-in browser user (e.g.
`sipp`, `jotts upload`).

### Env vars

| Variable | Purpose | Default |
|----------|---------|---------|
| `HOST` | bind address | `127.0.0.1` (set `0.0.0.0` in Docker) |
| `PORT` | listen port | `3000` |
| `<APP>_DB_PATH` | SQLite path | `<app>.sqlite` |
| `<APP>_PASSWORD` | session login password | none → "changeme" warning |
| `<APP>_API_KEY` | API key for `/api/*` | none → 403 |
| `COOKIE_SECURE` | HTTPS-only cookie flag | `false` |

App-specific env vars are prefixed with the uppercase app name
(`JOTTS_PASSWORD`, `FEEDS_API_KEY`). `HOST`, `PORT`, `COOKIE_SECURE` are not
prefixed.

## Templates (html/template)

Templates live in `templates/`, parsed once at startup via
`template.ParseFS(appFS, "templates/*.html")` and rendered with
`web.Render(t, w, "name.html", data, log)`.

Use `{{ define "..." }}` / `{{ template "..." . }}` for layout composition.
The base file defines block names; pages define the content blocks.

**templates/base.html:**

```html
{{ define "base" }}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ template "title" . }}</title>
  <meta name="theme-color" content="#121113" />
  <link rel="stylesheet" href="/assets/darkmatter.css">
  <link rel="stylesheet" href="/static/styles.css">
</head>
<body>
  <div class="container">
    {{ template "content" . }}
  </div>
</body>
</html>
{{ end }}
```

**templates/index.html:**

```html
{{ define "title" }}Items{{ end }}
{{ define "content" }}
  {{ range .Items }}
    <a href="/items/{{ .ShortID }}">{{ .Title }}</a>
  {{ end }}
{{ end }}
{{ template "base" . }}
```

Notes:
- Link CSS via `/static/styles.css` (app-local) and `/assets/darkmatter.css`
  (shared theme served by `darkmatter.Mount`).
- Forms POST to web routes, not `/api/*`.
- Pass pre-rendered HTML as `template.HTML(...)`; `html/template` auto-escapes
  everything else.
- Flash errors via `?error=...` query param + `web.RedirectWithError` /
  `RedirectWithSuccess`.

## Static assets

Embedded via `//go:embed templates/*.html static/*` on a single `appFS`.
Serve under `/static/` via `web.EmbeddedHandler(appFS, "static")`. Shared
theme files (CSS + fonts) come from `darkmatter.Mount(mux, "/assets")`.

## Logging (slog)

Standard library `log/slog`. Build once in `main`:

```go
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
```

Pass it into `App` and pass it to `web.Render` (it logs template errors).
Use `logger.Error("msg", "err", err)`, `logger.Warn(...)`, `logger.Info(...)`.

## Dockerfile

Multi-stage, built from the repo root so `pkg/` is available for the
`replace` directives. Pure Go (`CGO_ENABLED=0`) because the SQLite driver is
`modernc.org/sqlite`.

```dockerfile
# Build from repo root: docker build -t APP_NAME -f apps/APP_NAME/Dockerfile .
FROM golang:1.25-bookworm AS builder
WORKDIR /app
COPY pkg/ ./pkg/
COPY apps/APP_NAME/go.mod apps/APP_NAME/go.sum ./apps/APP_NAME/
WORKDIR /app/apps/APP_NAME
RUN go mod download
COPY apps/APP_NAME/ ./
RUN CGO_ENABLED=0 go build -o /APP_NAME .

FROM debian:bookworm-slim
COPY --from=builder /APP_NAME /usr/local/bin/APP_NAME
WORKDIR /data
ENV HOST=0.0.0.0
ENV PORT=3000
EXPOSE 3000
CMD ["APP_NAME"]
```

If the app makes outbound HTTPS requests, add to the final stage:
```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
```

If the app has CLI subcommands (jotts), set `CMD ["APP_NAME", "server"]`.

## App-local docker-compose.yml

```yaml
services:
  app:
    build:
      context: ../..
      dockerfile: apps/APP_NAME/Dockerfile
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    environment:
      - APP_NAME_PASSWORD=${APP_NAME_PASSWORD:-changeme}
      - APP_NAME_DB_PATH=/data/APP_NAME.sqlite
      - COOKIE_SECURE=false
      - HOST=0.0.0.0
      - PORT=${PORT:-3000}
    volumes:
      - APP_NAME-data:/data
    restart: unless-stopped

volumes:
  APP_NAME-data:
```

## .env.example

Always ship one listing every var the app reads, with short comments.

## Wiring up a new app

A new app is not done when `go run .` works. Several workspace-level files
list every app explicitly and must be updated, or CI / Docker images / deploy
break silently.

### 1. Root `docker-compose.yml` (production)

Pulls images from GHCR. Add a service + named volume:

```yaml
services:
  APP_NAME:
    image: ghcr.io/stevedylandev/andromeda/APP_NAME:latest
    restart: unless-stopped
    ports:
      - "PORT:3000"
    volumes:
      - APP_NAME_data:/data
    env_file: apps/APP_NAME/.env
```

Pick a unique host port (existing: 3000 sipp, 3030 jotts, 3456 og, 3535 posts,
3565 shrink, 4555 feeds, 4646 library, 6754 cellar). Drop the `volumes` /
`env_file` lines if stateless (see `shrink`, `og`).

If the app holds data worth backing up, mount its volume read-only into the
`backup` service.

### 2. `.github/workflows/docker.yml`

Two spots — both list every app:

```yaml
ALL='["backup","bookmarks","cellar","easel","feeds","jotts","library","og","posts","shrink","sipp","APP_NAME"]'
```

```yaml
for app in backup bookmarks cellar easel feeds jotts library og posts shrink sipp APP_NAME; do
```

### 3. `.github/workflows/docker-test.yml`

Same two lists — keep in lockstep with `docker.yml`.

### 4. App-local `docker-compose.yml`

Per-app dev compose (see above).

## Useful commands

Per-app (from `apps/<app>/`):

```bash
go mod tidy
go build ./...
go vet ./...
go test ./...
go run .                # or: go run . server  for apps with subcommands
```

Repo-wide (from root):

```bash
make go-check                       # fmt + test + vet across all Go modules
make go-test
make go-vet
make go-fmt
make go-app-test APP=APP_NAME
make go-app-vet  APP=APP_NAME
make go-app-fmt  APP=APP_NAME
```

The shared crates (`pkg/web`, `pkg/auth`, `pkg/config`,
`pkg/sqlite`, `pkg/darkmatter`) are each their own module — run
`go build ./...` inside any to check in isolation.

## Checklist

When scaffolding a new app:

1. `mkdir apps/APP_NAME && cd apps/APP_NAME && go mod init github.com/stevedylandev/andromeda/apps/APP_NAME`
2. Add shared-crate `require` + `replace` directives to `go.mod` (auth, config, sqlite, web, darkmatter).
3. `main.go` — env load, DB open, sessions bootstrap, `App` build, `ListenAndServe`.
4. `app.go` — `App` struct, `//go:embed`, page-data structs.
5. `routes.go` — mux wiring, middleware, `/static/` + `darkmatter.Mount`.
6. `db.go` — schema, model, CRUD via `pkg/sqlite.Open`.
7. `handlers_web.go` — login/logout + HTML CRUD pages.
8. `handlers_api.go` — JSON CRUD endpoints behind `RequireAPIKey`.
9. `templates/base.html` + per-page templates using `{{ define }}` blocks.
10. `static/styles.css` + any app-specific assets.
11. `.env.example` listing every env var.
12. `Dockerfile` (multi-stage, `CGO_ENABLED=0`) + app-local `docker-compose.yml`.
13. Add service + volume to root `docker-compose.yml` (+ `backup` mount if stateful).
14. Add app name to both `ALL` array + `for app in ...` loops in
    `.github/workflows/docker.yml` AND `.github/workflows/docker-test.yml`.
15. `go mod tidy`, then `make go-app-vet APP=APP_NAME` and `make go-app-test APP=APP_NAME`.
16. `docker build -f apps/APP_NAME/Dockerfile .` from repo root to verify image.

## What NOT to include

- No web frameworks (gin, echo, chi, fiber) — stdlib `net/http` mux is enough.
- No ORMs — raw `database/sql` + `?` placeholders.
- No connection pools — `sqlite.Open` sets `MaxOpenConns(1)` on purpose.
- No cgo SQLite drivers — use `modernc.org/sqlite` via `pkg/sqlite`.
- No external CSS frameworks unless specified — use `pkg/darkmatter`.
- No JS frontend / build step — `html/template` rendered server-side.
- No CLI / TUI deps (cobra, bubbletea) unless the app actually needs them.
- No `replace` directives for anything outside `pkg/`.