taskplaner/.planning/research/SUMMARY.md

# Project Research Summary

**Project:** TaskPlaner - Personal Task/Notes Web App
**Domain:** Single-user, self-hosted task and notes management with image attachment capabilities
**Researched:** 2026-01-29
**Confidence:** HIGH

## Executive Summary

This is a personal task and notes management application designed for self-hosted, single-user deployment with a focus on capturing both typed entries and digitized paper notes via image attachments. Expert developers in this domain prioritize simplicity over scalability, leveraging SQLite for persistence, filesystem storage for images, and modern full-stack frameworks that minimize operational complexity. The recommended approach is a modular monolith using SvelteKit with SQLite, avoiding microservices and external dependencies that add unnecessary overhead for single-user scenarios.

The key success factors are: (1) keeping the stack minimal but modern (SvelteKit + SQLite + better-sqlite3), (2) designing the data model to support both tasks and thoughts as a unified entity type rather than separate systems, and (3) implementing image storage on the filesystem with database references from day one to avoid painful migrations later. The architecture should follow a modular monolith pattern with clear internal boundaries (repository pattern, service layer) while maintaining deployment simplicity through containerization.

Critical risks include storing images directly in the database (bloats database, slow backups), missing mobile camera capture support (primary use case for digitizing paper notes), and over-engineering the task/thought distinction into separate systems. These are mitigated by: filesystem-based content-addressable image storage, mobile-first responsive design with HTML5 camera API integration, and a unified data model with a simple type discriminator field.

## Key Findings

### Recommended Stack

The research strongly recommends SvelteKit as the full-stack framework due to its exceptional developer experience for solo projects, small bundle sizes (30% faster load times vs React/Vue), and built-in SSR with API routes that eliminate the need for a separate backend. Svelte 5's runes provide explicit reactivity without virtual DOM overhead, making it ideal for responsive single-user applications.

**Core technologies:**
- **SvelteKit 2.50.x + Svelte 5.49.x**: Full-stack framework with built-in routing, SSR, and API routes — best DX for solo/small projects with minimal runtime overhead
- **SQLite 3.x + better-sqlite3 12.x**: Zero-config, serverless database with FTS5 full-text search built-in — 20-39% faster than alternatives, perfect for single-user apps with no separate database service to manage
- **TypeScript 5.x**: Type safety with first-class Svelte/SvelteKit support — catches bugs early and provides excellent IDE integration
- **Drizzle ORM 0.45.x**: Lightweight, type-safe SQL abstraction — code-first schema in TypeScript with ~7.4kb footprint and no runtime overhead
- **Tailwind CSS 4.1.x**: Utility-first CSS with zero runtime overhead — automatic purging keeps CSS tiny, great for rapid prototyping
- **sharp 0.34.x**: High-performance image processing — 4-5x faster than ImageMagick for thumbnail generation and optimization

**Supporting tools:**
- Node.js 22 LTS runtime (required for better-sqlite3 native bindings)
- Docker multi-stage builds for minimal production images (~70MB with Alpine base)
- Zod for form and API input validation
- nanoid for URL-safe unique ID generation

### Expected Features

Based on competitor analysis (Todoist, Bear, Simplenote, Evernote, Obsidian), the feature landscape is well-defined with clear table stakes and differentiators.

**Must have (table stakes):**
- Create/Edit/Delete items with task vs thought distinction — fundamental CRUD with type differentiation
- Mark tasks complete — core task management; every competitor has this
- Image attachments — project requirement for digitizing paper notes
- Tags for organization — standard pattern across all competitors
- Full-text search — users expect to find content quickly
- Mobile-responsive UI — "any device" access means mobile must work well
- Cross-device access via web — inherently provided by web app architecture
- Quick capture mode — minimal friction input is essential for habit formation

**Should have (competitive advantage):**
- Dark mode — low complexity, high user satisfaction
- Keyboard shortcuts — power user efficiency
- Pin/favorite items — quick access to important entries
- Export to JSON/Markdown — data portability and user ownership
- Due dates on tasks — natural extension of task management
- Drag-and-drop reorder — intuitive organization UX

**Defer to v2+ (nice to have):**
- Markdown support — adds complexity to editing
- Natural language date parsing ("tomorrow", "next Monday")
- Recurring tasks — adds state machine complexity
- OCR on images — requires external service/library
- Note linking with backlinks — changes user mental model
- Offline support with PWA — significant complexity (service worker, sync conflict resolution)

### Architecture Approach

