# Notizarr — Phase 1 Design Package

This is the Phase 1 deliverable: architecture, threat model, data model, API
design, PWA/Web Push design, Docker/Unraid design, folder structure, and the
phased implementation plan. **No application code is written in this phase.**
Per the project's own process rules, implementation (Phase 2+) does not start
until this package is reviewed and the open decisions below are confirmed.

## Documents

1. [01-architecture.md](01-architecture.md) — components, containers, data flow
2. [02-threat-model.md](02-threat-model.md) — trust boundaries, STRIDE notes, mitigations
3. [03-database-model.md](03-database-model.md) — full Postgres schema
4. [04-api-design.md](04-api-design.md) — public app API + LAN ingestion API
5. [05-pwa-web-push-design.md](05-pwa-web-push-design.md) — manifest, service worker, push flow, iOS notes
6. [06-docker-unraid-design.md](06-docker-unraid-design.md) — compose design, volumes, networking
7. [07-folder-structure.md](07-folder-structure.md) — repo layout vs. deployment layout
8. [08-implementation-plan.md](08-implementation-plan.md) — Phase 2–10 task breakdown, mapped to MVP acceptance criteria

## Open decisions that need your sign-off before Phase 2

These are the "major implementation decisions" the process asks to pause on:

| # | Decision | Recommendation | Why |
|---|---|---|---|
| 1 | Backend language/framework | **Node.js 22 + TypeScript, Fastify** | One language across front+back end for a solo-maintained homelab app; `web-push` and `openid-client` are the most mature libraries for the two hardest requirements (Web Push, OIDC); Fastify has first-class schema validation and low overhead. |
| 2 | ORM / migrations | **Drizzle ORM + drizzle-kit** | Typesafe, SQL-first, no native binary/engine (unlike Prisma) — simpler in a small Alpine container, plain-SQL migration files you can read and back up. |
| 3 | Realtime "instant in UI" delivery | **Server-Sent Events (SSE)**, in-process pub/sub, no Redis | Single-instance app; SSE is one-way (all we need), works over plain HTTP through a reverse proxy, avoids the complexity of a WebSocket + no new infra. |
| 4 | VAPID key storage | **Postgres `system_settings` table**, generated on first boot if absent | Already-durable volume; no separate key file to remember to back up — `pg_dump` covers it automatically. |
| 5 | Attachments / image handling | **No server-side fetch or proxy.** `image_url`/`external_url` are stored as plain URLs and loaded directly by the browser (`<img src>`), never fetched by the server. | Eliminates SSRF risk entirely for this feature per the security requirements, at the cost of not supporting file uploads in v1 (can be added later as an explicit, scoped feature). |
| 6 | Webhook mapping | MVP ships a **fixed simple mapping** (`{topic, title, message, url?}` JSON body, or ntfy-style headers), not a configurable templating engine | Spec says "goal is easy migration, not full protocol cloning"; a mapping UI is called out as a later enhancement. |
| 7 | Topic access control | Topics are **visible to all authenticated users by default**; an admin can mark a topic `restricted` and grant per-user access | Matches "single/small household" simplicity principle while still satisfying "users can browse allowed topics." |

If any of these should go differently, say so and I'll adjust the design before Phase 2 starts. Otherwise, confirming this package moves us into Phase 2 (repo bootstrap + Docker Compose skeleton).