commit 060ac007a3f4114d97870700f25d7b6571866190 Author: Drew Galbraith Date: Fri Aug 8 00:26:57 2025 -0700 Initial PRD from claude. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..418af9f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,93 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Version Control + +This project uses **Jujutsu (jj)** instead of git for version control. Key differences: +- Use `jj` commands instead of `git` commands +- Every change creates a new revision automatically +- Working copy is separate from the revision graph +- Common commands: + - `jj status` - check working copy status + - `jj log` - view revision history + - `jj new` - create new revision + - `jj describe` - add/edit commit message + - `jj squash` - move changes from working copy to parent revision + +## Project Overview + +Captain's Log is a GTD-inspired personal task management system designed to minimize cognitive overhead while maximizing productivity through context-aware task organization. + +**Core Philosophy**: Capture everything without thinking, see only what matters right now, work efficiently within your current context. + +## Technical Architecture + +### Backend: Rust + Axum + SQLx +- **Framework**: Axum for high-performance HTTP server +- **Database**: SQLx for type-safe database interactions +- **Dev Database**: SQLite for easy setup and portability +- **Production Database**: PostgreSQL for scalability +- **Authentication**: Simple session-based auth (single user) + +### Frontend: Vite + React + Tailwind CSS +- **Build Tool**: Vite for fast development and optimized builds +- **Framework**: React with functional components and hooks +- **Routing**: React Router for client-side navigation +- **Styling**: Tailwind CSS for rapid UI development +- **State Management**: React state with localStorage persistence +- **PWA Features**: Service worker for offline functionality +- **Mobile Optimization**: Touch gestures, responsive design + +### Core Data Models +```sql +-- Tasks (Phase 1 MVP) +tasks (id, title, description, priority, due_date, status, created_at, updated_at, completed_at) + +-- Future phases will add: +-- projects (id, name, description, color, status, created_at, updated_at) +-- contexts (id, name, description, color, icon) +-- task_contexts (task_id, context_id) +-- recurring_patterns (id, task_id, pattern_type, interval_value, days_of_week, monthly_type) +``` + +## Development Commands + +### Testing +```bash +# Backend tests +cargo test +cargo tarpaulin --out Html # Coverage report + +# Frontend tests +npm test # Unit tests +npm run test:e2e # End-to-end tests +npm run test:coverage # Coverage report +``` + +### Development Server +```bash +# Backend (Rust server) +cargo run + +# Frontend (Vite dev server) +npm run dev +``` + +## Current Phase: Core MVP + +**Focus**: Basic task management with CRUD operations +- Task properties: title, description, priority, due_date, status +- Simple web interface with mobile responsiveness +- Testing framework setup with >80% backend coverage target +- RESTful API endpoints for all task operations + +See `/plan/01_CORE_MVP/plan.md` for detailed implementation plan. + +## Future Phases + +1. **Phase 2**: Context tagging system (@computer, @phone, @errands, etc.) +2. **Phase 3**: Project organization and hierarchical structure +3. **Phase 4**: Smart views and anti-overwhelm features +4. **Phase 5**: Recurring tasks and advanced scheduling +5. **Phase 6**: PWA features and offline capability \ No newline at end of file diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..c8794ef --- /dev/null +++ b/PRD.md @@ -0,0 +1,248 @@ +# Captain's Log - Personal Task Management System +## Product Requirements Document (PRD) + +### Executive Summary + +**Problem Statement**: Managing personal tasks effectively without mental overhead or feeling overwhelmed by an endless backlog. + +**Solution**: A GTD-inspired web application that serves as a comprehensive "brain dump" for tasks while providing intelligent, context-aware filtering to surface only relevant, actionable items. + +**Key Value Proposition**: +- Capture everything without thinking +- See only what matters right now +- Work efficiently within your current context + +--- + +### User Persona & Use Cases + +**Primary User**: Individual knowledge worker seeking personal productivity optimization + +**Core Workflows**: +1. **Brain Dump**: Quickly capture tasks without categorization friction +2. **Daily Planning**: Review context-appropriate tasks for the day +3. **Context Switching**: Filter tasks by current availability (@computer, @errands, @phone) +4. **Project Focus**: Deep dive into specific project tasks +5. **Maintenance**: Process recurring tasks and update statuses + +--- + +### Core Features (MVP) + +#### 1. Task Management +- **Quick Capture**: Single-field task entry with smart parsing +- **Task Properties**: + - Title (required) + - Description (optional, markdown supported) + - Priority (High/Medium/Low) + - Due date (optional) + - Project assignment + - Context tags + - Status (Todo/In Progress/Done/Someday) + +#### 2. Context-Based Organization +- **Context Tags**: Predefined and custom contexts + - `@computer` - Requires computer access + - `@phone` - Phone-based tasks + - `@errands` - Location-based tasks + - `@office_hours` - Business hours required + - `@home` - Home-specific tasks + - `@online` - Internet required + - `@focused` - Deep work time needed +- **Context Filtering**: Show only tasks doable in current context +- **Multi-Context Support**: Tasks can have multiple context requirements + +#### 3. Project Organization +- **Hierarchical Projects**: Simple folder-like structure +- **Project Views**: Filter all tasks by project +- **Project Status**: Active/On Hold/Completed +- **Project Metadata**: Description, color coding + +#### 4. Smart Views (Anti-Overwhelm Features) +- **Today**: Limited view (max 7 tasks) based on due dates and priorities +- **This Week**: Week-ahead planning view +- **By Context**: Tasks filtered by selected context +- **By Project**: Project-focused task lists +- **Overdue**: Past-due items requiring attention +- **Someday/Maybe**: Future consideration items + +#### 5. Recurring Tasks +- **Flexible Patterns**: + - Daily, Weekly, Monthly + - Custom intervals (every N days/weeks) + - Day-of-week specifications (every Monday) + - Monthly by date or relative day +- **Context-Aware Recurrence**: Recurring tasks inherit context requirements +- **Smart Scheduling**: Next instance created only after completion + +#### 6. Mobile-Responsive Design +- **Touch-Friendly Interface**: Large tap targets, swipe actions +- **Progressive Web App**: Installable on mobile devices +- **Offline Capability**: Basic functionality without internet +- **Fast Task Entry**: Optimized mobile input experience + +--- + +### Technical Architecture + +#### Frontend: Vite + React +- **Build Tool**: Vite for fast development and optimized builds +- **Framework**: React with functional components and hooks +- **Routing**: React Router for client-side navigation +- **Styling**: Tailwind CSS for rapid UI development +- **State Management**: React state with localStorage persistence +- **PWA Features**: Service worker for offline functionality +- **Mobile Optimization**: Touch gestures, responsive design + +#### Backend: Rust +- **Framework**: Axum for high-performance HTTP server +- **Database**: SQLx for type-safe database interactions +- **Authentication**: Simple session-based auth (single user) +- **API Design**: RESTful endpoints with JSON responses +- **Error Handling**: Structured error responses + +#### Database Design +- **Development**: SQLite for easy setup and portability +- **Production**: PostgreSQL for scalability and advanced features +- **Migration Strategy**: Database abstraction layer using SQLx +- **Schema Management**: Automated migrations + +#### Core Data Models +```sql +-- Projects +projects (id, name, description, color, status, created_at, updated_at) + +-- Contexts +contexts (id, name, description, color, icon) + +-- Tasks +tasks (id, title, description, priority, due_date, status, project_id, created_at, updated_at, completed_at) + +-- Task-Context relationships (many-to-many) +task_contexts (task_id, context_id) + +-- Recurring task patterns +recurring_patterns (id, task_id, pattern_type, interval_value, days_of_week, monthly_type) +``` + +#### Deployment Architecture +- **Containerization**: Docker with multi-stage builds +- **Database**: Separate PostgreSQL container +- **Reverse Proxy**: Nginx for static files and SSL termination +- **VPS Deployment**: Docker Compose for easy deployment +- **Environment Management**: Environment-based configuration + +--- + +### User Experience Design + +#### Design Principles +1. **Minimal Cognitive Load**: Quick capture without forced categorization +2. **Context Awareness**: Show relevant tasks for current situation +3. **Progressive Disclosure**: Essential info visible, details on demand +4. **Visual Hierarchy**: Priority and urgency clearly communicated +5. **Consistent Interactions**: Predictable UI patterns across views + +#### Key Interface Elements +- **Quick Add Bar**: Always-visible task input at top +- **Context Selector**: Prominent context filtering controls +- **Task Cards**: Clean, scannable task representation +- **Smart Badges**: Visual indicators for priority, due dates, contexts +- **Swipe Actions**: Mobile-friendly task interactions (complete, defer, edit) + +#### Anti-Overwhelm Features +- **Limited Daily View**: Maximum 7 tasks to prevent paralysis +- **Defer Actions**: Easy postponement without guilt +- **Batch Operations**: Complete multiple tasks efficiently +- **Focus Mode**: Hide all non-essential UI elements + +--- + +### Future Enhancements (Post-MVP) + +#### Phase 2: Advanced Features +- **Time Estimation**: Task duration tracking and planning +- **Calendar Integration**: Sync with external calendars +- **Notification System**: Smart reminders based on context and location +- **Task Dependencies**: Prerequisite relationships between tasks +- **Templates**: Reusable task patterns for common workflows + +#### Phase 3: Analytics & Insights +- **Completion Analytics**: Personal productivity metrics +- **Context Analysis**: Time spent in different contexts +- **Project Progress**: Visual project completion tracking +- **Habit Tracking**: Recurring task completion patterns + +#### Phase 4: Inspiration & Activities +- **Inspiration List**: Capture "things I'd like to do" separate from tasks + - Activities like "practice piano", "learn photography", "try new recipes" + - Context-aware suggestions (@home activities, @outdoors ideas, etc.) + - Mood/energy level matching (high energy vs. relaxing activities) +- **Boredom Buster**: Smart suggestions based on available time and current context +- **Activity Tracking**: Optional logging of completed inspirational activities +- **Seasonal Suggestions**: Surface relevant activities based on time of year + +--- + +### Success Metrics + +#### Primary Metrics +- **Daily Active Usage**: Regular task capture and completion +- **Task Completion Rate**: Percentage of tasks marked complete vs. abandoned +- **Context Switch Efficiency**: Tasks completed per context session + +#### Secondary Metrics +- **Capture Velocity**: Time from task creation to categorization +- **Mobile Usage**: Percentage of interactions from mobile devices +- **Overwhelm Reduction**: User-reported stress levels (qualitative) + +--- + +### Development Roadmap + +#### Phase 1: Core MVP (4-6 weeks) +1. Database schema and backend API +2. Basic task CRUD operations +3. Project organization +4. Context tagging system +5. Simple web interface +6. Mobile-responsive design + +#### Phase 2: Smart Features (2-3 weeks) +1. Smart views and filtering +2. Recurring task engine +3. Quick capture improvements +4. PWA features + +#### Phase 3: Polish & Deploy (1-2 weeks) +1. UI/UX refinements +2. Performance optimization +3. VPS deployment setup +4. Documentation + +--- + +### Technical Considerations + +#### Scalability +- Single-user system optimized for personal use +- Database designed to handle thousands of tasks efficiently +- Efficient indexing on frequently queried fields + +#### Security +- Session-based authentication for simplicity +- Input validation and sanitization +- Rate limiting on API endpoints +- Secure password storage (if multi-user expansion needed) + +#### Performance +- Lazy loading for large task lists +- Client-side caching with service worker +- Database query optimization +- Optimized build and bundle sizes with Vite + +#### Maintenance +- Automated database backups +- Application logging and monitoring +- Simple deployment pipeline +- Configuration management for different environments