# 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)
- **Architecture**: Active Record pattern with models handling persistence
- **Testing**: Unit tests + Hurl API integration tests

#### Backend Project Structure
```
backend/
├── src/
│   ├── main.rs                 # Application entry point with health endpoint
│   ├── database/
│   │   ├── mod.rs              # Database module exports
│   │   └── connection.rs       # Database connection utilities
│   ├── models/
│   │   ├── mod.rs              # Models module
│   │   └── task.rs             # TaskModel with CRUD methods
│   └── services/
│       ├── mod.rs              # Error handling and exports
│       └── tasks.rs            # HTTP handlers for task endpoints
├── tests/api/                  # Hurl API integration tests
└── migrations/                 # SQLx database migrations
```

### 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 - Current Implementation)
tasks (id, title, description, status, created_at, updated_at, completed_at)

-- Future phases will add:
-- priority and due_date fields to tasks table
-- 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
just test-unit              # Unit tests (cargo test)
just test-coverage          # Coverage report (tarpaulin HTML)
just test-integration       # API tests (Hurl)

# Individual commands
cargo test                  # Direct unit test execution
hurl --test tests/api/*.hurl # Direct API test execution

# Frontend tests (when implemented)
npm test                    # Unit tests
npm run test:e2e           # End-to-end tests
npm run test:coverage      # Coverage report
```

### Development Server
```bash
# Backend (Rust server)
just dev                    # Run backend server (cargo run)

# Other backend commands
just build                  # Build project
just migrate               # Run database migrations
just reset-db              # Reset database
just fmt                   # Format code
just lint                  # Run clippy

# Frontend (when implemented)
npm run dev                # Vite dev server
```

## Current Phase: Core MVP Backend ✅

**Status**: Backend implementation completed
- ✅ Task properties: title, description, status, timestamps
- ✅ RESTful API endpoints for all task operations
- ✅ Testing framework with unit tests and API integration tests
- ✅ Coverage reporting setup (currently 32.41%)
- ⏳ Frontend implementation (next phase)

See `/plan/01_CORE_MVP/backend.md` for implementation details.
See `/plan/future_improvements.md` for architectural enhancement opportunities.

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