---
phase: 05-template-data-model-and-api
verified: 2026-03-12T12:00:00Z
status: passed
score: 21/21 must-haves verified
re_verification: false
---

# Phase 5: Template Data Model and API Verification Report

**Phase Goal:** The backend has a first-class template system — new DB tables, migrations, and REST endpoints — that lets the app store user templates, classify items by tier, and generate budgets from templates programmatically
**Verified:** 2026-03-12
**Status:** PASSED
**Re-verification:** No — initial verification

## Goal Achievement

### Observable Truths (Plan 01)

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | `budget_items` table has an `item_tier` column with values fixed, variable, one_off | VERIFIED | `002_templates.sql` line 3: `ALTER TABLE budget_items ADD COLUMN item_tier item_tier NOT NULL DEFAULT 'fixed'`; enum defined on line 1 |
| 2 | `templates` table exists with one-per-user constraint | VERIFIED | `002_templates.sql` lines 5-13: CREATE TABLE templates + `CREATE UNIQUE INDEX idx_templates_user_id ON templates (user_id)` |
| 3 | `template_items` table excludes one_off via CHECK constraint | VERIFIED | `002_templates.sql` line 24: `CONSTRAINT chk_template_items_no_one_off CHECK (item_tier IN ('fixed', 'variable'))` |
| 4 | Template and TemplateItem Go structs exist with JSON tags | VERIFIED | `models/models.go` lines 99-124: Template, TemplateItem, TemplateDetail structs, all fields have json tags |
| 5 | Query functions exist for template CRUD and budget generation from template | VERIFIED | `db/queries.go`: GetTemplate (377), UpdateTemplateName (415), CreateTemplateItem (432), UpdateTemplateItem (467), DeleteTemplateItem (493), ReorderTemplateItems (501), GenerateBudgetFromTemplate (558) |
| 6 | GetBudgetWithItems returns item_tier in budget item rows | VERIFIED | `db/queries.go` line 251: `bi.item_tier` in SELECT; line 266: `&i.ItemTier` in Scan |
| 7 | CreateBudgetItem and UpdateBudgetItem accept item_tier parameter | VERIFIED | `db/queries.go` line 337: `itemTier models.ItemTier` param on CreateBudgetItem; line 354: same on UpdateBudgetItem |

### Observable Truths (Plan 02)

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 8 | GET /api/template returns template with items (or empty if none exists) | VERIFIED | `router.go` line 65: `r.Get("/", h.GetTemplate)`; `handlers.go` line 456: GetTemplate calls queries.GetTemplate which returns empty TemplateDetail on pgx.ErrNoRows |
| 9 | PUT /api/template updates template name | VERIFIED | `router.go` line 66: `r.Put("/", h.UpdateTemplateName)`; `handlers.go` line 466: UpdateTemplateName handler implemented |
| 10 | POST /api/template/items adds item and auto-creates template | VERIFIED | `router.go` line 67: `r.Post("/items", h.CreateTemplateItem)`; `db/queries.go` line 435: ON CONFLICT (user_id) DO UPDATE implements lazy creation |
| 11 | PUT /api/template/items/{itemId} updates a template item | VERIFIED | `router.go` line 69: `r.Put("/items/{itemId}", h.UpdateTemplateItem)`; `handlers.go` line 518 |
| 12 | DELETE /api/template/items/{itemId} removes a template item | VERIFIED | `router.go` line 70: `r.Delete("/items/{itemId}", h.DeleteTemplateItem)`; `handlers.go` line 557 |
| 13 | PUT /api/template/items/reorder batch-updates sort order | VERIFIED | `router.go` line 68: `r.Put("/items/reorder", h.ReorderTemplateItems)` — registered BEFORE `{itemId}` to prevent routing conflict; `handlers.go` line 572 |
| 14 | POST /api/budgets/generate creates budget from template or returns 409 if exists | VERIFIED | `router.go` line 53: `r.Post("/generate", h.GenerateBudget)` placed before `/{id}` routes; `handlers.go` line 603: errors.As checks BudgetExistsError, returns 409 with budget_id |
| 15 | POST /api/budgets/{id}/items accepts optional item_tier field | VERIFIED | `handlers.go` line 389: `ItemTier models.ItemTier` in CreateBudgetItem request struct |
| 16 | PUT /api/budgets/{id}/items/{itemId} accepts optional item_tier field | VERIFIED | `handlers.go` line 421: `ItemTier models.ItemTier` in UpdateBudgetItem request struct |
| 17 | GET /api/budgets/{id} returns item_tier in each budget item | VERIFIED | `models/models.go` line 69: `ItemTier ItemTier json:"item_tier"` on BudgetItem; GetBudgetWithItems scans it |
| 18 | One-off items cannot be added to templates (rejected by DB CHECK) | VERIFIED | DB-level: migration CHECK constraint; handler-level defense: `handlers.go` lines 497-504 reject one_off with 400 |

**Score:** 18/18 plan truths verified

### Required Artifacts

| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `backend/migrations/002_templates.sql` | item_tier enum, templates table, template_items table, item_tier column on budget_items | VERIFIED | 28 lines, all four schema elements present and syntactically correct |
| `backend/internal/models/models.go` | ItemTier type, Template struct, TemplateItem struct, updated BudgetItem | VERIFIED | ItemTier type + 3 constants (lines 21-27), BudgetItem.ItemTier (line 69), Template (99-105), TemplateItem (107-119), TemplateDetail (121-124) |
| `backend/internal/db/queries.go` | Template query functions, updated budget item queries with item_tier | VERIFIED | All 7 template functions present (lines 377-668), BudgetExistsError struct (lines 16-25), item_tier in all budget item queries |
| `backend/internal/api/handlers.go` | Template handlers, Generate handler, updated budget item handlers | VERIFIED | 7 new handler methods (lines 456-637), CreateBudgetItem/UpdateBudgetItem updated with ItemTier |
| `backend/internal/api/router.go` | /api/template routes and /api/budgets/generate route | VERIFIED | /api/template route group (lines 64-71), /api/budgets/generate (line 53) |

### Key Link Verification

| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| `db/queries.go` | `models/models.go` | Template/TemplateItem struct usage in query returns | VERIFIED | models.Template used at lines 378, 416; models.TemplateItem at 445, 468; models.TemplateDetail at 377, 384, 412 |
| `migrations/002_templates.sql` | `db/queries.go` | SQL column names match Scan field order for item_tier | VERIFIED | item_tier appears in SELECT/INSERT/UPDATE/RETURNING clauses; Scan order matches SELECT order in GetBudgetWithItems and GetTemplate |
| `api/handlers.go` | `db/queries.go` | h.queries.GetTemplate, h.queries.GenerateBudgetFromTemplate | VERIFIED | GetTemplate called at line 458, GenerateBudgetFromTemplate at line 623, CreateTemplateItem at line 510 |
| `api/router.go` | `api/handlers.go` | route registration to handler methods | VERIFIED | h.GetTemplate at line 65, h.GenerateBudget at line 53 |

### Requirements Coverage

| Requirement | Source Plan | Description | Status | Evidence |
|-------------|------------|-------------|--------|----------|
| TMPL-01 | 05-01, 05-02 | User can tag a budget item as fixed, variable, or one-off when creating or editing it | SATISFIED | ItemTier on BudgetItem model; CreateBudgetItem/UpdateBudgetItem handlers accept item_tier field; GET budget returns item_tier per item |
| TMPL-02 | 05-01, 05-02 | User can define a monthly budget template containing fixed items (with amounts) and variable items (category only) | SATISFIED | templates + template_items tables with CHECK (no one_off); full CRUD API under /api/template; lazy template creation; reorder endpoint |
| TMPL-04 | 05-01, 05-02 | One-off items are not carried forward to new months | SATISFIED | DB-level: CHECK constraint on template_items prevents one_off; GenerateBudgetFromTemplate only reads template_items (which cannot contain one_off); handler-level validation at lines 497-504 |

**Orphaned requirements check:** REQUIREMENTS.md traceability table maps TMPL-01, TMPL-02, TMPL-04 to Phase 5. No other requirements are mapped to Phase 5. No orphaned requirements.

### Anti-Patterns Found

No anti-patterns found.

- No TODO/FIXME/PLACEHOLDER comments in any phase-modified Go files
- No empty return stubs in template or budget-generation code
- No unimplemented handlers (all 7 template handlers have real logic)
- Note: `OIDCStart` and `OIDCCallback` handlers return 501 "not configured" — these are pre-existing stubs from an earlier phase, not introduced by Phase 5

### Human Verification Required

None required. All observable truths for this phase (backend data model and API) are fully verifiable by static code inspection and `go build`/`go vet`.

### Gaps Summary

No gaps. All must-haves verified.

---

## Verification Notes

**`go build ./...` result:** Exit 0 — full backend compiles cleanly.

**`go vet ./...` result:** Exit 0 — no issues.

**Route ordering confirmed:** In `router.go`, `PUT /items/reorder` (line 68) is registered before `PUT /items/{itemId}` (line 69). In the `/api/budgets` group, `POST /generate` (line 53) is registered before `GET /{id}` (line 54). Both orderings prevent chi treating static path segments as parameterized values.

**BudgetExistsError wiring confirmed:** `db.BudgetExistsError` struct defined in `db/queries.go` with `ExistingBudgetID uuid.UUID` field. Handler uses `errors.As(err, &budgetExistsErr)` and reads `budgetExistsErr.ExistingBudgetID` — the field name matches exactly.

**Lazy template creation confirmed:** `CreateTemplateItem` uses `INSERT INTO templates (user_id) VALUES ($1) ON CONFLICT (user_id) DO UPDATE SET updated_at = now() RETURNING id` — template is created automatically on first item add.

**Empty template return confirmed:** `GetTemplate` returns `&models.TemplateDetail{Items: []models.TemplateItem{}}` (not nil, not an error) when no template row exists, allowing the frontend to render an empty state without special error handling.

---

_Verified: 2026-03-12_
_Verifier: Claude (gsd-verifier)_