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 complete implementation strategy for building a web-based reference board application (inspired by PureRef) for artists and creative professionals. The application enables users to collect, organize, and manipulate visual reference images collaboratively through any modern web browser, with full Nix deployment support.

Business Value:

• Fills market gap for collaborative, accessible reference board tools
• Enables remote creative collaboration without desktop software
• Provides professional-grade visual organization tools
• Demonstrates modern web capabilities with reproducible Nix deployment

Technology Stack (Verified ✅):

• Frontend: Svelte + SvelteKit + Konva.js
• Backend: FastAPI (Python) + PostgreSQL + MinIO
• Deployment: Nix Flakes + NixOS modules
• All components verified in nixpkgs (see VERIFICATION-COMPLETE.md)

Objectives

• Build performant web application supporting 500+ images at 60fps
• Implement all 18 functional requirements from specification
• Achieve ≥80% test coverage (backend + frontend)
• Deploy reproducibly using Nix to self-hosted infrastructure
• Complete MVP development in 16 weeks
• Validate with beta users (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?

  • Design follows single responsibility principle (modular: frontend/backend/storage/database)
  • Clear module boundaries defined (see Technical Approach below)
  • Dependencies justified and documented (see tech-research.md + nix-package-verification.md)
  • Type hints enforced (Python: Pydantic models, Optional: TypeScript frontend)
  • Linting configured (Ruff for Python, ESLint for JavaScript)

• Testing Discipline: What testing strategy will ensure correctness?

  • Unit test coverage plan (≥80%): pytest (backend), Vitest (frontend)
  • Integration test scenarios identified (API endpoints, canvas ops, file uploads)
  • Edge cases documented (large files, concurrent uploads, 500+ images, network failures)
  • E2E tests planned for critical flows (registration → board → upload → export)

• User Experience Consistency: How does this impact users?

  • UI/API changes follow existing patterns (RESTful API, intuitive canvas interactions)
  • Error handling is user-friendly (clear messages, actionable feedback, no raw exceptions)
  • Documentation plan complete (OpenAPI docs, user guide, inline help)
  • Accessibility validated (WCAG 2.1 AA compliance testing with axe-core)

• Performance & Efficiency: What are the performance implications?

  • Performance budget established (60fps canvas, <200ms API, <3s page load)
  • Algorithmic complexity analyzed (O(n) rendering, O(log n) spatial queries)
  • Resource usage estimated (2GB RAM server, 100GB storage, 10Mbps bandwidth)

Scope

In Scope

Core Features (MVP):

• ✅ User authentication (email/password, JWT)
• ✅ Board CRUD operations
• ✅ Multi-method image upload (picker, drag-drop, paste, batch, ZIP)
• ✅ Infinite canvas with pan/zoom/rotate
• ✅ Image transformations (drag, scale, rotate, crop, flip, opacity, greyscale)
• ✅ Multi-selection and bulk operations
• ✅ Image grouping with annotations and colored labels
• ✅ Z-order management (layering)
• ✅ Alignment & distribution tools (snap-to-grid)
• ✅ Copy/cut/paste/delete operations
• ✅ Focus mode and slideshow
• ✅ Export (single, ZIP, composite image)
• ✅ Board sharing (configurable permissions: View-only, View+Comment)
• ✅ Adaptive image quality (auto-detect with manual override)
• ✅ Image library with cross-board reuse
• ✅ Command palette (Ctrl+K)
• ✅ Non-destructive editing
• ✅ Auto-arrange (by name/date/optimal/random)

Deployment:

• ✅ Complete Nix deployment (flake.nix + NixOS modules)
• ✅ Single-server architecture
• ✅ PostgreSQL, MinIO, Nginx configuration
• ✅ CI/CD pipeline with Nix

Quality:

• ✅ ≥80% test coverage
• ✅ Performance benchmarking
• ✅ WCAG 2.1 AA accessibility

Out of Scope (Deferred to v2.0)

• Real-time collaborative editing (multiple users same board simultaneously)
• Native mobile apps (iOS/Android)
• Video/3D model support
• Advanced image editing (filters, color correction beyond greyscale)
• Public board gallery/marketplace
• Team workspaces with role-based access control
• Monetization (payments, subscriptions)
• Multi-language support (English-only v1.0)
• Offline PWA mode
• Third-party integrations (Google Drive, Dropbox, Pinterest)

Technical Approach

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    CLIENT (Browser)                          │
│  ┌────────────────────────────────────────────────────┐    │
│  │   Svelte Frontend + Konva.js Canvas                │    │
│  │   - UI Components (forms, modals, menus)          │    │
│  │   - Canvas (image manipulation, 60fps)            │    │
│  │   - Svelte Stores (state management)              │    │
│  │   - API Client (fetch wrapper)                    │    │
│  └────────────────────────────────────────────────────┘    │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTPS
┌──────────────────────▼───────────────────────────────────────┐
│         Nginx (Reverse Proxy / Static Files)                 │
│  ├─ / → Frontend SPA (Svelte build)                         │
│  ├─ /api/* → FastAPI backend                                │
│  └─ /storage/* → MinIO images                               │
└──────────────────────┬───────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼────────┐ ┌──▼──────────┐ ┌─▼──────────┐
│  FastAPI       │ │ PostgreSQL  │ │   MinIO    │
│  (Python)      │ │ (Database)  │ │  (Images)  │
│  - Auth        │ │ - users     │ │ - originals│
│  - Boards      │ │ - boards    │ │ - thumbs   │
│  - Images      │ │ - images    │ │            │
│  - Processing  │ │ - groups    │ │            │
└────────────────┘ └─────────────┘ └────────────┘

Key Components

1. Frontend (Svelte + Konva.js)

Responsibilities:

• Render UI (forms, modals, command palette)
• Manage canvas (Konva.js: images, viewport, selection, groups)
• Handle interactions (drag, resize, rotate, keyboard)
• API communication
• Client-side validation

Structure:

frontend/
├── src/
│   ├── lib/
│   │   ├── canvas/      # Konva.js wrappers
│   │   ├── stores/      # Svelte state management
│   │   ├── api/         # API client
│   │   └── components/  # Reusable UI
│   ├── routes/          # SvelteKit pages
│   └── app.html         # HTML template
├── static/              # Static assets
├── tests/               # Vitest tests
└── package.json

2. Backend (FastAPI)

Responsibilities:

• Authentication (JWT, password hashing)
• Board/image CRUD
• File upload processing
• Thumbnail generation (background)
• Permission validation
• API documentation (auto-generated)

Structure:

backend/
├── app/
│   ├── auth/            # Authentication
│   ├── boards/          # Board operations
│   ├── images/          # Upload/processing
│   ├── database/        # SQLAlchemy models
│   ├── api/             # Route handlers
│   └── core/            # Config, middleware
├── tests/               # pytest tests
└── pyproject.toml       # uv project file

3. Database (PostgreSQL)

Schema:

users (id, email, password_hash, created_at)
boards (id, user_id, title, viewport_state JSONB, created_at)
images (id, user_id, filename, metadata JSONB, created_at)
board_images (board_id, image_id, position JSONB, transformations JSONB, z_order)
groups (id, board_id, name, color, annotation)
share_links (id, board_id, token, permission_level, created_at)

4. Image Storage (MinIO)

Structure:

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

Dependencies

External (All verified in nixpkgs ✅):

Python:

python3Packages = [
  fastapi uvicorn sqlalchemy alembic pydantic
  python-jose passlib pillow boto3 python-multipart
  httpx pytest pytest-cov pytest-asyncio
]

JavaScript (via npm):

{
  "svelte": "^4.2.0",
  "@sveltejs/kit": "^2.0.0",
  "konva": "^9.3.0",
  "vite": "^5.0.0"
}

System:

[ postgresql nodejs imagemagick uv ruff ]

Internal:

• Frontend → Backend (REST API)
• Backend → Database (SQLAlchemy)
• Backend → MinIO (boto3 S3 client)
• Backend → Image Processing (Pillow + ImageMagick)

Risks & Mitigations

Risk	Impact	Probability	Mitigation
Canvas performance degrades >500 images	High	Medium	Virtual rendering (visible only), Konva layers, pagination option
Large file uploads timeout (50MB)	High	Medium	Streaming uploads, chunked transfer, increase timeouts, progress bars
Nix deployment complexity	Medium	Medium	Comprehensive docs, example configs, test on multiple NixOS versions
Browser compatibility (Safari)	Medium	Low	Define minimum versions, polyfills, cross-browser testing
Image processing bottleneck	High	Medium	Celery for distributed tasks (Phase 2), rate limiting, optimize Pillow
DB query performance	Medium	Low	Database indexes (GIN for JSONB), query optimization, Redis caching
Storage costs (100GB+/user)	Low	Low	Storage quotas, image deduplication, compression
File upload attacks	High	Low	Strict validation (magic bytes), size limits, CSP headers

Implementation Phases

Phase 0: Research & Design (Week 0 - Pre-Development)

Status: ✅ COMPLETE

Artifacts Created:

• tech-research.md (18KB, comprehensive tech stack analysis)
• nix-package-verification.md (verification of all nixpkgs availability)
• VERIFICATION-COMPLETE.md (summary + proof)
• data-model.md (database schema design - to be created)
• contracts/ (API contracts - to be created)

Decisions Made:

• Frontend: Svelte + Konva.js (smallest bundle, best canvas performance)
• Backend: FastAPI (async, fast, leverages existing Python)
• Database: PostgreSQL (JSONB support, full-text search)
• Storage: MinIO (S3-compatible, future-proof)
• Deployment: Nix Flakes (reproducible, declarative)

All NEEDS CLARIFICATION resolved:

• Share permissions: Configurable (View-only / View+Comment)
• Connection detection: Hybrid (auto-detect + manual override)
• Navigation order: User-configurable (Chronological/Spatial/Alphabetical/Random)

---

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

Goal: Development environment, core architecture, basic CRUD

Week 1: Project Setup & Nix Configuration

Tasks:

• Initialize Git repository structure
• Create flake.nix with development environment
• Set up frontend (SvelteKit + Vite)
• Set up backend (FastAPI with uv)
• Configure PostgreSQL with Nix
• Set up pre-commit hooks (Ruff, ESLint, Prettier)
• Initialize CI/CD pipeline
• Create initial database schema

Deliverables:

• nix develop provides complete dev environment
• Frontend dev server runs (npm run dev)
• Backend dev server runs (uvicorn app.main:app --reload)
• PostgreSQL accessible
• CI runs linters

Week 2: Authentication System

Tasks:

• Design user schema + JWT strategy
• Implement registration endpoint
• Implement login endpoint (JWT generation)
• Implement password hashing (bcrypt)
• Add JWT validation middleware
• Create frontend login/register forms
• Implement auth state management (Svelte stores)
• Add protected routes
• Write unit tests for auth (pytest)
• Write integration tests for endpoints

Deliverables:

• Users can register and log in
• JWT tokens issued and validated
• Protected endpoints require auth
• Frontend auth flow complete
• ≥80% test coverage for auth

Week 3: Board Management

Tasks:

• Implement board creation endpoint
• Implement board list endpoint
• Implement board detail endpoint
• Implement board update endpoint
• Implement board delete endpoint
• Create frontend board list view
• Create board creation form
• Create board settings modal
• Add database migrations (Alembic)
• Write tests for board operations

Deliverables:

• Full board CRUD functionality
• Frontend displays board list
• Database stores board data
• ≥80% test coverage

Week 4: Image Upload & Storage

Tasks:

• Set up MinIO with Nix
• Implement multipart upload endpoint
• Add file validation (type, size, magic bytes)
• Implement streaming to MinIO
• Create image metadata storage
• Implement thumbnail generation (Pillow)
• Set up background tasks (FastAPI BackgroundTasks)
• Create upload UI (picker + drag-drop)
• Add progress indicator
• Write upload tests

Deliverables:

• Users can upload images
• Images stored in MinIO
• Thumbnails auto-generated
• Upload progress visible
• ≥80% test coverage

---

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

Goal: Core canvas functionality and image manipulation

Week 5: Canvas Foundation

Tasks:

• Integrate Konva.js into Svelte
• Implement infinite canvas (pan/zoom)
• Load images from backend
• Implement image dragging
• Implement selection (single click)
• Add selection indicators
• Store positions in database
• Persist canvas viewport state
• Add keyboard shortcuts (arrows for pan)
• Write canvas state tests

Deliverables:

• Canvas renders images
• Pan/zoom/drag work smoothly
• Positions persist
• 60fps maintained

Week 6: Image Transformations

Tasks:

• Implement rotation
• Implement scaling (resize handles)
• Add flip horizontal/vertical
• Add opacity adjustment
• Add greyscale toggle
• Implement crop tool
• Store transformations (JSONB)
• Add "reset to original" button
• Ensure non-destructive editing
• Write transformation tests

Deliverables:

• All transformations working
• Non-destructive editing verified
• Transformations persist

Week 7: Multi-Selection & Bulk Ops

Tasks:

• Implement selection rectangle
• Add Ctrl+Click multi-select
• Add select all (Ctrl+A)
• Implement bulk move
• Implement bulk rotate/scale
• Add copy/cut/paste
• Implement delete with confirmation
• Add selection count indicator
• Implement undo/redo (optional)
• Write multi-selection tests

Deliverables:

• Multi-select works
• Bulk operations functional
• Copy/paste correct
• Delete confirms for >10 images

Week 8: Z-Order & Layering

Tasks:

• Implement bring to front
• Implement send to back
• Add bring forward/backward
• Store Z-order in database
• Add keyboard shortcuts (PgUp/PgDn)
• Ensure Z-order persistence
• Write Z-order tests

Deliverables:

• Full layering control
• Z-order immediately visible
• Persistence verified

---

Phase 3: Advanced Features (Weeks 9-12)

Goal: Grouping, alignment, sharing, export

Week 9: Grouping & Annotations

Tasks:

• Implement create group from selection
• Add annotation text input
• Add color label picker
• Implement move group as unit
• Add ungroup command
• Store groups in database
• Visual group indicators
• Prevent multi-group membership
• Write grouping tests

Deliverables:

• Groups functional
• Annotations and colors work
• Groups move as unit
• Persistence verified

Week 10: Alignment & Distribution

Tasks:

• Implement align commands (top/bottom/left/right/center)
• Implement distribute (horizontal/vertical)
• Add snap-to-grid
• Make grid configurable
• Add snap toggle shortcut
• Visual grid overlay
• Write alignment tests

Deliverables:

• Alignment commands work
• Snap-to-grid functional
• Works with 100+ images

Week 11: Board Sharing

Tasks:

• Implement share link generation
• Add permission selector (View/View+Comment)
• Implement link validation endpoint
• Create shared board view (read-only)
• Implement comment system
• Add share link management UI
• Store links in database
• Add rate limiting
• Write sharing tests

Deliverables:

• Share links generated
• Permission levels work
• Comments functional (View+Comment)
• Links revocable

Week 12: Export & Download

Tasks:

• Implement single image download
• Implement ZIP export (all images)
• Implement composite export (canvas → PNG/JPEG)
• Add resolution selector (1x/2x/4x)
• Add progress indicator
• Handle large exports (streaming/background)
• Write export tests

Deliverables:

• All export methods work
• Progress indicators visible
• Large exports handled

---

Phase 4: Polish & Deployment (Weeks 13-16)

Goal: Performance, quality, deployment readiness

Week 13: Performance & Adaptive Quality

Tasks:

• Implement connection speed detection
• Serve different thumbnail resolutions
• Add manual quality override
• Optimize canvas rendering (virtual rendering)
• Add lazy loading for image lists
• Implement Redis caching (optional)
• Run performance benchmarks (Lighthouse)
• Optimize database queries (indexes)

Deliverables:

• Boards load <10s on 3G
• Canvas maintains 60fps with 500+ images
• API responses <200ms p95
• Lighthouse score >90

Week 14: Command Palette & Features

Tasks:

• Implement command palette (Ctrl+K)
• Add searchable commands
• Implement focus mode
• Add slideshow mode
• Implement navigation order selector
• Add auto-arrange commands
• Implement image library view
• Write feature tests

Deliverables:

• Command palette functional
• Focus/slideshow work
• Auto-arrange layouts correctly
• Image library allows reuse

Week 15: Testing & Accessibility

Tasks:

• Achieve ≥80% coverage (both sides)
• Add E2E tests (Playwright)
• Run accessibility audit (axe-core)
• Fix WCAG 2.1 AA violations
• Add keyboard navigation
• Test all browsers (Chrome/Firefox/Safari/Edge)
• Add loading states
• Implement error boundaries

Deliverables:

• ≥80% coverage verified
• E2E tests cover critical paths
• WCAG 2.1 AA compliant
• Works on all browsers

Week 16: Deployment & Documentation

Tasks:

• Finalize flake.nix
• Create NixOS module
• Write deployment docs
• Create API docs (OpenAPI)
• Write user guide
• Set up production config
• Implement monitoring/logging
• Staging deployment
• Plan production deployment

Deliverables:

• Complete Nix deployment config
• All documentation complete
• Staging validated
• Production-ready

---

Success Criteria

Functional Completeness

• All 18 functional requirements implemented and tested
• All user scenarios from spec work end-to-end
• No critical bugs
• Beta users complete all workflows

Quality Standards

• ≥80% test coverage (pytest-cov + Vitest)
• Zero linter errors (Ruff + ESLint)
• All tests passing in CI
• Code reviews approved

Performance Benchmarks

• Canvas 60fps with 500 images (Chrome DevTools)
• API <200ms p95 (load testing)
• Page load <3s on 5Mbps (Lighthouse)
• Board with 100 images loads <2s
• Upload 10 images (20MB) <10s on 10Mbps

Accessibility & UX

• WCAG 2.1 AA (axe-core)
• Keyboard navigation for all features
• User-friendly error messages
• 90%+ "easy to use" in beta

Deployment

• nixos-rebuild deploys successfully
• All services start correctly
• Rollback works
• Documentation complete

Open Questions

• Canvas library? → Konva.js (verified)
• Backend framework? → FastAPI (verified)
• Database? → PostgreSQL (verified)
• Storage? → MinIO (verified)
• Undo/redo in Phase 2 or defer to v2.0?
• Celery for background tasks or FastAPI BackgroundTasks sufficient?
• Redis for caching or PostgreSQL sufficient initially?
• Thumbnail resolutions optimal? (800px/1600px/3200px)

References

• Specification: spec.md
• Technology Research: tech-research.md
• Nix Verification: nix-package-verification.md + VERIFICATION-COMPLETE.md
• Requirements Checklist: checklists/requirements.md
• Constitution: ../../.specify/memory/constitution.md

External:

• Konva.js: https://konvajs.org/docs/
• FastAPI: https://fastapi.tiangolo.com/
• Svelte: https://svelte.dev/docs
• Nix Manual: https://nixos.org/manual/nix/stable/
• PureRef: https://www.pureref.com/

---

Timeline: 16 weeks (4 months) to MVP
Team Size: 2-3 developers recommended
Deployment: Self-hosted NixOS server
Status: Ready to begin Week 1