# Phase 1: Foundation - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-14
**Phase:** 1-Foundation
**Areas discussed:** Directory layout, Migration tool, Templating + router, Local dev stack

---

## Directory Layout

| Option | Description | Selected |
|--------|-------------|----------|
| Two cmds, shared internal | `backend/cmd/web` + `backend/cmd/worker` + shared `backend/internal/{db,web,session,tablos,tasks,files,...}`. Standard Go layout. | ✓ |
| Single binary, subcommand | One `backend` binary with `backend web` / `backend worker` subcommands. Smaller deploy artifact. | |
| Feature-first internal | `internal/<feature>/{handler.go,store.go,templates/}` — each domain owns its own templates + handlers. | |

**User's choice:** Two cmds, shared internal
**Notes:** Locks in conventional Go layout. Single-binary subcommand left available for Phase 7 reconsideration if the two-binary Docker image gets awkward.

---

## Migration Tool

| Option | Description | Selected |
|--------|-------------|----------|
| goose | pressly/goose. Embeddable library + CLI. Supports Go-based migrations. One file per migration with `-- +goose Up/Down`. | ✓ |
| golang-migrate | golang-migrate/migrate. CLI-first, SQL-only by default. Wider mindshare. Split `*.up.sql` / `*.down.sql`. | |
| atlas | ariga/atlas. Schema-as-code/declarative. Richer features but heavier learning curve. | |

**User's choice:** goose
**Notes:** User asked for a direct recommendation; Claude argued for goose on three grounds — embeddability (one binary in Phase 7 deploy), single-file-per-migration aligning with sqlc, and the option for Go migrations if a backfill ever requires it. User accepted ("go for goose").

---

## Templating + Router

| Option | Description | Selected |
|--------|-------------|----------|
| templ + chi | templ (type-safe, compiled templates) + chi router. Best HTMX-fragment DX. Matches go-backend's existing pick. | ✓ |
| html/template + net/http 1.22 | Std-lib-only — html/template + Go 1.22 enhanced ServeMux (method-prefixed patterns). Zero external deps. | |
| templ + net/http 1.22 | Keep templ's type safety, drop chi. Hand-roll middleware stacking. | |

**User's choice:** templ + chi
**Notes:** Best DX for HTMX partials wins over a stricter dep budget. chi's middleware ergonomics and `Route()` subrouters will be load-bearing once auth + tablos routes land.

---

## Local Dev Stack

| Option | Description | Selected |
|--------|-------------|----------|
| podman + standalone Tailwind | podman compose for Postgres; standalone Tailwind binary (no Node/pnpm in `backend/`). | ✓ |
| docker compose + standalone Tailwind | docker compose for portability; same standalone Tailwind binary. | |
| podman + pnpm Tailwind | Keep go-backend's existing pnpm + tailwindcss npm package. | |

**User's choice:** podman + standalone Tailwind
**Notes:** "No JS toolchain in `backend/`" is a load-bearing thesis. compose.yaml is portable between podman and docker — README will note both. Tailwind binary version is pinned in the justfile.

---

## Claude's Discretion

- Concrete chi middleware order within the agreed stack (RequestID → RealIP → Logger → Recoverer → graceful shutdown wiring).
- slog handler details (JSON in prod, text in dev), keyed off `ENV`.
- air configuration (`air.toml` watch globs; whether tailwind runs as a separate `just styles` process or air `pre_cmd`).
- Whether goose runs via library call from a `backend migrate` subcommand or pure CLI in Phase 1 (Phase 7 will likely require the library approach).
- Demo page layout/CSS — keep minimal but professional; the visible `hx-get` interaction is the only hard requirement.
- Whether to ship a minimal `/healthz` smoke test in Phase 1 or defer all testing to Phase 2.

## Deferred Ideas

- **Single-binary subcommand layout** (`backend web` / `backend worker`) — rejected for Phase 1; revisit in Phase 7 if two-binary Docker image is awkward.
- **Embedded goose migrations at app startup** — Phase 1 uses CLI; embedded library call deferred to Phase 7.
- **`/readyz` endpoint** — Phase 7 (DEPLOY-04). Phase 1 ships `/healthz` only.
- **Production logging configuration** (sampling, redaction, log shipping) — Phase 7.
- **Full handler test suite** — Phase 2 establishes testing strategy; Phase 1 may include a minimal `/healthz` test only.
