**docs:** update README.md and .claude/CLAUDE.md with new features, architecture, and API changes

- Reflect addition of React SPA, SQLite persistence, and tag management
- Update quick start guide for backend and frontend setup
- Document full API routes and database schema
- Revise project structure for recent refactor
- Improve production and testing notes for clarity

.claude/CLAUDE.md

@@ -9,7 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 go test -v -coverprofile=coverage.out -coverpkg=./... ./...
 
 # Run a single test
-go test -v -run TestWebhookHandler ./test/diunwebhook/
+go test -v -run TestWebhookHandler ./pkg/diunwebhook/
 
 # Run the app locally
 go run ./cmd/diunwebhook/
@@ -19,22 +19,44 @@ docker build -t diun-webhook-dashboard .
 
 # Run with Docker Compose
 docker compose up -d
+
+# Frontend (from frontend/ directory)
+bun install          # install deps
+bun run dev          # dev server on :5173 (proxies /api and /webhook to :8080)
+bun run build        # production build → frontend/dist/
 ```
 
 CI warns (but does not fail) when coverage drops below 80%.
 
 ## Architecture
 
-The app is a minimal Go HTTP server that receives [DIUN](https://crazymax.dev/diun/) webhook events and exposes them via a JSON API and static HTML dashboard. All states are in-memory (no persistence).
+The app is a Go HTTP server that receives [DIUN](https://crazymax.dev/diun/) webhook events and exposes them via a JSON API and a React SPA dashboard. Events are persisted to a SQLite database (`diun.db`) using `modernc.org/sqlite` (pure Go, no CGO).
 
 **Package layout:**
-- `pkg/diunwebhook/` — core library: `DiunEvent` struct, in-memory `updates` map (guarded by `sync.Mutex`), and HTTP handlers (`WebhookHandler`, `UpdatesHandler`)
-- `cmd/diunwebhook/main.go` — wires the handlers and static file server onto `net/http`'s default mux, listens on `:8080`
-- `test/diunwebhook/` — external test package (`package diunwebhook_test`) that imports `pkg/diunwebhook`; uses `httptest` for handler tests
-- `static/` — served verbatim at `/`
+- `pkg/diunwebhook/` — core library: `DiunEvent`, `UpdateEntry`, and `Tag` structs; SQLite-backed storage (guarded by `sync.Mutex`); HTTP handlers (`WebhookHandler`, `UpdatesHandler`, `DismissHandler`, `TagsHandler`, `TagByIDHandler`, `TagAssignmentHandler`)
+- `cmd/diunwebhook/main.go` — calls `InitDB()`, wires handlers onto `net/http`'s default mux, serves `./frontend/dist` at `/`, listens on `:8080` (overridable via `PORT` env var), graceful shutdown
+- `pkg/diunwebhook/diunwebhook_test.go` — external test package (`package diunwebhook_test`); uses `httptest` for handler tests
+- `pkg/diunwebhook/export_test.go` — test-only exports
+- `frontend/` — React SPA (Bun + Vite + React 19 + Tailwind CSS + shadcn/ui + dnd-kit)
+
+**Database schema (SQLite):**
+- `updates` — one row per image (PRIMARY KEY `image`), stores full event fields plus `received_at` and `acknowledged_at`
+- `tags` — user-defined tag/group names (`id` INTEGER PK, `name` UNIQUE)
+- `tag_assignments` — maps `image` → `tag_id` (FK with CASCADE delete)
+
+**API routes:**
+- `POST /webhook` — accept a DIUN event
+- `GET /api/updates` — return all events (with tag and acknowledged state)
+- `PATCH /api/updates/{image}` — mark an event as acknowledged (dismiss)
+- `GET /api/tags` — list all tags
+- `POST /api/tags` — create a tag
+- `DELETE /api/tags/{id}` — delete a tag (cascades to assignments)
+- `PUT /api/tag-assignments` — assign an image to a tag
+- `DELETE /api/tag-assignments` — unassign an image from its tag
 
 **Key data flow:**
-1. DIUN POSTs JSON to `/webhook` → `WebhookHandler` decodes into `DiunEvent` → stored in `updates[event.Image]` (the latest event per image wins)
-2. Dashboard JS polls `GET /api/updates` → `UpdatesHandler` returns a full map as JSON
+1. DIUN POSTs JSON to `/webhook` → `WebhookHandler` decodes into `DiunEvent` → upserted into `updates` table (latest event per image wins, resets acknowledged state)
+2. React SPA polls `GET /api/updates` every 5 s → `UpdatesHandler` returns map of `UpdateEntry` (includes event, received time, acknowledged flag, and optional tag)
+3. User can dismiss updates via `PATCH /api/updates/{image}` and organize images into tag groups via the tag/assignment endpoints
 
-**Test helpers exposed from the library package** (not part of the public API, only for tests): `GetUpdatesMap()`, `UpdatesReset()`, `UpdateEvent()`.
+**Test helpers exposed from the library package** (not part of the public API, only for tests): `GetUpdatesMap()`, `UpdatesReset()`, `UpdateEvent()`, `ResetTags()`.