Greenfield Project Tutorial

# Project Constitution: Photo Organizer

## Version
- Version: 1.0.0
- Ratified: 2026-03-01
- Last Amended: 2026-03-01

## Principles

### Article I: Simplicity First
Prioritize simple, maintainable solutions over complex architectures.

**Rules:**
- Use ≤3 libraries beyond the framework
- Avoid abstractions until proven necessary
- Prefer vanilla JS over heavy frameworks

**Rationale**: Simple code is easier to maintain and has fewer bugs.

### Article II: Performance by Design
The application MUST handle thousands of photos efficiently.

**Rules:**
- Virtual scrolling for large collections (>100 items)
- Lazy loading for thumbnails
- Database queries optimized with indexes
- No operation should block the UI thread >16ms

**Rationale**: User experience depends on responsive performance.

### Article III: Test-Driven Quality
All features must have comprehensive test coverage.

**Rules:**
- Unit tests for business logic
- Integration tests for database operations
- E2E tests for critical user journeys
- Tests written before implementation (TDD)

**Rationale**: Testing catches regressions and ensures reliability.

### Article IV: Local-First Architecture
User data MUST remain on their local machine.

**Rules:**
- No cloud storage or uploads
- Photos referenced by filesystem path
- Metadata stored in local SQLite database
- Offline-capable by default

**Rationale**: Privacy and user data ownership are non-negotiable.

### User Story 1 - View Album Collection (Priority: P1)

Users can see all their photo albums displayed in a grid, sorted by date, with thumbnail previews.

**Why this priority**: Core value - without viewing albums, no other features matter.

**Independent Test**: Can be tested by creating test albums and verifying display. Delivers immediate value by showing existing photo organization.

**Acceptance Scenarios**:

1. **Given** user has 10 albums, **When** they open the app, **Then** all 10 albums are displayed in a grid sorted by creation date (newest first)
2. **Given** an album has 100 photos, **When** album is displayed, **Then** the first 4 photos are shown as a preview thumbnail collage
3. **Given** user has 500 albums, **When** they scroll the album list, **Then** albums load smoothly without lag using virtual scrolling

### User Story 2 - Create and Manage Albums (Priority: P1)

Users can create new albums, rename albums, and delete albums.

**Why this priority**: Essential for organizing photos - users need to create structure before adding content.

**Independent Test**: Can be tested by creating, renaming, and deleting albums. Delivers value by enabling organization.

**Acceptance Scenarios**:

1. **Given** user clicks "New Album", **When** they enter a name, **Then** a new empty album is created with the current date
2. **Given** user right-clicks an album, **When** they select "Rename", **Then** they can edit the album name inline
3. **Given** user selects an album and presses Delete, **When** they confirm, **Then** the album and all photo references are removed

### User Story 3 - Add Photos to Albums (Priority: P1)

Users can add photos from their local filesystem to albums.

**Why this priority**: Core functionality - users need to populate albums with photos.

**Independent Test**: Can be tested by selecting photos and verifying they appear in albums. Delivers value by enabling photo collection.

**Acceptance Scenarios**:

1. **Given** user opens an album, **When** they click "Add Photos" and select files, **Then** selected photos are added to the album
2. **Given** user drags files from their filesystem onto an album, **When** they drop the files, **Then** photos are added to that album
3. **Given** user adds 1000 photos to an album, **When** photos are added, **Then** the process completes within 5 seconds

### User Story 4 - Drag and Drop Organization (Priority: P2)

Users can drag photos between albums and reorder albums.

**Why this priority**: Enhances UX but basic organization works without it.

**Independent Test**: Can be tested by dragging photos and albums. Delivers value by improving organization efficiency.

**Acceptance Scenarios**:

1. **Given** user drags a photo from one album, **When** they drop it on another album, **Then** the photo moves to the target album
2. **Given** user drags an album, **When** they drop it in a new position, **Then** the album order is updated and persisted
3. **Given** user drags multiple selected photos, **When** they drop them on an album, **Then** all selected photos move together

### Functional Requirements

- **FR-001**: System MUST store album metadata (id, name, created_date, sort_order) in local SQLite database
- **FR-002**: System MUST store photo metadata (id, album_id, filepath, thumbnail_path, capture_date, file_size) in local SQLite database
- **FR-003**: System MUST reference photo files by absolute filesystem path without copying/moving original files
- **FR-004**: System MUST generate thumbnail images (200x200px) and cache them in application directory
- **FR-005**: System MUST support JPEG, PNG, HEIC, and WebP image formats
- **FR-006**: System MUST use virtual scrolling for album lists with >100 albums
- **FR-007**: System MUST use virtual scrolling for photo grids with >100 photos
- **FR-008**: System MUST extract EXIF metadata (capture date) from photos when available
- **FR-009**: System MUST handle missing or moved photo files gracefully with placeholder thumbnails
- **FR-010**: System MUST persist drag-and-drop reordering immediately to database

## Success Criteria

### Measurable Outcomes