The recommended architecture is a modular monolith with clear internal boundaries, avoiding microservices complexity while maintaining clean separation of concerns. This provides simple deployment (single container) with easy debugging and no network overhead between components, while enabling testability through repository pattern abstraction.

**Major components:**
1. **Web Frontend (SPA)** — Svelte 5 components with client-side routing, handles UI rendering and user interaction with optimistic updates
2. **REST API (SvelteKit routes)** — Business logic, validation, and orchestration with separate route handlers for notes, tasks, tags, search, and upload
3. **Repository Layer** — Data access abstraction using repository pattern to enable testing with mocks and future database changes if needed
4. **SQLite Database** — Primary data persistence with FTS5 virtual tables for full-text search (auto-updated via triggers)
5. **File Storage** — Content-addressable filesystem storage for images using SHA256 hash as filename for automatic deduplication

**Key architectural patterns:**
- Modular monolith with clear domain boundaries but single deployment
- Repository pattern for testable, database-agnostic business logic
- Content-addressable storage for images (hash as filename enables cache-forever and deduplication)
- Unified data model for notes/tasks (single table with type discriminator, not separate tables)
- FTS5 triggers for automatic search index updates on data changes

### Critical Pitfalls

1. **Storing images in database as BLOBs** — Database grows massive, backups become slow, migrations become painful. Solution: Store images on filesystem (content-addressable with hash-based naming), store only file path/hash in database. This must be correct from Phase 1 as migrating images out of database later is a high-cost recovery operation.

2. **No server-side image upload validation** — Users accidentally upload 50MB RAW files, server crashes, storage fills up, or malicious files get stored. Solution: Validate file type using magic bytes (not just extension), enforce reasonable size limits (e.g., 10MB), reject non-image MIME types, and convert/resize large images on upload.

3. **Mobile camera capture doesn't work** — Desktop testing passes but mobile fails with wrong orientation (EXIF rotation ignored), camera doesn't trigger, or UI doesn't fit viewport. Solution: Use `<input type="file" accept="image/*" capture="environment">` for mobile camera, handle EXIF orientation server-side, test on actual mobile devices early, design mobile-first.

4. **Tagging system becomes complex or inconsistent** — Either over-engineered (hierarchical tags, colors, descriptions) or under-thought (no autocomplete, "work" vs "Work" vs "WORK" as separate tags). Solution: Start with flat tags, implement case-insensitive matching, provide autocomplete from existing tags, resist adding features until proven needed.

5. **No data export or backup strategy** — Database corruption, accidental deletion, or wanting to migrate to different system with no recovery path. Solution: Design export from day one (JSON + image files), document data format, use named Docker volumes with explicit backup strategy.

## Implications for Roadmap

Based on research findings, the project should be structured in 7 phases following component dependencies and architectural layering patterns:

### Phase 1: Foundation & Data Model
**Rationale:** Must establish correct storage patterns before building features. Image storage strategy and unified entry model are critical architectural decisions that are painful to change later (PITFALLS.md: "high cost recovery" for images in database).

**Delivers:** SQLite database with migrations, basic schema (unified notes table with type field), repository layer for data access, filesystem storage structure for future images.

**Addresses:** Unified task/thought distinction (FEATURES.md: table stakes), prevents database storage pitfall (PITFALLS.md: critical), enables export-friendly data model (PITFALLS.md).

