webref/specs/001-reference-board-viewer/plan.md

# Plan: Reference Board Viewer

**Created:** 2025-11-02  
**Status:** Active  
**Owner:** Development Team  

## Overview

This plan outlines the implementation strategy for building a web-based reference board application (PureRef-inspired) for artists and creative professionals. The application will enable users to collect, organize, and manipulate visual reference images collaboratively through any modern web browser, with full Nix deployment support.

**Why This Matters:**
- Fills gap in market for collaborative, accessible reference board tools
- Enables remote creative collaboration
- Provides artists with professional-grade tools without desktop software
- Demonstrates modern web capabilities with Nix deployment

## Objectives

- [ ] Build a performant web application supporting 500+ images at 60fps
- [ ] Implement 18 functional requirements from specification
- [ ] Achieve ≥80% test coverage across frontend and backend
- [ ] Deploy reproducibly using Nix to self-hosted infrastructure
- [ ] Complete development in 12-16 weeks
- [ ] Validate with beta users and achieve 90%+ "easy to use" rating

## Constitution Alignment Check

Before proceeding, verify alignment with constitutional principles:

- **Code Quality & Maintainability:** How will this maintain/improve code quality?
  - [x] Design follows single responsibility principle (modular architecture: frontend, backend, storage, database)
  - [x] Clear module boundaries defined (see architecture diagram below)
  - [x] Dependencies justified and documented (see tech-research.md)
  - [x] Type hints enforced (Python: Pydantic models, Optional: TypeScript for frontend)
  - [x] Linting configured (Ruff for Python, ESLint for JavaScript)
  
- **Testing Discipline:** What testing strategy will ensure correctness?
  - [x] Unit test coverage plan (≥80%): pytest for backend, Vitest for frontend
  - [x] Integration test scenarios identified (API endpoints, canvas operations, file uploads)
  - [x] Edge cases documented (large files, concurrent uploads, 500+ images, network failures)
  - [x] E2E tests for critical flows (user registration → board creation → image upload → export)
  
- **User Experience Consistency:** How does this impact users?
  - [x] UI/API changes follow existing patterns (RESTful API, intuitive canvas interactions)
  - [x] Error handling is user-friendly (clear messages, actionable feedback, no raw exceptions)
  - [x] Documentation plan complete (API docs via OpenAPI, user guide, inline help)
  - [x] Accessibility validated (WCAG 2.1 AA compliance testing with axe-core)
  
- **Performance & Efficiency:** What are the performance implications?
  - [x] Performance budget established (60fps canvas, <200ms API, <3s page load)
  - [x] Algorithmic complexity analyzed (O(n) for rendering, O(log n) for spatial queries)
  - [x] Resource usage estimated (2GB RAM server, 100GB storage, 10Mbps bandwidth)

## Scope

### In Scope
**Core Features (MVP):**
- ✅ User authentication and account management (email/password)
- ✅ Board CRUD operations (create, read, update, delete, list)
- ✅ Image upload (file picker, drag-drop, paste, batch, ZIP)
- ✅ Canvas operations (infinite canvas, pan, zoom, rotate viewport)
- ✅ Image manipulation (drag, scale, rotate, crop, flip, opacity, greyscale)
- ✅ Multi-selection and bulk operations
- ✅ Image grouping with annotations and colored labels
- ✅ Z-order management (bring to front, send to back)
- ✅ Alignment and distribution tools (snap-to-grid)
- ✅ Copy/cut/paste/delete operations
- ✅ Focus mode and slideshow
- ✅ Export (single image, ZIP, composite image)
- ✅ Board sharing with configurable permissions (View-only, View+Comment)
- ✅ Adaptive image quality based on connection speed
- ✅ Image library with cross-board reuse
- ✅ Command palette (Ctrl+K/Cmd+K)
- ✅ Non-destructive editing (original always preserved)
- ✅ Auto-arrange by criteria (name, date, optimal, random)

**Deployment:**
- ✅ Full Nix deployment configuration (flake.nix + NixOS modules)
- ✅ Single-server deployment architecture
- ✅ PostgreSQL database setup
- ✅ MinIO or filesystem image storage
- ✅ Nginx reverse proxy configuration

