drew/captains-log
1
0
Fork 0
Code Pull requests Packages 2 Activity Actions
captains-log/PRD.md
Drew Galbraith 420a904efe Set colorscheme.
2025-09-22 21:07:26 -07:00

8.8 KiB
Raw Blame History

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: CSS for styling
  • 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

-- 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