---
phase: 07-deploy-v1
plan: "01"
subsystem: backend-deploy
tags: [go, embed, goose, health-endpoints, deploy]
dependency_graph:
  requires:
    - 06-02 (cmd/worker wiring — same pool/db patterns mirrored)
  provides:
    - embed.FS anchor for static/ and migrations/ (consumed by Dockerfile in plan 07-02)
    - RunMigrations for use in cmd/web startup (D-10)
    - /healthz liveness and /readyz readiness endpoints (D-12, D-13)
  affects:
    - backend/cmd/web/main.go (startup sequence)
    - backend/internal/web/router.go (NewRouter signature change)
tech_stack:
  added:
    - go:embed (stdlib) — static asset and migration embedding
    - github.com/pressly/goose/v3 — SQL migration runner via embedded FS
    - github.com/jackc/pgx/v5/stdlib — pgx/v5 database/sql bridge for goose
  patterns:
    - embed.FS anchor in package root with //go:embed directives
    - fs.FS parameter for static serving (replaces string path)
    - goose.SetBaseFS + goose.Up for idempotent embedded migrations
key_files:
  created:
    - backend/embed.go
    - backend/internal/db/migrate.go
  modified:
    - backend/internal/web/handlers.go
    - backend/internal/web/handlers_test.go
    - backend/internal/web/router.go
    - backend/cmd/web/main.go
    - backend/internal/web/csrf_test.go
    - backend/internal/web/handlers_auth_test.go
    - backend/internal/web/handlers_files_test.go
    - backend/internal/web/handlers_tablos_test.go
    - backend/internal/web/handlers_tasks_test.go
decisions:
  - "embed.go in package assets at backend/ root — module root makes static/ and migrations/ siblings, no ../ paths needed"
  - "import assets \"backend\" aliased import — package name assets matches package declaration in embed.go"
  - "pool.Config().ConnConfig.ConnString() for DSN extraction — avoids storing DSN separately"
  - "goose default table name goose_db_version — no custom table needed (T-07-02 accepted)"
  - "fs.Sub() strips static/ prefix from embedded FS — avoids double-prefix in served URLs"
  - "Variable renamed fileHandler (not fs) — prevents shadowing io/fs import in router.go"
metrics:
  duration: "~6 minutes"
  completed: "2026-05-15"
  tasks: 2
  files: 11
---

# Phase 7 Plan 1: Go embed anchor, goose RunMigrations, and /healthz+/readyz handler split Summary

## What Was Built

go:embed anchor for zero-runtime-file-dependency binary, goose RunMigrations using pgx/v5/stdlib bridge, and liveness/readiness health endpoint split (HealthzHandler no-arg + ReadyzHandler with pinger).

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | go:embed anchor, goose RunMigrations, handler split | 77e37cb | backend/embed.go, backend/internal/db/migrate.go, backend/internal/web/handlers.go, backend/internal/web/handlers_test.go |
| 2 | Wire embed.FS into NewRouter and RunMigrations into main.go | bdd3cba | backend/internal/web/router.go, backend/cmd/web/main.go, 5 test files |

## Decisions Made

1. `embed.go` placed at `backend/` root in `package assets` — the module root makes `static/` and `migrations/` natural siblings so `//go:embed` directives resolve without `../` paths. Module is `module backend`; consumers import with `import assets "backend"` which aliases the import path to the package identifier.

2. `pool.Config().ConnConfig.ConnString()` used to extract DSN for goose's database/sql bridge — avoids threading DSN as a separate parameter through the call stack.

3. `goose.SetBaseFS` + `goose.Up(sqlDB, "migrations")` — the embedded FS subdirectory path `"migrations"` matches the actual directory name in the module root; no path remapping needed.

4. `fs.Sub(staticFS, "static")` strips the `static/` prefix from the embedded FS before passing to `http.FileServer(http.FS(...))` — this ensures `/static/tailwind.css` maps to the correct embedded entry without double-prefix.

5. Local variable renamed `fileHandler` (was `fs`) in `router.go` to prevent shadowing the `"io/fs"` package import.

6. All 5 test helper files updated from `"./static"` string to `os.DirFS("./static")` to match the new `fs.FS` parameter type in `NewRouter`.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] router.go and all *_test.go call sites updated in Task 1**
- **Found during:** Task 1 GREEN phase (handlers.go updated but router.go still called HealthzHandler(pinger))
- **Issue:** Changing HealthzHandler's signature from `(pinger Pinger)` to `()` caused compilation failure in router.go which prevented the handler tests from compiling at all.
- **Fix:** Updated router.go, cmd/web/main.go, and all 5 test helper files as part of the GREEN implementation. These are all interdependent changes that cannot compile in isolation. Task 2 changes were merged into a single GREEN commit after the RED test commit.
- **Files modified:** backend/internal/web/router.go, backend/cmd/web/main.go, 5 *_test.go files
- **Commit:** bdd3cba

**2. [Rule 3 - Blocking] Generated files needed in worktree (sqlc + templ)**
- **Found during:** First test run in worktree context
- **Issue:** The worktree starts clean — sqlc-generated .go files and templ-generated *_templ.go files are gitignored and must be regenerated per DEVELOPMENT.md.
- **Fix:** Ran `templ generate` (via `just generate` partial) and `sqlc generate` in the worktree backend directory before running tests.
- **Files modified:** None (generated files are gitignored; not committed)

## Verification

```
cd backend && go test ./... -count=1
```

All packages pass:
- `backend/internal/auth` — ok
- `backend/internal/db` — ok
- `backend/internal/files` — ok
- `backend/internal/jobs` — ok
- `backend/internal/web` — ok (TestHealthz_OK, TestReadyz_OK, TestReadyz_Down all pass)
- `backend/internal/web/ui` — ok
- `backend/templates` — ok

```
go build -o /tmp/xtablo-web ./cmd/web && ls -la /tmp/xtablo-web
```
Binary compiles at ~22.7 MB with embedded assets and migrations.

## Success Criteria Check

1. `go test ./... -count=1` exits 0 — PASS
2. `go build ./cmd/web/...` exits 0 — PASS
3. `grep ReadyzHandler backend/internal/web/router.go` — PASS (r.Get("/readyz", ReadyzHandler(pinger)))
4. `grep RunMigrations backend/cmd/web/main.go` — PASS (db.RunMigrations(ctx, pool, assets.Migrations))
5. `backend/embed.go` in `package assets` with `//go:embed all:static` and `//go:embed migrations` — PASS
6. `backend/internal/db/migrate.go` exports `RunMigrations` — PASS
7. TestHealthz_OK passes without pinger; TestHealthz_Down deleted; TestReadyz_OK and TestReadyz_Down pass — PASS

## Known Stubs

None.

## Threat Flags

No new threat surface introduced beyond plan's threat_model. Health endpoints return only `{"status":"ok"}` or `{"status":"degraded","db":"down"}` — no version strings, stack traces, or DSN fragments (T-07-01 mitigated).

## Self-Check: PASSED

- backend/embed.go: EXISTS
- backend/internal/db/migrate.go: EXISTS
- backend/internal/web/handlers.go: EXISTS (contains ReadyzHandler)
- backend/internal/web/router.go: EXISTS (contains /readyz route)
- backend/cmd/web/main.go: EXISTS (contains RunMigrations call)
- Commits 77e37cb and bdd3cba: VERIFIED in git log