**Testing & Quality:**
- ✅ ≥80% test coverage
- ✅ CI/CD pipeline with Nix
- ✅ Performance benchmarking
- ✅ Accessibility testing (WCAG 2.1 AA)

### Out of Scope
**Deferred to v2.0:**
- Real-time collaborative editing (multiple users editing same board simultaneously)
- Mobile app (native iOS/Android)
- Video/3D model support (only images in v1.0)
- Advanced image editing (filters, color correction beyond greyscale)
- Public board gallery/marketplace
- Team workspaces and role-based access control (only individual users + sharing)
- Custom branding/white-labeling
- Monetization features (payments, subscriptions)
- Multi-language support (English-only in v1.0)
- Offline mode (PWA with service workers)
- Third-party integrations (Google Drive, Dropbox, Pinterest)

## Technical Approach

### Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    CLIENT (Browser)                          │
│                                                              │
│  ┌────────────────────────────────────────────────────┐    │
│  │   Svelte Frontend (SvelteKit)                      │    │
│  │   ├─ UI Components (forms, modals, menus)         │    │
│  │   ├─ Konva.js Canvas (image manipulation)         │    │
│  │   ├─ Svelte Stores (state management)             │    │
│  │   └─ API Client (fetch wrapper)                   │    │
│  └────────────────────────────────────────────────────┘    │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTPS
                       │
