708 lines
33 KiB
Markdown
708 lines
33 KiB
Markdown
# Specification: Reference Board Viewer
|
|
|
|
**Version:** 1.0.0
|
|
**Created:** 2025-11-02
|
|
**Last Updated:** 2025-11-02
|
|
**Status:** Approved
|
|
**Owner:** Project Team
|
|
|
|
## Purpose
|
|
|
|
This specification defines a web-based reference board application for artists and creative professionals to collect, organize, and manipulate visual reference images. The application addresses the need for a collaborative, accessible alternative to desktop-only tools (like PureRef), enabling users to create mood boards, reference collections, and visual collages from any device with internet access.
|
|
|
|
**Business Value:**
|
|
- Enables remote collaboration on visual reference collections
|
|
- Provides accessible visual organization tools without desktop software installation
|
|
- Supports artists' creative workflows with non-destructive image manipulation
|
|
- Scales from individual artists to collaborative creative teams
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### Scenario 1: Creating a New Reference Board
|
|
|
|
**Actor:** Artist (authenticated user)
|
|
**Goal:** Create a new reference board for a character design project
|
|
|
|
**Flow:**
|
|
1. User logs into the application
|
|
2. User creates a new board titled "Character Design - Fantasy Knight"
|
|
3. User uploads 15 reference images (armor, poses, weapons) via drag-and-drop
|
|
4. User arranges images by dragging them into desired positions
|
|
5. User groups armor references together with a label "Plate Armor - Blue"
|
|
6. User saves the board
|
|
|
|
**Success Criteria:** Board is saved with all images properly positioned and grouped
|
|
|
|
### Scenario 2: Collaborating on a Shared Board
|
|
|
|
**Actor:** Art Director (authenticated user)
|
|
**Goal:** Review and annotate a junior artist's reference board
|
|
|
|
**Flow:**
|
|
1. Junior artist shares board "Environment Concepts" with art director (View+Comment permission)
|
|
2. Art director opens the shared board link
|
|
3. Art director views all images and can add comments
|
|
4. Art director adds comment "Love the color palette in group 3"
|
|
5. Junior artist sees the comment when reopening the board
|
|
|
|
**Success Criteria:** Art director can view board, add comments, but cannot modify images or layout
|
|
|
|
### Scenario 3: Working with Limited Bandwidth
|
|
|
|
**Actor:** Freelance artist with slow internet connection
|
|
**Goal:** Access reference board while traveling
|
|
|
|
**Flow:**
|
|
1. User opens their board "Portrait References"
|
|
2. Application automatically detects slow connection using browser Network API and speed test
|
|
3. Application serves low-resolution previews of images
|
|
4. User can still zoom/pan/arrange images smoothly
|
|
5. User can optionally load full-resolution version of specific images
|
|
6. User can manually override quality setting if auto-detection is incorrect
|
|
|
|
**Success Criteria:** Board loads and remains usable within 10 seconds on 3G connection
|
|
|
|
### Scenario 4: Complex Image Arrangement
|
|
|
|
**Actor:** Concept artist (authenticated user)
|
|
**Goal:** Create organized layout of 50+ references with precise alignment
|
|
|
|
**Flow:**
|
|
1. User opens existing board with 50 images
|
|
2. User selects 10 images showing character expressions
|
|
3. User uses "Align Top" command to align all selected images
|
|
4. User uses "Distribute Horizontal" to space them evenly
|
|
5. User enables snap-to-grid for precise placement
|
|
6. User groups the aligned images with annotation "Expression Study"
|
|
7. User exports the final arrangement as a single high-resolution image
|
|
|
|
**Success Criteria:** Images align precisely, export contains all images at full quality
|
|
|
|
### Scenario 5: Non-Destructive Editing
|
|
|
|
**Actor:** Illustrator (authenticated user)
|
|
**Goal:** Crop and adjust images for board without losing original files
|
|
|
|
**Flow:**
|
|
1. User uploads high-resolution reference photo (4K resolution)
|
|
2. User crops image to focus on a specific detail
|
|
3. User converts image to greyscale for value study
|
|
4. User reduces opacity to 50% for overlay reference
|
|
5. User later needs original - clicks "Reset to Original"
|
|
6. All edits are reverted, original 4K image restored
|
|
|
|
**Success Criteria:** Original image is never modified, all edits are reversible
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
#### FR1: User Authentication & Account Management
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to create accounts, log in, and manage their profile to access private boards and collaborate with others.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can register for an account with email and password
|
|
- [ ] Users can log in and log out securely
|
|
- [ ] User sessions persist across browser sessions
|
|
- [ ] Users can reset forgotten passwords
|
|
- [ ] Each user has a unique, isolated workspace for their boards
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for authentication logic, integration tests for login/logout flows
|
|
- UX Impact: Login process completes in <3 seconds, clear error messages for failed authentication
|
|
- Performance: Authentication check completes in <100ms, sessions cached efficiently
|
|
|
|
#### FR2: Board Management
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to create, save, edit, delete, and organize multiple reference boards.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can create a new board with a title
|
|
- [ ] Users can save boards (auto-save and manual save)
|
|
- [ ] Users can edit board title and metadata
|
|
- [ ] Users can delete boards (with confirmation prompt)
|
|
- [ ] Users can view a list of all their boards
|
|
- [ ] Board list shows preview thumbnail, title, last modified date, and image count
|
|
- [ ] Users can duplicate existing boards
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for board CRUD operations, integration tests for board list rendering
|
|
- UX Impact: Board creation is instant (<200ms), deletion requires confirmation to prevent accidents
|
|
- Performance: Board list loads in <1 second for users with up to 100 boards
|
|
|
|
#### FR3: Board Sharing & Collaboration
|
|
**Priority:** High
|
|
**Description:** Users must be able to share boards with other users while maintaining privacy controls.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Boards are private by default (only owner can access)
|
|
- [ ] Users can generate a share link for any board
|
|
- [ ] When creating share link, owner chooses permission level: View-only or View+Comment
|
|
- [ ] View-only links allow recipients to see board but not modify or comment
|
|
- [ ] View+Comment links allow recipients to add comments/annotations but not modify images or layout
|
|
- [ ] Users can revoke share links at any time
|
|
- [ ] Users can change permission level of existing share links
|
|
- [ ] Board owner can see list of active share links with their permission levels
|
|
- [ ] Comments from viewers are visually distinct from owner content
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for sharing permissions, security tests to verify access controls
|
|
- UX Impact: Share link generation is instant, clear indication of board privacy status
|
|
- Performance: Share link validation completes in <100ms
|
|
|
|
#### FR4: Image Upload & Import
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to add images to boards through multiple convenient methods.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can upload images via file picker dialog
|
|
- [ ] Users can upload multiple images simultaneously (batch upload)
|
|
- [ ] Users can drag and drop image files directly onto the board
|
|
- [ ] Users can paste images from clipboard (e.g., screenshots)
|
|
- [ ] Users can upload ZIP files containing multiple images (extracted automatically)
|
|
- [ ] Supported formats: JPEG, PNG, GIF, WebP, SVG
|
|
- [ ] Maximum individual file size: 50MB
|
|
- [ ] Maximum batch upload size: 500MB
|
|
- [ ] Upload progress indicator shows for uploads >5 seconds
|
|
- [ ] Failed uploads show clear error messages with reasons
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for file validation, integration tests for each upload method
|
|
- UX Impact: Upload progress visible for large files, drag-drop works intuitively
|
|
- Performance: Upload processes in background, UI remains responsive
|
|
|
|
#### FR5: Image Positioning & Layout
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to freely position, arrange, and organize images on the infinite canvas.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can drag images to any position on the canvas
|
|
- [ ] Images can overlap (Z-order controlled by user)
|
|
- [ ] Users can bring images to front or send to back
|
|
- [ ] Users can bring images forward/backward one layer at a time
|
|
- [ ] Canvas is infinite (no boundaries, scrollable in all directions)
|
|
- [ ] Users can select multiple images with click+drag selection box
|
|
- [ ] Users can select/deselect individual images with Ctrl+Click (Cmd+Click on Mac)
|
|
- [ ] Selected images show visual highlight (border or outline)
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for drag-drop, unit tests for Z-order calculations
|
|
- UX Impact: Dragging feels smooth (<16ms frame time), visual feedback is immediate
|
|
- Performance: Handles 500+ images on canvas without lag
|
|
|
|
#### FR6: Image Alignment & Distribution
|
|
**Priority:** High
|
|
**Description:** Users must be able to precisely align and distribute images for professional layouts.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can align selected images: Top, Bottom, Left, Right, Center Vertical, Center Horizontal
|
|
- [ ] Users can distribute selected images: Horizontal spacing, Vertical spacing
|
|
- [ ] Alignment operations preserve relative positions except for aligned axis
|
|
- [ ] Distribution creates equal spacing between images
|
|
- [ ] Snap-to-grid mode helps images align to grid lines
|
|
- [ ] Grid size is configurable (default: 50px)
|
|
- [ ] Snap-to-grid can be toggled on/off with keyboard shortcut
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for alignment calculations, integration tests for UI commands
|
|
- UX Impact: Alignment is instant (<50ms), grid provides visual guides
|
|
- Performance: Alignment calculations complete in <100ms for 100 selected images
|
|
|
|
#### FR7: Image Grouping & Annotations
|
|
**Priority:** High
|
|
**Description:** Users must be able to organize images into groups with labels for better organization.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can select multiple images and create a group
|
|
- [ ] Groups can have text annotations (title/description)
|
|
- [ ] Groups can have colored labels (user selects from color palette)
|
|
- [ ] Groups can be moved as a single unit (all images move together)
|
|
- [ ] Groups can be ungrouped (images remain, group dissolves)
|
|
- [ ] Images can belong to only one group at a time
|
|
- [ ] Groups can contain 1-1000 images
|
|
- [ ] Group annotations are visible as overlay or adjacent to group
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for grouping logic, integration tests for group operations
|
|
- UX Impact: Group creation is instant, visual indicators clearly show grouped images
|
|
- Performance: Moving groups with 100+ images maintains 60fps
|
|
|
|
#### FR8: Image Transformation & Editing
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to transform and adjust images non-destructively.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can scale images (resize) by dragging corners or entering dimensions
|
|
- [ ] Users can rotate images to any angle (free rotation and 90° increments)
|
|
- [ ] Users can flip images horizontally and vertically
|
|
- [ ] Users can crop images to rectangular regions
|
|
- [ ] Users can adjust image opacity (0-100%)
|
|
- [ ] Users can convert images to greyscale
|
|
- [ ] All transformations are non-destructive (original preserved)
|
|
- [ ] Users can reset any image to original state
|
|
- [ ] Transformation UI shows current values (angle, scale %, opacity %)
|
|
- [ ] Proportional scaling is default (maintains aspect ratio)
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for transformation calculations, integration tests for UI controls
|
|
- UX Impact: Transformations render in real-time (<16ms), controls are intuitive
|
|
- Performance: Transformations use GPU acceleration when available
|
|
|
|
#### FR9: Multi-Selection & Bulk Operations
|
|
**Priority:** High
|
|
**Description:** Users must be able to select and operate on multiple images simultaneously.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can select multiple images by dragging selection rectangle
|
|
- [ ] Users can add to selection with Ctrl+Click (Cmd+Click on Mac)
|
|
- [ ] Users can select all images with Ctrl+A (Cmd+A on Mac)
|
|
- [ ] Users can deselect all with Escape key or clicking empty canvas
|
|
- [ ] Bulk operations available: Move, Scale, Rotate, Delete, Group, Align, Distribute
|
|
- [ ] Bulk transformations apply relative to each image's center
|
|
- [ ] Selection count indicator shows number of selected images
|
|
- [ ] Users can invert selection (select all except currently selected)
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for selection operations, unit tests for bulk transforms
|
|
- UX Impact: Selection box appears instantly, visual feedback for selected state
|
|
- Performance: Selection operations remain responsive with 500+ images
|
|
|
|
#### FR10: Copy, Cut, Paste, Delete Operations
|
|
**Priority:** High
|
|
**Description:** Users must have standard clipboard operations for efficient editing.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can copy selected images (Ctrl+C / Cmd+C)
|
|
- [ ] Users can cut selected images (Ctrl+X / Cmd+X)
|
|
- [ ] Users can paste copied/cut images (Ctrl+V / Cmd+V)
|
|
- [ ] Pasted images appear at center of current viewport
|
|
- [ ] Pasted images are automatically selected
|
|
- [ ] Users can delete selected images (Delete/Backspace key)
|
|
- [ ] Delete operation requires confirmation if >10 images selected
|
|
- [ ] Cut images are removed from canvas after paste
|
|
- [ ] Copied images remain on canvas after paste
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for clipboard operations, unit tests for delete logic
|
|
- UX Impact: Standard keyboard shortcuts work as expected
|
|
- Performance: Copy/paste operations complete in <200ms
|
|
|
|
#### FR11: Command Palette
|
|
**Priority:** Medium
|
|
**Description:** Users must have quick access to all commands through a searchable palette.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Command palette opens with keyboard shortcut (Ctrl+K / Cmd+K)
|
|
- [ ] Palette shows list of all available commands
|
|
- [ ] Users can search/filter commands by typing
|
|
- [ ] Search matches command names and synonyms
|
|
- [ ] Palette shows keyboard shortcuts next to commands
|
|
- [ ] Recently used commands appear at top
|
|
- [ ] Palette closes after command execution or on Escape key
|
|
- [ ] Commands are categorized (File, Edit, View, Arrange, etc.)
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for command execution, unit tests for search/filter
|
|
- UX Impact: Palette opens instantly (<100ms), search results update in real-time
|
|
- Performance: Search filters 100+ commands in <50ms
|
|
|
|
#### FR12: Canvas Navigation & Viewport Control
|
|
**Priority:** Critical
|
|
**Description:** Users must be able to navigate the infinite canvas efficiently.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can pan canvas by dragging with middle mouse button or spacebar+drag
|
|
- [ ] Users can zoom in/out with mouse wheel or pinch gesture
|
|
- [ ] Zoom levels: 10% to 500% (increments of 10%)
|
|
- [ ] Users can rotate entire canvas view (for different perspective)
|
|
- [ ] Users can reset camera to default position/zoom/rotation
|
|
- [ ] Users can fit all images to viewport (zoom to fit)
|
|
- [ ] Users can center on selected image(s)
|
|
- [ ] Viewport position/zoom persists when reopening board
|
|
- [ ] Touch gestures supported on tablets: two-finger pan, pinch zoom, rotate
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for navigation controls, unit tests for zoom calculations
|
|
- UX Impact: Pan/zoom feels smooth (60fps), gestures respond naturally
|
|
- Performance: Viewport updates maintain 60fps with 500+ images
|
|
|
|
#### FR13: Image Focus & Navigation
|
|
**Priority:** Medium
|
|
**Description:** Users must be able to focus on individual images and navigate between them.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can double-click image to enter focus mode (image fills viewport)
|
|
- [ ] Focus mode hides all other images temporarily
|
|
- [ ] Users can exit focus mode with Escape key or clicking outside
|
|
- [ ] Users can navigate to next image with arrow key or on-screen button
|
|
- [ ] Users can navigate to previous image with arrow key or on-screen button
|
|
- [ ] Users can choose navigation order from dropdown: Chronological (upload time), Spatial (left-to-right, top-to-bottom), Alphabetical (by filename), Random
|
|
- [ ] Navigation order preference is saved per user and persists across sessions
|
|
- [ ] Default navigation order is Chronological
|
|
- [ ] Focus mode shows image counter (e.g., "5 of 23")
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for focus mode, unit tests for navigation logic
|
|
- UX Impact: Focus transition is smooth, navigation is intuitive
|
|
- Performance: Focus mode transitions complete in <200ms
|
|
|
|
#### FR14: Slideshow Mode
|
|
**Priority:** Low
|
|
**Description:** Users must be able to play an automatic slideshow of board images.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can start slideshow from menu or keyboard shortcut
|
|
- [ ] Slideshow displays images in full-screen or maximized view
|
|
- [ ] Configurable interval between images (1-30 seconds, default 5)
|
|
- [ ] Users can pause/resume slideshow
|
|
- [ ] Users can manually advance to next/previous image during slideshow
|
|
- [ ] Users can exit slideshow with Escape key
|
|
- [ ] Slideshow respects navigation order setting (same as focus mode: Chronological, Spatial, Alphabetical, or Random)
|
|
- [ ] Slideshow controls overlay bottom of screen
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for slideshow controls, unit tests for timing logic
|
|
- UX Impact: Transitions between images are smooth, controls are accessible
|
|
- Performance: Slideshow maintains smooth transitions at 60fps
|
|
|
|
#### FR15: Image Export & Download
|
|
**Priority:** High
|
|
**Description:** Users must be able to export images and board layouts for external use.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can download individual images (click image → "Download")
|
|
- [ ] Users can export all images as ZIP file (preserves original quality)
|
|
- [ ] Users can export entire board as single composite image (PNG/JPEG)
|
|
- [ ] Composite export captures current viewport or all images [user selects]
|
|
- [ ] Composite export resolution: Screen resolution, 2x, 4x (up to 16K pixels)
|
|
- [ ] Export operations show progress indicator
|
|
- [ ] Exported ZIP includes folder structure for grouped images
|
|
- [ ] Exported images maintain original filenames where possible
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for export operations, unit tests for image generation
|
|
- UX Impact: Export options are clear, progress visible for large exports
|
|
- Performance: Single image export <1s, ZIP export <10s for 100 images
|
|
|
|
#### FR16: Adaptive Image Quality Serving
|
|
**Priority:** High
|
|
**Description:** Application must serve appropriate image quality based on connection speed to ensure usability on all networks.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Application automatically detects user's connection speed using browser Network Information API and initial speed test
|
|
- [ ] On slow connections (<1 Mbps), serve low-resolution previews (max 800px)
|
|
- [ ] On medium connections (1-5 Mbps), serve medium-resolution (max 1600px)
|
|
- [ ] On fast connections (>5 Mbps), serve full-resolution images
|
|
- [ ] Users can manually override automatic detection with quality setting (Auto/Low/Medium/High)
|
|
- [ ] Quality setting selector is easily accessible in UI
|
|
- [ ] Original full-resolution images always preserved on server
|
|
- [ ] Users can selectively load full-resolution for specific images regardless of quality setting
|
|
- [ ] Quality setting preference persists across sessions
|
|
- [ ] Loading indicator shows when full-resolution is being fetched
|
|
- [ ] Application re-evaluates connection speed periodically (every 5 minutes) when in Auto mode
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for quality detection, unit tests for resolution logic
|
|
- UX Impact: Boards load within 10 seconds on slow connections
|
|
- Performance: Quality detection completes within first 2 seconds of session
|
|
|
|
#### FR17: Image Reuse Across Boards
|
|
**Priority:** Medium
|
|
**Description:** Users must be able to reuse uploaded images across multiple boards without re-uploading.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] When image is uploaded, it's stored in user's image library
|
|
- [ ] Users can access their image library from any board
|
|
- [ ] Users can add existing library images to new boards
|
|
- [ ] Same image on multiple boards references single stored file (no duplication)
|
|
- [ ] Deleting image from a board doesn't delete from library
|
|
- [ ] Users can permanently delete images from library (removes from all boards)
|
|
- [ ] Library view shows all uploaded images with thumbnails
|
|
- [ ] Library supports search/filter by filename or upload date
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Integration tests for library operations, unit tests for reference counting
|
|
- UX Impact: Adding library images is instant (no re-upload), library is easily browsable
|
|
- Performance: Image library with 1000+ images loads in <2 seconds
|
|
|
|
#### FR18: Arrange Images by Criteria
|
|
**Priority:** Low
|
|
**Description:** Users can automatically arrange images based on different sorting criteria.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Users can auto-arrange images by: Name (alphabetical), Upload date, Optimal layout, Random
|
|
- [ ] Optimal layout minimizes whitespace while maintaining readability
|
|
- [ ] Random arrangement distributes images unpredictably across canvas
|
|
- [ ] Auto-arrange preserves groups (grouped images stay together)
|
|
- [ ] Users can undo auto-arrange operation
|
|
- [ ] Auto-arrange operation shows preview before applying
|
|
- [ ] Users can configure arrange direction (left-to-right, top-to-bottom)
|
|
- [ ] Arrange operation respects existing groups and their internal layout
|
|
|
|
**Constitutional Alignment:**
|
|
- Testing: Unit tests for sorting algorithms, integration tests for arrange UI
|
|
- UX Impact: Arrange operation is reversible, preview shows expected result
|
|
- Performance: Auto-arrange completes in <2 seconds for 100 images
|
|
|
|
### Non-Functional Requirements
|
|
|
|
#### NFR1: Performance
|
|
Per Constitutional Principle 4:
|
|
- **Page Load Time:** Initial application load <3 seconds on 5 Mbps connection
|
|
- **Board Load Time:** Board with 100 images loads in <2 seconds (low-res previews)
|
|
- **UI Responsiveness:** All user interactions respond within 200ms
|
|
- **Animation Frame Rate:** Canvas operations maintain 60fps (pan, zoom, drag)
|
|
- **Concurrent Users:** System supports 1,000 concurrent users
|
|
- **Large Boards:** Boards with 500+ images remain usable (no lag during pan/zoom)
|
|
- **Upload Performance:** 10 images (20MB total) upload in <10 seconds on 10 Mbps connection
|
|
- **Export Performance:** Board export to single image completes in <30 seconds for 100 images
|
|
|
|
#### NFR2: Quality
|
|
Per Constitutional Principle 1:
|
|
- **Code Coverage:** ≥80% test coverage (Principle 2 requirement)
|
|
- **Linting:** Zero errors/warnings in code quality checks
|
|
- **Type Safety:** All data structures and interfaces fully typed
|
|
- **Documentation:** All user-facing features documented in help system
|
|
- **Error Handling:** All error states have user-friendly messages
|
|
- **Logging:** All critical operations logged for debugging
|
|
|
|
#### NFR3: User Experience
|
|
Per Constitutional Principle 3:
|
|
- **Accessibility:** WCAG 2.1 AA compliance for all UI elements
|
|
- **Keyboard Navigation:** All features accessible via keyboard shortcuts
|
|
- **Error Messages:** Clear, actionable messages for all error conditions
|
|
- **Responsive Design:** Works on desktop (1920x1080), tablet (1024x768), and mobile (375x667)
|
|
- **Browser Support:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
|
- **Loading States:** Progress indicators for all operations >1 second
|
|
- **Offline Support:** Users see appropriate message when offline (no cryptic errors)
|
|
- **Help System:** Contextual help available for all major features
|
|
|
|
#### NFR4: Maintainability
|
|
Per Constitutional Principle 1:
|
|
- **Code Complexity:** Functions maintain low cyclomatic complexity (<10)
|
|
- **Modularity:** Clear separation between UI, business logic, and data layers
|
|
- **Dependency Management:** All dependencies explicitly versioned
|
|
- **Deployment:** Reproducible deployments via Nix configuration
|
|
- **Configuration:** Environment-specific settings externalized (not hardcoded)
|
|
- **Monitoring:** Application health metrics exposed for monitoring
|
|
|
|
#### NFR5: Security
|
|
- **Authentication:** Secure password hashing and session management
|
|
- **Authorization:** Strict access controls for private boards
|
|
- **Data Privacy:** User data isolated, no cross-user data leakage
|
|
- **File Upload Validation:** All uploads validated for file type, size, and malicious content
|
|
- **XSS Prevention:** All user input sanitized before display
|
|
- **CSRF Protection:** All state-changing operations protected against CSRF
|
|
- **HTTPS:** All connections encrypted in transit
|
|
- **Secrets Management:** No hardcoded secrets, use environment variables
|
|
|
|
#### NFR6: Scalability
|
|
- **Storage:** Support for 100GB+ total image storage per user
|
|
- **Boards per User:** Support for 500+ boards per user
|
|
- **Images per Board:** Support for 1,000+ images per board
|
|
- **Concurrent Sessions:** Single user can have 5+ concurrent sessions
|
|
- **Horizontal Scaling:** Application can scale horizontally (add more servers)
|
|
|
|
#### NFR7: Reliability
|
|
- **Uptime:** 99.9% uptime target (SLA)
|
|
- **Data Durability:** Image uploads have 99.999% durability (no data loss)
|
|
- **Auto-Save:** Boards auto-save every 30 seconds (prevents work loss)
|
|
- **Backup:** User data backed up daily
|
|
- **Recovery:** Point-in-time recovery available for last 30 days
|
|
- **Graceful Degradation:** If image service fails, application shows cached/cached thumbnails
|
|
|
|
## Success Criteria
|
|
|
|
Post-deployment validation (technology-agnostic, measurable outcomes):
|
|
|
|
- [ ] **User Onboarding:** New users can create their first board with 10 images within 5 minutes
|
|
- [ ] **Board Load Performance:** 95% of board loads complete within 3 seconds
|
|
- [ ] **Operation Responsiveness:** 99% of user interactions respond within 200ms
|
|
- [ ] **Upload Success Rate:** 99% of valid image uploads succeed on first attempt
|
|
- [ ] **Cross-Browser Compatibility:** Application works identically on all supported browsers
|
|
- [ ] **Accessibility Compliance:** Application passes WCAG 2.1 AA automated testing suite
|
|
- [ ] **Mobile Usability:** Users can successfully create and edit boards on tablet devices
|
|
- [ ] **Collaboration Success:** Users can successfully share boards and recipients can access within 1 minute
|
|
- [ ] **Export Reliability:** 100% of export operations complete successfully or show clear error
|
|
- [ ] **Non-Destructive Editing:** Users can reset any edited image to original 100% of the time
|
|
- [ ] **Connection Adaptability:** Application loads successfully on 3G connections (1 Mbps) within 10 seconds
|
|
- [ ] **User Satisfaction:** 90%+ of users rate the application "easy to use" in post-launch survey
|
|
- [ ] **Feature Completeness:** All 18 functional requirements fully implemented and testable
|
|
- [ ] **Test Coverage:** ≥80% code coverage maintained across entire codebase
|
|
|
|
## Key Entities
|
|
|
|
High-level description of main concepts in the system:
|
|
|
|
### User
|
|
- Unique identifier
|
|
- Authentication credentials (email, password hash)
|
|
- Profile information (name, preferences)
|
|
- Owns multiple Boards
|
|
- Has access to own Image Library
|
|
- Can receive shared board links
|
|
|
|
### Board
|
|
- Unique identifier
|
|
- Title and description
|
|
- Owner (User reference)
|
|
- Creation and last modified timestamps
|
|
- Privacy setting (private or shareable)
|
|
- Contains multiple Images positioned on canvas
|
|
- Contains multiple Groups
|
|
- Viewport state (zoom, pan, rotation)
|
|
- Auto-save enabled/disabled
|
|
|
|
### Image
|
|
- Unique identifier
|
|
- Original file (full resolution)
|
|
- Thumbnail versions (multiple resolutions)
|
|
- File metadata (filename, size, dimensions, format, upload date)
|
|
- Position on board (X, Y coordinates)
|
|
- Transformations (scale, rotation, crop, opacity, effects)
|
|
- Z-order (layer position)
|
|
- Belongs to zero or one Group
|
|
- Reference count (how many boards use this image)
|
|
|
|
### Group
|
|
- Unique identifier
|
|
- Contains multiple Images
|
|
- Annotation text
|
|
- Color label
|
|
- Position and bounding box
|
|
- Transformation state (can be moved/scaled as unit)
|
|
|
|
### Share Link
|
|
- Unique identifier
|
|
- Associated Board reference
|
|
- Access token (secure, unguessable)
|
|
- Creation timestamp
|
|
- Access count and last accessed timestamp
|
|
- Active/revoked status
|
|
|
|
### Image Library
|
|
- User's collection of all uploaded images
|
|
- Organized by upload date, filename
|
|
- Shared across all user's boards
|
|
- Images can be added to multiple boards
|
|
|
|
## Assumptions
|
|
|
|
Based on the feature description, we're making these informed assumptions:
|
|
|
|
1. **Authentication Method:** Email/password authentication with secure session management (industry standard for web apps)
|
|
|
|
2. **Single User Type:** All authenticated users have the same capabilities (no admin/editor/viewer roles beyond board sharing)
|
|
|
|
3. **Board Editing:** Only board owner can edit; shared links provide read-only access
|
|
|
|
4. **Image Storage:** Images stored in cloud-compatible storage (filesystem or object storage) with CDN support for optimal delivery
|
|
|
|
5. **Connection Detection:** Slow connection detected using browser Network Information API or download speed test on first load
|
|
|
|
6. **Navigation Order:** Image navigation in focus/slideshow modes follows upload order (chronological) by default
|
|
|
|
7. **Deployment Environment:** Self-hosted deployment on Linux-based servers using Nix for reproducible builds
|
|
|
|
8. **Offline Capability:** Application is online-only (requires internet connection), gracefully handles disconnections
|
|
|
|
9. **Image Formats:** Standard web image formats supported (JPEG, PNG, GIF, WebP, SVG), no RAW or specialized formats
|
|
|
|
10. **Concurrent Editing:** No real-time collaborative editing (multiple users editing same board simultaneously), only sharing for viewing
|
|
|
|
11. **Billing/Payment:** No monetization features in v1.0 (free for all users)
|
|
|
|
12. **Mobile Support:** Optimized for tablet/desktop, mobile phone support is basic (view-only recommended)
|
|
|
|
13. **Browser Requirements:** Modern evergreen browsers (no IE11 support)
|
|
|
|
14. **Language:** English-only interface in v1.0
|
|
|
|
15. **Maximum Limits:** Reasonable limits to prevent abuse: 50MB per image, 500MB per batch upload, 1000 images per board
|
|
|
|
16. **Share Link Permissions:** Configurable per link - owner decides between View-only and View+Comment when generating share link
|
|
|
|
17. **Connection Detection:** Hybrid approach using automatic detection (browser Network Information API + speed test) with manual user override capability
|
|
|
|
18. **Navigation Order Options:** User-configurable with four options: Chronological (default), Spatial, Alphabetical, and Random
|
|
|
|
## Dependencies
|
|
|
|
### External Dependencies (High-Level)
|
|
|
|
- **Web Hosting Infrastructure:** Server environment capable of running modern web applications
|
|
- **Storage System:** File storage with sufficient capacity and performance for image files
|
|
- **HTTPS/SSL Certificates:** Required for secure authentication and data transmission
|
|
- **Email Service:** For password reset and notifications (if implemented)
|
|
- **Browser APIs:** Modern browser support for drag-drop, clipboard, canvas rendering
|
|
|
|
### Internal Dependencies
|
|
|
|
- **User Authentication System:** Required before any board/image operations
|
|
- **File Upload System:** Required before image manipulation features
|
|
- **Image Processing:** Required for generating thumbnails and low-resolution versions
|
|
- **State Management:** Required for canvas operations (undo/redo, auto-save)
|
|
|
|
## Open Issues
|
|
|
|
None - all clarifications resolved.
|
|
|
|
## Rollout Plan
|
|
|
|
1. **Development:** 12-16 week development cycle
|
|
- Weeks 1-4: User authentication, board management, basic image upload
|
|
- Weeks 5-8: Canvas operations, image positioning, transformations
|
|
- Weeks 9-12: Advanced features (groups, command palette, export)
|
|
- Weeks 13-16: Polish, adaptive quality, performance optimization
|
|
|
|
2. **Testing:** 2-week QA cycle
|
|
- Functional testing of all 18 requirements
|
|
- Cross-browser compatibility testing
|
|
- Performance benchmarking under load
|
|
- Accessibility audit
|
|
|
|
3. **Staging:** 1-week validation period
|
|
- Deploy to staging environment with Nix
|
|
- Internal team dogfooding (create real reference boards)
|
|
- Security audit and penetration testing
|
|
- Performance monitoring and optimization
|
|
|
|
4. **Production:** Phased rollout
|
|
- Week 1: Closed beta (50 invited users)
|
|
- Week 2-3: Open beta (public access, feedback collection)
|
|
- Week 4: General availability release
|
|
- Post-launch: Monitor error rates, performance metrics, user feedback
|
|
|
|
5. **Monitoring:** Key metrics to watch
|
|
- Application error rate (<0.1% target)
|
|
- Average page load time (<3s target)
|
|
- API response times (<200ms p95 target)
|
|
- Upload success rate (>99% target)
|
|
- User engagement (boards created, images uploaded)
|
|
- Browser/device distribution
|
|
|
|
## Appendix
|
|
|
|
### References
|
|
|
|
- **PureRef:** Desktop application providing inspiration for feature set (https://www.pureref.com/)
|
|
- **WCAG 2.1 Guidelines:** Web Content Accessibility Guidelines for accessibility compliance
|
|
- **Nix Package Manager:** For reproducible deployment (https://nixos.org/)
|
|
|
|
### Terminology
|
|
|
|
- **Board:** A canvas containing positioned reference images (also called "reference board" or "mood board")
|
|
- **Canvas:** Infinite 2D workspace where images are positioned
|
|
- **Focus Mode:** Full-screen view of a single image, hiding all others
|
|
- **Group:** Collection of images that move together, with shared annotation
|
|
- **Non-Destructive Editing:** Image modifications that don't alter the original file
|
|
- **Z-Order:** Stacking order of overlapping images (which appears in front)
|
|
- **Adaptive Quality:** Serving different image resolutions based on connection speed
|
|
|
|
### Change Log
|
|
|
|
| Version | Date | Author | Changes |
|
|
|---------|------------|--------------|----------------------------|
|
|
| 1.0.0 | 2025-11-02 | Project Team | Initial specification |
|