# 08 — Implementation Plan (Phases 2–10)

Each phase ends with: run tests, run lint, build, fix all errors, verify
`docker compose up -d` still works end-to-end for whatever exists so far.
No phase starts until the previous one is green.

## Phase 2 — Bootstrap project & Docker Compose

- npm/pnpm workspace scaffold (`apps/server`, `apps/web`, `packages/shared`)
- Fastify skeleton with the two listeners (8080/8081), `/health`, `/ready`
- Vite + React + Tailwind skeleton, dark theme tokens, empty shell page
- Drizzle configured against Postgres; `docker-compose.yml` (dev) brings up
  `notizarr` (hot-reload) + `notizarr-postgres`
- `Dockerfile` (multi-stage: build web → build server → copy web dist into
  server's static dir → slim runtime image), non-root user, healthcheck
  script
- **Exit criteria:** `docker compose up -d` succeeds, `notizarr-postgres` is
  healthy, `GET :8080/health` returns 200, empty React shell loads.

## Phase 3 — Database + backend API skeleton

- All tables from `03-database-model.md` as Drizzle schema + migrations
- CRUD-level modules for `topics`, `notifications` (insert, list, get) with
  no auth yet (stubbed), so the data layer can be exercised
- OpenAPI schema generation wired up, `/docs` serving it
- Unit tests for schema constraints (unique slugs, FK cascades, retention
  math)
- **Exit criteria:** migrations run clean on a fresh DB; can insert/list a
  topic and a notification via the API without auth.

## Phase 4 — Authentication + API tokens

- OIDC module (`openid-client`): login/callback/logout, PKCE, state/nonce
  validation, session cookie issuance, bootstrap-first-admin logic
- Proxy-auth module: trusted-CIDR check, header parsing, session creation
- `AUTH_MODE=disabled` (local dev convenience: single implicit admin user)
- API token module: create/list/revoke/rotate, hashing, scoping
  (topics/source/CIDR/expiry), last-used tracking
- CSRF protection (Origin check + custom header) on listener A mutations
- Tests: each auth mode, token scope enforcement, revoked/expired token
  rejection, CSRF rejection on cross-origin mutation attempts
- **Exit criteria:** MVP criteria #5–7 (auth works, admin can create a
  topic, admin can create a scoped token) pass manually and via tests.

## Phase 5 — Notification ingestion + history

- Listener B: canonical publish endpoint, `/api/v1/topics/:slug` alias,
  ntfy-compat endpoint, webhook endpoint
- Rate limiter (per-token, per-IP), `INGESTION_ALLOWED_CIDRS` enforcement
- Deduplication logic, occurrence_count increment
- SSE stream on listener A (`notification.created`/`updated` events)
- Read/unread + starred state, unread-count aggregation per topic
- Retention cleanup interval job
- Tests: ingestion auth/scoping, rate limiting (burst + sustained), dedup
  window behavior, SSE fan-out, retention deletion
- **Exit criteria:** MVP criteria #8–10 (LAN client can publish, appears
  instantly via SSE, persisted) pass.

## Phase 6 — Frontend UI

- Navigation shells: mobile bottom nav (Inbox/Topics/Search/Starred/
  Settings), desktop sidebar + stream + optional detail panel
- Topic list (unread/total/latest, bell state), topic settings screen
  (push ON/OFF toggle)
- Notification list (cards per spec), notification detail
  (`/topics/:slug/messages/:id`), search + filters
- Empty states, loading skeletons, dark-first theme, responsive breakpoints
- Manual + automated visual smoke checks in the Browser tool (mobile and
  desktop viewport)
- **Exit criteria:** MVP criteria #22 (polished on iPhone and desktop) —
  judged by hand in the browser tool at this stage, refined further in
  Phase 7/8.

## Phase 7 — PWA + Web Push

- `vite-plugin-pwa` with `injectManifest`, manifest.webmanifest, icon set
  (incl. maskable + apple-touch-icon), safe-area CSS
- Service worker: precache, runtime caching, `push`/`notificationclick`
  handlers
- VAPID generation/storage in `system_settings`, `web-push` send integration
  wired into the Phase 5 fan-out step (previously a no-op stub)
- Subscribe/unsubscribe flow, devices screen, diagnostics screen
- Manual iPhone test pass (install to Home Screen, enable notifications,
  trigger a real push, confirm deep link opens the right message)
- **Exit criteria:** MVP criteria #11–18 (PWA installable, push permission,
  subscription stored, push ON sends / OFF doesn't, arrives on iPhone,
  tapping opens exact notification) pass.

## Phase 8 — Admin UI + rate limiting polish + diagnostics

- Admin dashboard widgets (`04-api-design.md`'s `/admin/stats/dashboard`)
- Noisy-source detection thresholds + admin warnings
- Tokens/Users/Devices/Push/Security/System admin screens
- Audit log viewer
- Settings screens (user + admin) per `01-architecture.md`
- **Exit criteria:** full admin IA from the spec is navigable and
  functional; rate-limit rejections are visible end-to-end (trigger one,
  see it flagged).

## Phase 9 — Migration helpers + ntfy compatibility hardening

- `docs/migration-ntfy.md`: side-by-side ntfy → Notizarr endpoint mapping
- `docs/home-assistant.md`: `rest_command` example replacing `ntfy.publish`
  (as given in the spec), plus one example per currently-used service
  (Seerr, Uptime Kuma, generic webhook)
- Compatibility test matrix: header-based, JSON-based, query-param-based
  ntfy-style requests all produce equivalent stored notifications
- **Exit criteria:** MVP criteria #8 re-verified using an ntfy-style request
  shape, not just the canonical API.

## Phase 10 — Testing + hardening + documentation

- Fill any remaining gaps in the automated test list from the original spec
  (stale push subscription cleanup, device removal, authorization matrix
  across roles, retention cleanup edge cases)
- Security pass: CSP, HSTS, frame-ancestors, request size limits, dependency
  audit
- Top-level `README.md`: install, configure `.env`, deploy on Unraid,
  backup/restore, troubleshooting (linking the diagnostics screen)
- Full MVP acceptance checklist run end-to-end, including container
  restart persistence checks (#19–21)
- **Exit criteria:** all 22 MVP acceptance criteria pass.

## Cross-cutting, done incrementally rather than as a separate phase

- Structured logging + secret redaction: introduced in Phase 2, extended as
  new modules land
- Metrics: introduced alongside the ingestion endpoints in Phase 5
- Lint/typecheck/test/build as CI-equivalent local commands: set up in
  Phase 2, run at the end of every subsequent phase