captains-log/CLAUDE.md

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

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

# 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

# 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