128 lines
No EOL
4.8 KiB
Markdown
128 lines
No EOL
4.8 KiB
Markdown
# 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 |