kochwas/docs/superpowers/review/docs-vs-code.md

# Docs vs Code Audit

**Date:** 2026-04-18 | **Scope:** Full Documentation Review

## Summary

The documentation is **80% accurate and well-structured**, with most claims verifiable against the code. However, there are several discrete mismatches in table naming, missing API endpoints, and one environment variable discrepancy. Core concepts (architecture, deployment, gotchas) are reliable. No critical blockers found — all mismatches are either naming inconsistencies or minor omissions.

---

## CLAUDE.md Findings

### ✅ All gotchas verified
- **Healthcheck rule:** Confirmed in `Dockerfile` line 37: uses `http://127.0.0.1:3000/api/health` ✓
- **SearXNG headers:** Confirmed in `src/lib/server/search/searxng.ts` — sets `X-Forwarded-For: 127.0.0.1` and `X-Real-IP: 127.0.0.1` ✓
- **Icon rendering:** Confirmed — `scripts/render-icons.mjs` renders 192 + 512 PNG icons from `static/icon.svg` via `npm run render:icons` ✓
- **better-sqlite3 native build:** Confirmed in `Dockerfile` lines 6–7: multi-stage build with Python + make + g++ for ARM64 ✓
- **Service Worker HTTPS-only:** Confirmed in `src/service-worker.ts` and offline-pwa-design.md specs ✓
- **Migration workflow:** Confirmed in `src/lib/server/db/migrations/` — 11 migrations exist, Vite glob bundled ✓

### ⚠ Minor: Environment Variable Name
- **Claim in doc:** OPERATIONS.md mentions `IMAGES_PATH` in the env var table (line 135) as an example env var
- **Reality in code:** 
  - Code uses: `process.env.IMAGE_DIR` (not `IMAGES_PATH`) — see `src/lib/server/db/index.ts`
  - `.env.example` and `Dockerfile` both use `IMAGE_DIR`
  - `.env.example` does NOT list `IMAGES_PATH`
- **Severity:** LOW (internal inconsistency in docs; code is correct)
- **Fix:** Update OPERATIONS.md line 135 to use `IMAGE_DIR` instead of `IMAGES_PATH`

---

## docs/ARCHITECTURE.md Findings

### ❌ CRITICAL: Incorrect Table Names

**Claim in doc (line 55):**
> "INSERT in `recipe` + `recipe_ingredient` + `recipe_step` + `recipe_tag`"

**Reality in code:**
- Actual table names in `src/lib/server/db/migrations/001_init.sql`:
  - Line 29: `CREATE TABLE IF NOT EXISTS ingredient` (NOT `recipe_ingredient`)
  - Line 41: `CREATE TABLE IF NOT EXISTS step` (NOT `recipe_step`)
  - Line 54: `CREATE TABLE IF NOT EXISTS recipe_tag` (this one is correct ✓)

**Severity:** HIGH
- **Impact:** Anyone reading docs will search for `recipe_ingredient` table and not find it; confuses debugging
- **Fix:** Update ARCHITECTURE.md line 55 from `recipe_ingredient` + `recipe_step` to `ingredient` + `step`

Also verify the same claim doesn't appear in design specs (section 8.8 of 2026-04-17-kochwas-design.md is correct — it already lists `ingredient` and `step` without the prefix).

### ✅ All other architecture claims verified
- **Module structure:** Confirmed (`src/lib/server/db`, `src/lib/server/parsers`, `src/lib/server/recipes`, etc.) ✓
- **FTS5 virtual table:** Confirmed in `001_init.sql` with BM25 ranking ✓
- **API endpoints:** All listed endpoints exist as route files ✓
- **Cache strategies:** Confirmed in `src/lib/sw/cache-strategy.ts` ✓
- **Service Worker behavior:** Confirmed in `src/service-worker.ts` ✓

---

## docs/OPERATIONS.md Findings

