# WishNinja — Design (original plan)

> **Status:** This is the original pre-implementation design, kept for posterity. The build
> followed it closely, but a few details evolved during implementation. For the current state of
> the code, the README and the git history are authoritative. Notable deltas from this document:
>
> - **Item images are always stored locally.** Pasted URLs are downloaded server-side and saved as
>   files; the `ImageKind.ExternalUrl` value and `WishlistItem.ImageUrl` column were removed.
> - **Ordering:** list queries order by `Id` (not `CreatedAt`), because SQLite cannot `ORDER BY`
>   a `DateTimeOffset` column.
> - **Connection string:** derived from `WishNinja__DataPath` (default `/data`); override via
>   `ConnectionStrings__DefaultConnection` (not `ConnectionStrings__Default`).
> - **CI registry auth:** uses a `REGISTRY_TOKEN` PAT secret, not the auto-provided token.
> - **Seeder:** implemented as `Services/StartupInitializer.cs` (migrate + seed roles + admin),
>   not `AdminSeeder.cs`.
> - **Container** runs as root for hassle-free Unraid bind-mount permissions (the "non-root" note
>   below was not adopted).

---

## Context

The user runs an Unraid home server hosting many self-hosted apps and wants a **new gift
wishlist manager** ("WishNinja") that ships as a **Docker image** and lives in their
self-hosted **Gitea** instance. The working directory was empty — a clean greenfield build.

The app lets a closed group (family/friends) create wishlists, add items with links/prices/
images, and **claim/reserve gifts so the owner never sees what's been claimed** (preserving the
surprise) while other viewers do (avoiding duplicate gifts). Users are managed internally with
email-based password resets.

### Confirmed decisions
- **Stack:** ASP.NET Core **Blazor Web App** (interactive **server** render mode), **.NET 10 LTS**.
- **Persistence:** **SQLite** via **EF Core**, single DB file on a mounted volume.
- **Auth:** **ASP.NET Core Identity** with internal accounts + email password resets.
- **Onboarding:** **Admin invites only** (no open self-registration).
- **Claim privacy:** **Claims hidden from the list owner**; visible to other viewers.
- **Item images:** **file upload + clipboard paste** (both stored locally on `/data`) **+ external URL**.
- **Delivery:** Docker image, built via Gitea Actions → Gitea container registry, run on Unraid.

---

## Architecture & Stack

| Concern | Choice |
|---|---|
| Framework | ASP.NET Core 10 (LTS), Blazor Web App, InteractiveServer render mode |
| ORM / DB | EF Core 10 + SQLite (`Microsoft.EntityFrameworkCore.Sqlite`) |
| Identity | ASP.NET Core Identity (cookie auth, roles: `Admin`, `User`) |
| Email | `MailKit` for SMTP (password reset + invite emails) |
| Data Protection | Keys persisted to `/data/keys` so cookies/antiforgery survive restarts |
| Image storage | Local files under `/data/uploads`; served via a static-files mapping |
| Container base | `mcr.microsoft.com/dotnet/aspnet:10.0` (Debian slim), built from `sdk:10.0` |

**Why Blazor Server interactivity:** all-C#, single container, no separate JS build, live claim
buttons. Reverse proxy must allow **WebSocket upgrades** (SignalR) — documented in the README.

---

## Data Model (EF Core entities)

- **ApplicationUser : IdentityUser** — adds `DisplayName`, `CreatedAt`.
- **Wishlist** — `Id`, `OwnerId` (FK user), `Title`, `Description`, `Visibility`
  (`AllMembers` | `SpecificUsers`), `IsArchived`, `CreatedAt`.
- **WishlistShare** — `WishlistId`, `UserId` (rows only when `Visibility = SpecificUsers`).
- **WishlistItem** — `Id`, `WishlistId`, `Name`, `Description`, `ProductUrl`, `ImageKind`,
  `ImagePath`, `Price`, `Priority`, `Quantity`, `SortOrder`, `CreatedAt`.
- **Claim** — `Id`, `WishlistItemId`, `ClaimedByUserId`, `Quantity`, `Note`, `CreatedAt`.
- **Invite** — `Id`, `Email`, `TokenHash`, `Role`, `InvitedByUserId`, `ExpiresAt`, `AcceptedAt`.

EF migrations applied automatically at startup for friction-free self-hosting.

---

## Core Features

### Wishlists & items
- CRUD wishlists; set visibility (all members / specific users via `WishlistShare`).
- CRUD items with name, description, product link, price, priority, quantity, image.
- Item images via three inputs, all stored locally:
  - **File upload** → saved to `/data/uploads`, `ImageKind=Uploaded`.
  - **Clipboard paste** → JS-interop `paste` handler captures the blob, uploads via the same path.
  - **Image URL** → downloaded server-side and saved as a local file.
  - Upload validation: allowlist content types (png/jpeg/webp/gif), size cap, GUID filenames.

### Claim / reservation (owner-hidden)
- Any member viewing a list they **don't own** sees each item's claim state and can claim/
  unclaim (respecting `Quantity`).
- The **owner's view of their own list never loads or renders claim data** — enforced at the
  query layer, not just hidden in the UI, so it can't leak via timing/DOM. This is the single most
  important correctness rule and gets dedicated unit tests.

### Auth & onboarding (admin-invite-only)
- Self-registration disabled. Admin invites by email → emailed invite link with a one-time token
  → recipient sets `DisplayName` + password → account created with `User` role.
- First-run **admin seeding** from env vars (`SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD`).
- Password reset via Identity's token flow + MailKit SMTP email.
- Admin area: list/disable users, manage invites.

---

## Verification
- **Automated:** `dotnet test` — owner queries never return claim data; non-owner queries do;
  invite token single-use/expiry; image upload type/size validation; list queries run on SQLite.
- **Container:** `docker compose up --build`; verify SQLite DB + uploads persist across restarts
  via the `/data` volume.
- **Unraid:** deploy image, map appdata volume + port, place behind reverse proxy with WebSockets
  enabled, confirm Blazor interactivity (claim button) works through the proxy.