- **SC-001**: Application loads and displays 500 albums within 2 seconds
- **SC-002**: Scrolling through 1000 photos maintains 60fps (no frame drops)
- **SC-003**: Adding 100 photos to an album completes within 5 seconds
- **SC-004**: Drag-and-drop operations complete with <100ms perceived latency
- **SC-005**: Thumbnail generation for 1000 photos completes in background within 30 seconds
- **SC-006**: Album creation completes within 500ms
- **SC-007**: Database queries for album/photo lists complete within 50ms
- **SC-008**: Application uses <100MB memory with 10,000 photos loaded

## Question 1: Thumbnail Storage

**Context**: The spec mentions generating thumbnails but doesn't specify where they're stored.

**What we need to know**: Where should thumbnail images be stored?

**Suggested Answers**:

| Option | Answer | Implications |
|--------|--------|-------------|
| A | Store in application data directory (`~/.photo-organizer/thumbnails/`) | Clean separation, requires disk space, persists across app restarts |
| B | Store in system temp directory | Automatic cleanup, regenerates on restart, saves disk space |
| C | Store in SQLite as blobs | Single database file, increases DB size, slower queries |
| Custom | Provide your own answer | Explain your preferred approach |

**Your choice**: A - Store in application data directory for persistence

## Constitution Check

### Article I: Simplicity First
✓ PASS - Using vanilla JS, no React/Vue/Angular
✓ PASS - Only 2 libraries: Vite (dev tool) + sql.js (database)
✓ PASS - No unnecessary abstractions

### Article II: Performance by Design
✓ PASS - Virtual scrolling for large lists
✓ PASS - Web Worker for thumbnail generation (non-blocking)
✓ PASS - Database indexes on common queries
✓ PASS - IndexedDB for thumbnail caching

### Article III: Test-Driven Quality
✓ PASS - Unit tests for database operations
✓ PASS - Integration tests for file handling
✓ PASS - E2E tests for drag-and-drop workflows

### Article IV: Local-First Architecture
✓ PASS - No cloud APIs or uploads
✓ PASS - Photos stay in original locations
✓ PASS - Metadata in local SQLite
✓ PASS - Offline-capable (no network required)

**RESULT**: All principles satisfied. Proceed to Phase 0.

# Task Breakdown: Photo Album Organizer

## Phase 1: Core Data Layer

### Tasks

1. **[P] Set up project structure**
   - File: `package.json`, `vite.config.js`
   - Initialize Vite project
   - Install sql.js dependency
   - Configure build settings

2. **[P] Create SQLite schema**
   - File: `src/db/schema.sql`
   - Create albums table with indexes
   - Create photos table with indexes
   - Add foreign key constraints

3. **[P] Implement database wrapper**
   - File: `src/db/database.js`
   - Initialize sql.js
   - Create CRUD operations for albums
   - Create CRUD operations for photos
   - Add transaction support

4. **Write database tests**
   - File: `tests/db/database.test.js`
   - Test album CRUD operations
   - Test photo CRUD operations
   - Test transaction rollback
   - Test database persistence

**Checkpoint**: All database tests passing, can create/read/update/delete albums and photos

---

## Phase 2: Thumbnail Generation

### Tasks

1. **[P] Create Web Worker for thumbnail generation**
   - File: `src/workers/thumbnail-worker.js`
   - Accept photo file and generate 200x200 thumbnail
   - Use Canvas API for resizing
   - Extract EXIF metadata (capture date)
   - Return thumbnail as blob

2. **[P] Implement thumbnail cache**
   - File: `src/services/thumbnail-cache.js`
   - Store thumbnails in IndexedDB
   - Implement LRU eviction (max 10,000 thumbnails)
   - Add cache hit/miss tracking

3. **[P] Create thumbnail service**
   - File: `src/services/thumbnail-service.js`
   - Coordinate Web Worker and cache
   - Queue thumbnail generation requests
   - Prioritize visible thumbnails

4. **Write thumbnail tests**
   - File: `tests/services/thumbnail-service.test.js`
   - Test thumbnail generation
   - Test cache hit/miss scenarios
   - Test prioritization logic
   - Test worker error handling

**Checkpoint**: Can generate thumbnails without blocking UI, cache works correctly

---

## Phase 3: Album Grid UI

### Tasks

1. **Create album grid component**
   - File: `src/components/album-grid.js`
   - Render albums in responsive grid
   - Display 2x2 photo preview collage
   - Show album name and photo count
   - Handle empty albums

2. **Implement virtual scrolling**
   - File: `src/components/virtual-scroll.js`
   - Use IntersectionObserver API
   - Render only visible albums (+buffer)
   - Recycle DOM elements
   - Maintain scroll position

3. **Add album actions**
   - File: `src/components/album-actions.js`
   - Create new album dialog
   - Rename album inline editing
   - Delete album with confirmation
   - Update UI optimistically

4. **Write UI tests**
   - File: `tests/components/album-grid.test.js`
   - Test album rendering
   - Test virtual scrolling
   - Test CRUD operations
   - Test keyboard navigation

**Checkpoint**: Album grid displays, scrolls smoothly with 500+ albums, CRUD works

[... Additional phases for photo grid, drag-and-drop, etc. ...]