┌──────────────────────▼───────────────────────────────────────┐
│              Nginx (Reverse Proxy / Static Files)            │
│  ├─ / → Frontend SPA (Svelte build)                         │
│  ├─ /api/* → FastAPI backend                                │
│  └─ /storage/* → MinIO or filesystem images                 │
└──────────────────────┬───────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼────────┐ ┌──▼──────────┐ ┌─▼──────────┐
│  FastAPI       │ │ PostgreSQL  │ │   MinIO    │
│  (Backend API) │ │ (Database)  │ │  (Images)  │
│                │ │             │ │            │
│ ┏━━━━━━━━━━━━┓ │ │ ┏━━━━━━━━┓ │ │ ┏━━━━━━━━┓ │
│ ┃ Auth       ┃ │ │ ┃ users  ┃ │ │ ┃ bucket/┃ │
│ ┃ Boards     ┃ │ │ ┃ boards ┃ │ │ ┃ images/┃ │
│ ┃ Images     ┃ │ │ ┃ images ┃ │ │ ┃ thumbs/┃ │
│ ┃ Upload     ┃ │ │ ┃ groups ┃ │ │ ┗━━━━━━━━┛ │
│ ┃ Processing ┃ │ │ ┃ shares ┃ │ │            │
│ ┗━━━━━━━━━━━━┛ │ │ ┗━━━━━━━━┛ │ │            │
└────────────────┘ └─────────────┘ └────────────┘
```

### Technology Stack (Finalized)

Based on comprehensive research (see [tech-research.md](./tech-research.md)), the stack is:

| Layer | Technology | Rationale |
|-------|-----------|-----------|
| **Frontend Framework** | Svelte + SvelteKit | Smallest bundle, no VDOM, truly reactive, excellent performance |
| **Canvas Library** | Konva.js | Optimized for interactive canvas, layering, event handling |
| **Backend Framework** | FastAPI (Python) | Async, fast, great DX, leverages existing Python setup |
| **Database** | PostgreSQL | JSONB support, full-text search, robust, Nix-friendly |
| **Image Storage** | MinIO (S3-compatible) | Self-hosted, future-proof, can migrate to cloud |
| **Image Processing** | Pillow + ImageMagick | Standard, reliable, excellent Nix support |
| **Auth** | JWT (python-jose + passlib) | Stateless, industry standard, secure |
| **Build Tool** | Vite | Fast HMR, optimized builds, Svelte plugin |
| **Package Manager** | uv (Python) + npm (JS) | Already in shell.nix, ultra-fast |
| **Deployment** | Nix Flakes + NixOS | Reproducible, declarative, rollback support |

### Key Components

#### 1. Frontend Application (Svelte + Konva.js)
**Purpose:** User interface and canvas manipulation

**Responsibilities:**
- Render UI components (forms, modals, menus, command palette)
- Manage canvas state (images, viewport, selection, groups)
- Handle user interactions (drag, resize, rotate, click, keyboard)
- Communicate with backend API
- Implement client-side validation
- Cache data for performance

**Key Modules:**
- `src/lib/canvas/` - Konva.js canvas wrapper, event handlers
- `src/lib/stores/` - Svelte stores (auth, boards, images, viewport)
- `src/lib/api/` - API client (fetch wrapper with auth)
- `src/lib/components/` - Reusable UI components
- `src/routes/` - SvelteKit routes (pages)

**Testing:**
- Unit tests: Vitest for stores, utility functions
- Component tests: Testing Library for UI components
- Integration tests: Canvas operations, API interactions
- E2E tests: Playwright for full user flows

---

#### 2. Backend API (FastAPI)
**Purpose:** Business logic, data persistence, image processing

**Responsibilities:**
- User authentication (registration, login, password reset)
- Board CRUD operations
- Image upload, processing (thumbnails), metadata storage
- Serve image files (proxy to MinIO or filesystem)
- Permission validation for board sharing
- API documentation (auto-generated OpenAPI)

**Key Modules:**
- `app/auth/` - Authentication, JWT, password hashing
- `app/boards/` - Board operations, sharing logic
- `app/images/` - Upload handling, processing, storage
- `app/database/` - SQLAlchemy models, migrations
- `app/api/` - API route handlers
- `app/core/` - Configuration, dependencies, middleware

**Testing:**
- Unit tests: pytest for business logic
- Integration tests: TestClient for API endpoints
- Database tests: pytest-postgresql for database operations
- Performance tests: locust for load testing

---

#### 3. Database (PostgreSQL)
**Purpose:** Persistent data storage

**Responsibilities:**
- Store user accounts (encrypted passwords)
- Store board metadata (title, owner, created/updated timestamps)
- Store image metadata (filename, dimensions, transformations, position)
- Store groups (annotations, color labels, member images)
- Store share links (tokens, permissions, access logs)
- Full-text search for image library

**Schema Outline:**
```sql
users (id, email, password_hash, created_at)
boards (id, user_id, title, description, viewport_state JSONB, created_at, updated_at)
images (id, user_id, filename, storage_path, metadata JSONB, created_at)
board_images (board_id, image_id, position JSONB, transformations JSONB, z_order, group_id)
groups (id, board_id, name, color, annotation, created_at)
share_links (id, board_id, token, permission_level, created_at, last_accessed, revoked)
```

**Migrations:** Alembic (SQLAlchemy migration tool)

---

#### 4. Image Storage (MinIO)
**Purpose:** Store and serve image files

**Responsibilities:**
- Store original images (full resolution)
- Store generated thumbnails (low, medium, high)
- Serve images via HTTP
- Handle erasure coding for durability
- Provide S3-compatible API for future cloud migration

**Bucket Structure:**
```
webref/
├── originals/
│   └── {user_id}/{image_id}.{ext}
└── thumbnails/
    ├── low/{image_id}.webp       (800px max)
    ├── medium/{image_id}.webp    (1600px max)
    └── high/{image_id}.webp      (3200px max)
```

---

#### 5. Image Processing Pipeline (Pillow + ImageMagick)
**Purpose:** Generate thumbnails and process uploads

**Responsibilities:**
- Validate uploaded files (format, size, content)
- Extract metadata (dimensions, format, EXIF)
- Generate multiple resolution thumbnails
- Optimize images for web (WebP format, quality tuning)
- Run as background tasks (don't block API responses)

**Process Flow:**
1. User uploads image → FastAPI receives file
2. FastAPI validates file → saves original to MinIO
3. Background task generates thumbnails (3 resolutions)
4. Thumbnails saved to MinIO
5. Database updated with metadata and paths

---

### Dependencies

#### External Dependencies (via Nix)
**Python (Backend):**
```nix
python3Packages = [
  fastapi           # Web framework
  uvicorn          # ASGI server
  sqlalchemy       # ORM
  alembic          # Database migrations
  pydantic         # Data validation
  python-jose      # JWT tokens
  passlib          # Password hashing
  pillow           # Image processing
  boto3            # S3/MinIO client
  python-multipart # File upload handling
  httpx            # Async HTTP client (for testing)
]
```

**JavaScript (Frontend):**
```json
{
  "svelte": "^4.2.0",
  "@sveltejs/kit": "^2.0.0",
  "konva": "^9.3.0",
  "vite": "^5.0.0"
}
```

**System Services:**
- PostgreSQL 16
- MinIO (latest)
- Nginx 1.24+
- ImageMagick 7

#### Internal Dependencies
- Frontend depends on Backend API (REST endpoints)
- Backend depends on Database (SQLAlchemy sessions)
- Backend depends on Image Storage (MinIO client)
- Image Processing depends on Background Task Queue (FastAPI BackgroundTasks)

### Risks & Mitigations

| Risk | Impact | Probability | Mitigation Strategy |
|------|--------|-------------|---------------------|
| Canvas performance degrades with 500+ images | High | Medium | Implement virtual rendering (only render visible images), use Konva layers efficiently, add pagination option |
| Large file uploads (50MB) timeout | High | Medium | Implement streaming uploads, chunked transfer encoding, increase Nginx timeout config, show progress bar |
| Nix deployment complexity | Medium | Medium | Create comprehensive documentation, provide example configs, test on multiple NixOS versions |
| Browser compatibility issues (Safari, older browsers) | Medium | Low | Define minimum browser versions, polyfills for older APIs, comprehensive cross-browser testing |
| Image processing bottleneck (many concurrent uploads) | High | Medium | Use Celery for distributed task queue (Phase 2), implement rate limiting, optimize Pillow settings |
| Database query performance (complex board queries) | Medium | Low | Add database indexes (GIN for JSONB), query optimization, consider Redis caching for hot data |
| Storage costs (100GB+ per user) | Low | Low | Implement storage quotas, image deduplication (same image on multiple boards), compression |
| Security vulnerabilities (file upload attacks) | High | Low | Strict file validation (magic bytes, not just extension), size limits, malware scanning (future), CSP headers |

## Implementation Phases

### Phase 1: Foundation & Core Infrastructure (Weeks 1-4)

**Goal:** Set up development environment, core architecture, and basic CRUD operations

#### Week 1: Project Setup & Nix Configuration
- [ ] Initialize Git repository with proper .gitignore
- [ ] Create Nix flake.nix with development environment
- [ ] Set up frontend project (SvelteKit + Vite)
- [ ] Set up backend project (FastAPI with uv)
- [ ] Configure PostgreSQL with Nix
- [ ] Set up pre-commit hooks (Ruff, ESLint, Prettier)
- [ ] Initialize CI/CD pipeline (GitHub Actions or similar)
- [ ] Create initial database schema (users, boards tables)

**Deliverables:**
- Working development environment (`nix develop`)
- Frontend dev server running (`npm run dev`)
- Backend dev server running (`uvicorn app.main:app --reload`)
- PostgreSQL accessible locally
- CI pipeline runs linters

#### Week 2: Authentication System
- [ ] Design user schema and JWT strategy
- [ ] Implement user registration endpoint
- [ ] Implement login endpoint (JWT token generation)
- [ ] Implement password hashing (bcrypt via passlib)
- [ ] Add JWT validation middleware
- [ ] Create frontend login/register forms
- [ ] Implement frontend auth state management (Svelte stores)
- [ ] Add protected routes (redirect if not authenticated)
- [ ] Write unit tests for auth logic (pytest)
- [ ] Write integration tests for auth endpoints

**Deliverables:**
- Users can register and log in
- JWT tokens issued and validated
- Protected API endpoints require authentication
- Frontend auth flow complete
- ≥80% test coverage for auth module

#### Week 3: Board Management (CRUD)
- [ ] Implement board creation endpoint
- [ ] Implement board list endpoint (user's boards)
- [ ] Implement board detail endpoint (single board)
- [ ] Implement board update endpoint (title, description)
- [ ] Implement board delete endpoint
- [ ] Create frontend board list view
- [ ] Create frontend board creation form
- [ ] Create frontend board settings modal
- [ ] Add database migrations (Alembic)
- [ ] Write tests for board operations

**Deliverables:**
- Users can create, list, view, update, delete boards
- Frontend displays board list with thumbnails
- Database properly stores board data
- ≥80% test coverage for board module

#### Week 4: Image Upload & Storage Setup
- [ ] Set up MinIO with Nix (or filesystem storage)
- [ ] Implement multipart file upload endpoint
- [ ] Add file validation (type, size, magic bytes)
- [ ] Implement streaming upload to MinIO/filesystem
- [ ] Create image metadata storage (database)
- [ ] Implement thumbnail generation (Pillow)
- [ ] Set up background task processing (FastAPI BackgroundTasks)
- [ ] Create frontend upload UI (file picker + drag-drop)
- [ ] Add upload progress indicator
- [ ] Write tests for upload and storage

**Deliverables:**
- Users can upload images to boards
- Images stored in MinIO/filesystem
- Thumbnails generated automatically
- Upload progress visible to user
- ≥80% test coverage for upload module

---

### Phase 2: Canvas & Image Manipulation (Weeks 5-8)

**Goal:** Implement core canvas functionality and image manipulation features

#### Week 5: Canvas Foundation
- [ ] Integrate Konva.js into Svelte components
- [ ] Implement infinite canvas with pan/zoom
- [ ] Load images from backend onto canvas
- [ ] Implement image dragging (position update)
- [ ] Implement image selection (single click)
- [ ] Add visual selection indicators (border/highlight)
- [ ] Store image positions in database
- [ ] Implement canvas state persistence (viewport)
- [ ] Add keyboard shortcuts (arrow keys for pan)
- [ ] Write tests for canvas state management

**Deliverables:**
- Canvas renders uploaded images
- Users can pan and zoom canvas
- Users can drag images to new positions
- Positions persist when reopening board
- Canvas maintains 60fps performance

#### Week 6: Image Transformations
- [ ] Implement image rotation (Konva transform)
- [ ] Implement image scaling (resize handles)
- [ ] Add flip horizontal/vertical
- [ ] Add opacity adjustment (slider)
- [ ] Add greyscale toggle
- [ ] Implement crop tool (rectangular selection)
- [ ] Store transformations in database (JSONB)
- [ ] Add reset to original button
- [ ] Ensure non-destructive editing (original preserved)
- [ ] Write tests for transformations

**Deliverables:**
- Users can rotate, scale, flip, crop images
- Users can adjust opacity and apply greyscale
- All transformations are non-destructive
- Transformations persist when reopening board

#### Week 7: Multi-Selection & Bulk Operations
- [ ] Implement selection rectangle (drag to select multiple)
- [ ] Add Ctrl+Click for adding to selection
- [ ] Add select all (Ctrl+A)
- [ ] Implement bulk move (move all selected together)
- [ ] Implement bulk rotate/scale
- [ ] Add copy/cut/paste for images
- [ ] Implement delete with confirmation (>10 images)
- [ ] Add selection count indicator
- [ ] Implement undo/redo stack (nice-to-have)
- [ ] Write tests for multi-selection

**Deliverables:**
- Users can select multiple images
- Bulk operations work on all selected images
- Copy/paste works correctly
- Delete requires confirmation for large selections

#### Week 8: Z-Order & Layering
- [ ] Implement bring to front command
- [ ] Implement send to back command
- [ ] Add bring forward/send backward (one layer)
- [ ] Create Z-order visualization (optional)
- [ ] Store Z-order in database
- [ ] Add keyboard shortcuts (PgUp/PgDn)
- [ ] Ensure Z-order persists
- [ ] Write tests for Z-order operations

**Deliverables:**
- Users can control image layering
- Z-order changes immediately visible
- Z-order persists correctly

---

### Phase 3: Advanced Features (Weeks 9-12)

**Goal:** Implement grouping, alignment, sharing, and export features

#### Week 9: Grouping & Annotations
- [ ] Implement create group from selection
- [ ] Add group annotation text input
- [ ] Add color label picker for groups
- [ ] Implement move group as unit
- [ ] Add ungroup command
- [ ] Store groups in database (separate table)
- [ ] Visual indicators for grouped images
- [ ] Prevent images from belonging to multiple groups
- [ ] Write tests for grouping logic

**Deliverables:**
- Users can create groups from selected images
- Groups can have annotations and color labels
- Groups move together as a unit
- Groups persist correctly

#### Week 10: Alignment & Distribution
- [ ] Implement align top/bottom/left/right/center commands
- [ ] Implement distribute horizontal/vertical
- [ ] Add snap-to-grid functionality
- [ ] Make grid configurable (size setting)
- [ ] Add keyboard shortcut for snap toggle
- [ ] Visual grid overlay when snap enabled
- [ ] Write tests for alignment calculations

**Deliverables:**
- Users can align and distribute selected images
- Snap-to-grid helps with precise placement
- Alignment works correctly for 100+ images

#### Week 11: Board Sharing & Collaboration
- [ ] Implement share link generation
- [ ] Add permission level selector (View-only / View+Comment)
- [ ] Implement share link validation endpoint
- [ ] Create shared board view (read-only mode)
- [ ] Implement comment system for View+Comment links
- [ ] Add share link management UI (list, revoke)
- [ ] Store share links in database (tokens table)
- [ ] Add security: rate limiting on share link access
- [ ] Write tests for sharing and permissions

**Deliverables:**
- Users can generate share links with permissions
- Recipients can view shared boards
- View+Comment allows adding comments
- Share links can be revoked

#### Week 12: Export & Download
- [ ] Implement single image download
- [ ] Implement ZIP export (all images)
- [ ] Implement composite image export (render canvas to PNG/JPEG)
- [ ] Add resolution selector for composite (1x, 2x, 4x)
- [ ] Add export progress indicator
- [ ] Handle large exports (streaming or background task)
- [ ] Write tests for export operations

**Deliverables:**
- Users can download individual images
- Users can export all images as ZIP
- Users can export board as single composite image
- Export operations show progress

---

### Phase 4: Polish & Optimization (Weeks 13-16)

**Goal:** Performance optimization, quality features, deployment preparation

#### Week 13: Performance & Adaptive Quality
- [ ] Implement connection speed detection (Network Information API)
- [ ] Serve different resolution thumbnails based on connection
- [ ] Add manual quality override (Auto/Low/Medium/High)
- [ ] Optimize canvas rendering (virtual rendering for large boards)
- [ ] Add lazy loading for image list
- [ ] Implement Redis caching for hot data (optional)
- [ ] Run performance benchmarks (Lighthouse, load testing)
- [ ] Optimize database queries (add missing indexes)

**Deliverables:**
- Boards load in <10s on 3G connections
- Canvas maintains 60fps with 500+ images
- API responses <200ms p95
- Lighthouse score >90

#### Week 14: Command Palette & Additional Features
- [ ] Implement command palette (Ctrl+K/Cmd+K)
- [ ] Add searchable command list
- [ ] Implement focus mode (double-click image)
- [ ] Add slideshow mode with configurable interval
- [ ] Implement navigation order selector (Chronological/Spatial/Alphabetical/Random)
- [ ] Add auto-arrange commands (by name/date/optimal/random)
- [ ] Implement image library view (cross-board reuse)
- [ ] Write tests for command palette and features

**Deliverables:**
- Command palette provides quick access to all commands
- Focus mode and slideshow work correctly
- Auto-arrange layouts images intelligently
- Image library allows reusing images across boards

#### Week 15: Testing & Accessibility
- [ ] Achieve ≥80% test coverage (frontend + backend)
- [ ] Add E2E tests with Playwright (critical user flows)
- [ ] Run accessibility audit (axe-core, manual testing)
- [ ] Fix all WCAG 2.1 AA violations
- [ ] Add keyboard navigation for all features
- [ ] Test on all supported browsers (Chrome, Firefox, Safari, Edge)
- [ ] Add loading states for all async operations
- [ ] Implement error boundaries and fallbacks

**Deliverables:**
- ≥80% test coverage verified
- E2E tests cover critical paths
- WCAG 2.1 AA compliance verified
- All features work on supported browsers

#### Week 16: Deployment & Documentation
- [ ] Finalize Nix flake.nix with all services
- [ ] Create NixOS module for deployment
- [ ] Write deployment documentation (README, docs/)
- [ ] Create API documentation (OpenAPI/Swagger)
- [ ] Write user guide (how to use the application)
- [ ] Set up production environment configuration
- [ ] Implement monitoring and logging
- [ ] Perform staging deployment and validation
- [ ] Plan production deployment strategy

**Deliverables:**
- Full Nix deployment configuration ready
- Documentation complete (deployment, API, user guide)
- Staging environment validated
- Ready for production deployment

---

## Success Criteria

Clear, measurable criteria for completion:

### Functional Completeness
- [ ] All 18 functional requirements from spec.md implemented and tested
- [ ] All user scenarios from spec.md work end-to-end
- [ ] No critical bugs in issue tracker
- [ ] Beta users can complete all major workflows

### Quality Standards
- [ ] ≥80% test coverage (measured by pytest-cov and Vitest)
- [ ] Zero linter errors/warnings (Ruff for Python, ESLint for JS)
- [ ] All tests passing in CI/CD pipeline
- [ ] Code review approved for all major components

### Performance Benchmarks
- [ ] Canvas maintains 60fps with 500 images (measured with Chrome DevTools)
- [ ] API responses <200ms p95 (measured with load testing)
- [ ] Page load <3 seconds on 5 Mbps connection (Lighthouse)
- [ ] Board with 100 images loads in <2 seconds (low-res thumbnails)
- [ ] Upload of 10 images (20MB) completes in <10 seconds on 10 Mbps connection

### Accessibility & UX
- [ ] WCAG 2.1 AA compliance verified (automated testing with axe-core)
- [ ] Keyboard navigation works for all features
- [ ] All error messages are user-friendly (no technical jargon)
- [ ] 90%+ users rate application "easy to use" in beta feedback

### Deployment
- [ ] Application deploys successfully with `nixos-rebuild`
- [ ] All services start correctly (Nginx, FastAPI, PostgreSQL, MinIO)
- [ ] Rollback works (`nixos-rebuild --rollback`)
- [ ] Deployment documentation is clear and complete

### Documentation
- [ ] README.md explains project setup and development
- [ ] API documentation available at /api/docs (OpenAPI)
- [ ] User guide covers all major features
- [ ] Deployment guide covers Nix configuration

## Open Questions

- [x] ~~Which canvas library to use?~~ → **Resolved: Konva.js** (see tech-research.md)
- [x] ~~Python or Node.js backend?~~ → **Resolved: FastAPI (Python)** (leverages existing setup)
- [x] ~~PostgreSQL or SQLite?~~ → **Resolved: PostgreSQL** (better for multi-user, JSON support)
- [x] ~~MinIO or filesystem storage?~~ → **Resolved: MinIO** (S3-compatible, future-proof)
- [ ] Should we implement undo/redo in Phase 2 or defer to v2.0?
- [ ] Do we need Celery for background tasks, or is FastAPI BackgroundTasks sufficient for MVP?
- [ ] Should we use Redis for session caching, or is PostgreSQL sufficient initially?
- [ ] What's the optimal thumbnail resolution strategy? (Current: 800px/1600px/3200px)

## References

- **Specification:** [spec.md](./spec.md) - Full requirements document
- **Technology Research:** [tech-research.md](./tech-research.md) - Comprehensive tech stack analysis
- **Requirements Checklist:** [checklists/requirements.md](./checklists/requirements.md) - Quality validation
- **Project Constitution:** [../../.specify/memory/constitution.md](../../.specify/memory/constitution.md)

**External Resources:**
- Konva.js Documentation: https://konvajs.org/docs/
- FastAPI Documentation: https://fastapi.tiangolo.com/
- Svelte Documentation: https://svelte.dev/docs
- Nix Manual: https://nixos.org/manual/nix/stable/
- NixOS Options: https://search.nixos.org/options
- PureRef (inspiration): https://www.pureref.com/

---

**Next Steps:**
1. Review and approve this plan
2. Set up project repositories and development environment (Week 1)
3. Begin Phase 1 implementation
4. Weekly progress reviews and adjustments
5. Beta release after Week 16

**Estimated Timeline:** 16 weeks (4 months) to MVP  
**Estimated Team Size:** 2-3 developers (1 frontend-focused, 1 backend-focused, 1 full-stack/DevOps)  
**Deployment Target:** Self-hosted NixOS server