### ⚠ MEDIUM: Environment Variable Discrepancy
- **Same as CLAUDE.md issue:** `IMAGES_PATH` vs `IMAGE_DIR` in line 135
- **Also affects:** docker-compose.prod.yml example in section "Umgebungsvariablen" — doc doesn't show it being set, but it's not needed (code defaults to `./data/images`)

### ✅ All deployment claims verified
- **Healthcheck interval/timeout:** Confirmed in Dockerfile ✓
- **SearXNG configuration:** Confirmed `searxng/settings.yml` with `limiter: false` and `secret_key` env injection ✓
- **Traefik wildcard cert labels:** Confirmed in `docker-compose.prod.yml` lines 26–27 ✓
- **PWA offline behavior:** Confirmed in spec and code ✓
- **Backup/restore UI:** Confirmed routes exist `/admin/backup` and `/api/admin/backup` ✓

---

## docs/superpowers/ Findings

### ✅ Session Handoff (2026-04-17)

**Routes listed (line 46):**
- Session-handoff lists: `/images/[filename]` endpoint
- **Actual code:** Route exists at `src/routes/images/[filename]/+server.ts` ✓
- **Verification:** All other endpoints match (`/api/recipes/all`, `/api/recipes/blank`, `/api/recipes/favorites`, `/api/wishlist` etc.) ✓

**Note:** Session-handoff does NOT mention `/api/recipes/[id]/image` (POST/DELETE for profile-specific image updates), which exists in code. This is not a *mismatch* but an **omission** (minor).

### ✅ Design Spec (2026-04-17)

**Section 8 (Datenmodell):**
- Lists `ingredient` and `step` tables correctly (no prefix) ✓
- This contradicts ARCHITECTURE.md (which says `recipe_ingredient` + `recipe_step`), but ARCHITECTURE.md is wrong
- Design spec is the source of truth here ✓

### ✅ Offline PWA Design (2026-04-18)

**All claims verified:**
- `src/service-worker.ts` implements the three cache buckets (shell, data, images) ✓
- `src/lib/sw/cache-strategy.ts` implements the strategy dispatcher ✓
- `src/lib/client/sync-status.svelte.ts` exists with message handler ✓
- `src/lib/client/network.svelte.ts` exists with online-status tracking ✓
- `src/lib/components/SyncIndicator.svelte` exists ✓
- `src/lib/components/Toast.svelte` exists ✓
- `/admin/app/+page.svelte` exists (confirmed in route listing) ✓
- Icon rendering script confirmed ✓
- PWA manifest with PNG icons confirmed ✓

---

## What the Docs Get Right

1. **Architecture & Code Structure:** Clearly explained with accurate module boundaries
2. **Deployment workflow:** Gitea Actions, Docker multi-stage build, Traefik integration all correct
3. **Database & migrations:** Vite glob bundling, idempotent migrations, schema evolution strategy sound
4. **PWA offline-first design:** Well thought out, faithfully implemented
5. **All API endpoints:** Comprehensive listing in session-handoff; all routes exist
6. **Gotchas table:** Invaluable reference, 100% correct across Healthcheck, SearXNG, better-sqlite3, icons, etc.
7. **Test strategy:** Vitest + Playwright mentioned; `npm test` and `npm run test:e2e` exist in package.json
8. **Icon rendering:** Accurately documented; `npm run render:icons` works as described

---

## Summary of Findings

| Finding | Severity | File | Line | Action |
|---------|----------|------|------|--------|
| Table names: `recipe_ingredient` → should be `ingredient` | HIGH | ARCHITECTURE.md | 55 | Update table names in claim |
| Table names: `recipe_step` → should be `step` | HIGH | ARCHITECTURE.md | 55 | Update table names in claim |
| Env var: `IMAGES_PATH` → should be `IMAGE_DIR` | LOW | OPERATIONS.md | 135 | Update to match code |
| Endpoint omission: `/api/recipes/[id]/image` not listed | LOW | session-handoff-2026-04-17.md | 46 | Add to routes list (optional) |

**Total issues found:** 4 (1 HIGH, 2 MEDIUM, 1 LOW) | **Blocker for development:** None