# 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