**Avoids:** Separate tables for tasks vs thoughts (PITFALLS.md: task/thought confusion), images in database (PITFALLS.md: critical pitfall #1).

### Phase 2: Core CRUD & Basic UI
**Rationale:** Get basic functionality working before adding complexity. Repository pattern established in Phase 1 enables rapid API development. User validation comes from being able to create and view entries.

**Delivers:** REST API handlers for notes CRUD, service layer with business logic, basic SvelteKit frontend with note list/create/edit views, task completion status toggle.

**Uses:** SvelteKit API routes (STACK.md), Drizzle ORM for type-safe queries (STACK.md), Svelte 5 components (STACK.md).

**Implements:** REST API layer and Web Frontend components (ARCHITECTURE.md).

**Addresses:** Create/Edit/Delete items (FEATURES.md: P1), mark tasks complete (FEATURES.md: P1), quick capture mode (FEATURES.md: table stakes).

### Phase 3: Image Attachments
**Rationale:** Core project requirement for digitizing paper notes. Depends on data model from Phase 1. Must include mobile camera support as primary use case, not an afterthought.

**Delivers:** File storage abstraction with content-addressable storage, upload API with validation and EXIF handling, attachment records in database, frontend image upload/display with mobile camera integration, image processing with sharp for optimization.

**Uses:** sharp for image processing (STACK.md: 4-5x faster than ImageMagick), content-addressable storage pattern (ARCHITECTURE.md).

**Implements:** Upload API and File Storage components (ARCHITECTURE.md).

**Addresses:** Image attachments (FEATURES.md: P1), mobile camera capture (FEATURES.md: table stakes), mobile-responsive UI (FEATURES.md: P1).

**Avoids:** Images in database (PITFALLS.md: critical #1), no upload validation (PITFALLS.md: critical #2), mobile capture UX disaster (PITFALLS.md: critical #5).

### Phase 4: Tags & Organization
**Rationale:** Tags enhance search (implemented in Phase 5) and provide organization without complex hierarchies. Must keep simple to avoid over-engineering pitfall.

**Delivers:** Tags table and many-to-many junction table, tag CRUD API, autocomplete from existing tags, case-insensitive tag matching, tag filtering in frontend.

**Addresses:** Tags for organization (FEATURES.md: P1).

**Avoids:** Overly complex tagging (PITFALLS.md: critical #3) — resist hierarchies, colors, descriptions until proven needed.

### Phase 5: Search
**Rationale:** Depends on existing content from Phases 2-4 to index. FTS5 must index all text fields including image descriptions to avoid "search doesn't find images" pitfall.

**Delivers:** FTS5 virtual table and triggers for auto-indexing, search API with relevance ranking (BM25), search UI with result highlighting, tag filter integration.

**Uses:** SQLite FTS5 (STACK.md: built-in, zero dependencies), FTS5 Index component (ARCHITECTURE.md).

**Implements:** Search API and FTS5 Index components (ARCHITECTURE.md).

**Addresses:** Full-text search (FEATURES.md: P1), search on image context (PITFALLS.md: critical #4).

**Avoids:** LIKE '%query%' anti-pattern (ARCHITECTURE.md: no ranking, full table scan), missing image context in search (PITFALLS.md).

### Phase 6: Polish & UX Enhancements
**Rationale:** Core functionality complete, now improve user experience with low-complexity, high-impact features. These are proven patterns from competitors.

**Delivers:** Dark mode with theme toggle, keyboard shortcuts for common actions, pin/favorite functionality, drag-and-drop reorder, export to JSON/Markdown, due dates on tasks.

**Addresses:** Dark mode (FEATURES.md: P2), keyboard shortcuts (FEATURES.md: P2), pin/favorite (FEATURES.md: P2), export (FEATURES.md: P2), due dates (FEATURES.md: P2).

**Avoids:** No backup strategy (PITFALLS.md: critical #6) — export implements data portability.

### Phase 7: Containerization & Deployment
**Rationale:** Build and test locally first, containerize last. Docker configuration depends on knowing exact runtime requirements from Phases 1-6.

**Delivers:** Multi-stage Dockerfile (builder + production), docker-compose.yml with volume mounts, environment variable configuration, deployment documentation, backup strategy documentation.

**Uses:** Docker multi-stage builds (STACK.md: reduces image from ~500MB to ~70MB), Node.js 22 Alpine base (STACK.md), named volumes for data persistence (ARCHITECTURE.md).

**Addresses:** Containerized deployment (project requirement), cross-device access (FEATURES.md: table stakes).

**Avoids:** Data loss on container restart (PITFALLS.md: volume mount strategy), missing backup documentation (PITFALLS.md: critical #6).

### Phase Ordering Rationale

- **Foundation first (Phase 1):** Storage patterns must be correct from the start; changing image storage or data model later is high-cost recovery
- **Basic CRUD before features (Phase 2):** Validates architecture decisions with working software before adding complexity
- **Images early (Phase 3):** Core project requirement and primary differentiator; mobile testing provides early validation of responsive design
- **Tags before search (Phase 4):** Search enhancement; simpler to implement tags first then integrate into search
- **Search requires content (Phase 5):** FTS5 indexes existing data from Phases 2-4; no point indexing empty tables
- **Polish after core (Phase 6):** User validation of core features informs which polish features provide most value
- **Containerize last (Phase 7):** Simplifies development; knowing exact runtime dependencies enables optimal Docker configuration

This ordering follows ARCHITECTURE.md's recommended build order and addresses critical pitfalls at the earliest possible phase.

### Research Flags

**Phases likely needing deeper research during planning:**
- **Phase 3 (Images):** Mobile browser camera API quirks, EXIF handling libraries, image optimization parameters — while patterns are known, mobile browser behavior varies and needs verification during implementation
- **Phase 5 (Search):** FTS5 query syntax for ranking, snippet generation, advanced search features — basic usage is documented but optimal configuration may need research

**Phases with standard patterns (skip research-phase):**
- **Phase 1 (Foundation):** SQLite setup and repository pattern are well-documented with established best practices
- **Phase 2 (CRUD):** SvelteKit CRUD is standard framework usage with excellent documentation
- **Phase 4 (Tags):** Many-to-many relationships are fundamental database patterns with clear implementation
- **Phase 6 (Polish):** Dark mode, keyboard shortcuts, export are well-documented patterns with abundant examples
- **Phase 7 (Docker):** Containerization follows official Node.js Docker best practices with clear multi-stage build patterns

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Verified against official releases and documentation. Version numbers confirmed current as of 2026-01-29. Svelte 5.49.0, SvelteKit 2.50.1, Tailwind 4.1, better-sqlite3 benchmarks verified. |
| Features | MEDIUM | Based on competitor analysis via WebFetch (Todoist, Bear, Simplenote, Obsidian, Evernote). Feature categorization is hypothesis until user validation. Table stakes are clearly established across competitors. |
| Architecture | HIGH | Modular monolith, repository pattern, and content-addressable storage are proven patterns with strong documentation. SQLite FTS5 is official feature with comprehensive docs. |
| Pitfalls | MEDIUM | Based on domain experience patterns from training data. Specific issues (images in DB, mobile EXIF, tag complexity) are well-documented problems. WebSearch unavailable for verification of 2026-specific mobile browser quirks. |

**Overall confidence:** HIGH

The stack and architecture recommendations are based on verified current versions and official documentation. Feature expectations are validated against multiple competitors with consistent patterns. Pitfalls are informed by established domain knowledge, though some specifics (particularly mobile browser behavior) should be validated during Phase 3 implementation.

### Gaps to Address

**Mobile browser camera API behavior (2026):** Research based on training data patterns; verify `capture="environment"` attribute support and EXIF rotation handling on target mobile browsers (Safari iOS, Chrome Android) during Phase 3 implementation.

**FTS5 performance at scale:** Research indicates FTS5 is sufficient for "thousands of documents" but doesn't provide specific benchmarks for single-user scenarios. Monitor search performance during Phase 5; if issues arise with >10,000 entries, consider external search engine.

**Image optimization parameters:** Research recommends sharp with WebP conversion and 1920px max width, but optimal quality/size tradeoff should be validated with real user photos during Phase 3. May need tuning based on actual paper note photo characteristics.

**Export format specification:** Research identifies export as critical but doesn't specify exact format. During Phase 6, design export format that balances human readability (JSON) with reimport capability (include schema version, handle image references).

## Sources

### Primary (HIGH confidence)
- [Svelte 5.49.0 Release](https://github.com/sveltejs/svelte/releases) — Current stable version verified
- [SvelteKit 2.50.1 Release](https://github.com/sveltejs/kit/releases) — Current stable version verified
- [SQLite FTS5 Documentation](https://www.sqlite.org/fts5.html) — Built-in full-text search implementation
- [Docker Node.js Best Practices](https://docs.docker.com/guides/nodejs/containerize/) — Official containerization guide
- [better-sqlite3 GitHub](https://github.com/WiseLibs/better-sqlite3) — Performance claims verified
- [sharp Documentation](https://sharp.pixelplumbing.com/) — Image processing API and requirements

### Secondary (MEDIUM confidence)
- Todoist, Bear, Simplenote, Obsidian, Evernote features pages — Verified via WebFetch for competitor analysis
- [Drizzle vs Prisma Comparison](https://betterstack.com/community/guides/scaling-nodejs/drizzle-vs-prisma/) — ORM performance characteristics
- [SQLite Driver Benchmark](https://sqg.dev/blog/sqlite-driver-benchmark) — better-sqlite3 20-39% performance advantage verified
- [Microservices vs Monoliths in 2026](https://www.javacodegeeks.com/2025/12/microservices-vs-monoliths-in-2026-when-each-architecture-wins.html) — Modular monolith recommendation
- Standard Notes, Flatnotes, Evernote architecture documentation — Self-hosting patterns

### Tertiary (LOW confidence, verify during implementation)
- Training data patterns for mobile browser camera API behavior — May have changed since training cutoff
- Image upload architecture patterns from Medium articles — General patterns, not version-specific
- Task manager database schema tutorials — Generic patterns, need adaptation

---
*Research completed: 2026-01-29*
*Ready for roadmap: yes*