# Requirements: DiunDashboard

**Defined:** 2026-03-23
**Core Value:** Reliable, persistent visibility into which services need updating — data never disappears, and the dashboard is the one place you trust to show the full picture.

## v1 Requirements

Requirements for this milestone. Each maps to roadmap phases.

### Data Integrity

- [x] **DATA-01**: Webhook events use proper UPSERT (ON CONFLICT DO UPDATE) instead of INSERT OR REPLACE, preserving tag assignments when an image receives a new event
- [x] **DATA-02**: SQLite foreign key enforcement is enabled (PRAGMA foreign_keys = ON) so tag deletion properly cascades to tag assignments
- [ ] **DATA-03**: Webhook and API endpoints enforce request body size limits (e.g., 1MB) to prevent OOM from oversized payloads
- [ ] **DATA-04**: Test error handling uses t.Fatal instead of silent returns, so test failures are never swallowed

### Backend Refactor

- [ ] **REFAC-01**: Database operations are behind a Store interface with separate SQLite and PostgreSQL implementations
- [ ] **REFAC-02**: Package-level global state (db, mu, webhookSecret) is replaced with a Server struct that holds dependencies
- [ ] **REFAC-03**: Schema migrations use golang-migrate with separate migration directories per dialect (sqlite/, postgres/)

### Database

- [ ] **DB-01**: PostgreSQL is supported as an alternative to SQLite via pgx v5 driver
- [ ] **DB-02**: Database backend is selected via DATABASE_URL env var (present = PostgreSQL, absent = SQLite with DB_PATH)
- [ ] **DB-03**: Existing SQLite users can upgrade without data loss (baseline migration represents current schema)

### Bulk Actions

- [ ] **BULK-01**: User can acknowledge all pending updates at once with a single action
- [ ] **BULK-02**: User can acknowledge all pending updates within a specific tag/group

### Search & Filter

- [ ] **SRCH-01**: User can search updates by image name (text search)
- [ ] **SRCH-02**: User can filter updates by status (pending vs acknowledged)
- [ ] **SRCH-03**: User can filter updates by tag/group
- [ ] **SRCH-04**: User can sort updates by date, image name, or registry

### Update Indicators

- [ ] **INDIC-01**: Dashboard shows a badge/counter of pending (unacknowledged) updates
- [ ] **INDIC-02**: Browser tab title includes pending update count (e.g., "DiunDash (3)")
- [ ] **INDIC-03**: In-page toast notification appears when new updates arrive during polling
- [ ] **INDIC-04**: Updates that arrived since the user's last visit are visually highlighted

### Accessibility & Theme

- [ ] **A11Y-01**: Light/dark theme toggle with system preference detection (prefers-color-scheme)
- [ ] **A11Y-02**: Drag handle for tag reordering is always visible (not hover-only)

## v2 Requirements

Deferred to future milestone. Tracked but not in current roadmap.

### Auto-Grouping

- **GROUP-01**: Images are automatically grouped by Docker stack/compose project
- **GROUP-02**: Auto-grouping source is configurable (Docker socket, DIUN metadata, manual)

### DIUN Integration

- **DIUN-01**: DIUN and dashboard deploy as a single stack
- **DIUN-02**: Visual UI for managing DIUN notification channels
- **DIUN-03**: Visual UI for managing DIUN watched images

### Additional UX

- **UX-01**: Data retention with configurable TTL for acknowledged entries
- **UX-02**: Alternative tag assignment via dropdown (non-drag method)
- **UX-03**: Keyboard shortcuts for common actions
- **UX-04**: Browser notification API for background tab alerts
- **UX-05**: Filter by registry

## Out of Scope

| Feature | Reason |
|---------|--------|
| Auto-triggering image pulls or container restarts | Dashboard is a viewer, not an orchestrator; Docker socket access is a security risk |
| Notification channel management UI | DIUN already handles this; duplicating creates config drift |
| OAuth / multi-user accounts | Single-user self-hosted tool; reverse proxy auth is sufficient |
| Real-time WebSocket / SSE | 5s polling is adequate for low-frequency update signals |
| Mobile-native / PWA | Responsive web design is sufficient for internal tool |
| Changelog or CVE lookups per image | Requires external API integrations; different product scope |
| Undo for dismiss actions | Next DIUN scan recovers dismissed items; state complexity not justified |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DATA-01 | Phase 1 | Complete |
| DATA-02 | Phase 1 | Complete |
| DATA-03 | Phase 1 | Pending |
| DATA-04 | Phase 1 | Pending |
| REFAC-01 | Phase 2 | Pending |
| REFAC-02 | Phase 2 | Pending |
| REFAC-03 | Phase 2 | Pending |
| DB-01 | Phase 3 | Pending |
| DB-02 | Phase 3 | Pending |
| DB-03 | Phase 3 | Pending |
| BULK-01 | Phase 4 | Pending |
| BULK-02 | Phase 4 | Pending |
| SRCH-01 | Phase 4 | Pending |
| SRCH-02 | Phase 4 | Pending |
| SRCH-03 | Phase 4 | Pending |
| SRCH-04 | Phase 4 | Pending |
| INDIC-01 | Phase 4 | Pending |
| INDIC-02 | Phase 4 | Pending |
| INDIC-03 | Phase 4 | Pending |
| INDIC-04 | Phase 4 | Pending |
| A11Y-01 | Phase 4 | Pending |
| A11Y-02 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 22 total
- Mapped to phases: 22
- Unmapped: 0

---
*Requirements defined: 2026-03-23*
*Last updated: 2026-03-23 after roadmap creation*