# Backend MVP Implementation Plan

## Overview
This plan details the concrete implementation steps for the Captain's Log backend MVP using Rust + Axum + SQLx with comprehensive testing infrastructure.

## Project Structure
```
captains-log/
├── justfile                       # Task runner for development commands
├── README.md                      # Project documentation
└── backend/
    ├── Cargo.toml                 # Rust project manifest
    ├── .env.example               # Environment variables template
    ├── src/
    │   ├── main.rs               # Application entry point
    │   ├── lib.rs                # Library root with common exports
    │   ├── config.rs             # Configuration management
    │   ├── database/
    │   │   ├── mod.rs            # Database module
    │   │   ├── models.rs         # SQLx models and types
    │   │   └── connection.rs     # Database connection utilities
    │   ├── handlers/
    │   │   ├── mod.rs            # HTTP handlers module
    │   │   ├── tasks.rs          # Task CRUD endpoints
    │   │   └── health.rs         # Health check endpoint
    │   ├── services/
    │   │   ├── mod.rs            # Business logic services
    │   │   └── task_service.rs   # Task business logic
    │   └── utils/
    │       ├── mod.rs            # Utility functions
    │       └── test_helpers.rs   # Testing utilities
    ├── tests/
    │   ├── integration/
    │   │   ├── mod.rs            # Integration test setup
    │   │   ├── tasks_test.rs     # Task API integration tests
    │   │   └── common.rs         # Test database setup helpers
    │   └── api/
    │       ├── tasks.hurl        # Hurl API tests for tasks
    │       └── health.hurl       # Hurl API tests for health
    └── migrations/
        └── 001_create_tasks.sql  # Initial database schema
```

## Phase 1: Project Foundation (Days 1-2)

### Task 1.1: Initialize Rust Project
- [x] **File**: `backend/Cargo.toml`
  - Create new Rust binary project
  - Add core dependencies: axum, sqlx, tokio, serde, uuid, chrono, anyhow
  - Add dev dependencies: tarpaulin for coverage
  - Configure SQLx features for SQLite and runtime
  - **Expected outcome**: `cargo build` succeeds

### Task 1.2: Create Hello World Axum Server
- [x] **Files**: `backend/src/main.rs`, `backend/src/lib.rs`
  - Create basic Axum application with health check endpoint
  - Set up tokio runtime and basic error handling
  - Configure server to listen on localhost:3000
  - Add basic logging with tracing
  - Set up lib.rs with public module exports for testing
  - **Expected outcome**: `cargo run` starts server responding to GET /health

### Task 1.3: Create Development Justfile
- [ ] **File**: `justfile`
  - Initial commands: 'dev', 'build', 'test-unit', 'fmt', 'lint', 'clean'
  - As Needed: `test-api`, `test-coverage`
  - **Expected outcome**: `just --list` shows all commands

## Phase 2: Core Database Layer (Days 3-4)

### Task 2.0: Create Initial Database Migration
- [ ] **File**: `backend/migrations/001_create_tasks.sql`
  - Create tasks table with all required fields
  - Add proper indexes and constraints
  - Include created_at, updated_at triggers if needed
  - Add database justfile commands: `migrate`, `reset-db`
  - **Expected outcome**: `sqlx migrate run` creates table successfully

### Task 2.1: Define Task Model
- [ ] **File**: `backend/src/database/models.rs`
  - Create Task struct with SQLx derives
  - Add TaskStatus and Priority enums
  - Implement proper serialization/deserialization
  - Add validation attributes
  - **Expected outcome**: Models compile without errors

### Task 2.2: Database Connection Pool
- [ ] **File**: `backend/src/database/connection.rs`
  - Set up SQLx connection pool configuration
  - Add connection health checks
  - Create database initialization functions
  - Handle connection errors gracefully
  - **Expected outcome**: Connection pool starts successfully

### Task 2.3: Task Repository Layer
- [ ] **File**: `backend/src/database/mod.rs`
  - Implement TaskRepository trait
  - Add CRUD operations using SQLx queries
  - Include proper error handling
  - Add query builders for filtering/sorting
  - **Expected outcome**: All CRUD operations work against database

### Task 2.4: Unit Tests for Database Layer
- [ ] **File**: `backend/tests/unit/database_test.rs`
  - Test all CRUD operations
  - Test error conditions (not found, constraint violations)
  - Use in-memory SQLite for fast tests
  - Create test fixtures and utilities
  - **Expected outcome**: `cargo test` passes with >80% coverage for database layer

### Task 2.5: Test Database Utilities
- [ ] **File**: `backend/src/utils/test_helpers.rs`
  - Create test database setup/teardown functions
  - Add test data seeding utilities
  - Implement database reset between tests
  - Create assertion helpers for database state
  - **Expected outcome**: Test utilities work reliably across test runs

## Phase 3: Business Logic & Services (Day 5)

### Task 3.1: Task Service Implementation
- [ ] **File**: `backend/src/services/task_service.rs`
  - Implement TaskService with business logic
  - Add input validation and sanitization
  - Handle business rules (e.g., completed_at when status changes)
  - Include proper error types and handling
  - **Expected outcome**: Service layer handles all business logic correctly

### Task 3.2: Input Validation
- [ ] **Files**: `backend/src/services/validation.rs`, update task_service.rs
  - Add comprehensive input validation
  - Validate required fields, field lengths, date formats
  - Create custom error types for validation failures
  - Add validation for business rules
  - **Expected outcome**: Invalid inputs are rejected with clear error messages

### Task 3.3: Service Unit Tests
- [ ] **File**: `backend/tests/unit/task_service_test.rs`
  - Test all service methods with valid/invalid inputs
  - Test business rule enforcement
  - Mock database layer for isolated testing
  - Test error handling scenarios
  - **Expected outcome**: Service tests achieve >90% coverage

## Phase 4: HTTP Layer (Days 6-7)

### Task 4.1: Axum Server Setup
- [ ] **File**: `backend/src/main.rs`
  - Configure Axum application with middleware
  - Set up CORS, logging, and error handling middleware
  - Configure graceful shutdown
  - Add application state management
  - **Expected outcome**: Server starts and responds to basic requests

### Task 4.2: Health Check Endpoint
- [ ] **File**: `backend/src/handlers/health.rs`
  - Implement GET /health endpoint
  - Add database connectivity check
  - Return proper HTTP status codes and JSON responses
  - Include basic system information
  - **Expected outcome**: Health endpoint returns 200 OK when system is healthy

### Task 4.3: Task HTTP Handlers
- [ ] **File**: `backend/src/handlers/tasks.rs`
  - Implement all task CRUD endpoints:
    - `POST /api/tasks` - Create task
    - `GET /api/tasks` - List tasks with optional filtering
    - `GET /api/tasks/{id}` - Get single task
    - `PUT /api/tasks/{id}` - Update task
    - `PATCH /api/tasks/{id}/status` - Update status only
    - `DELETE /api/tasks/{id}` - Delete task
  - **Expected outcome**: All endpoints handle requests and return proper responses

### Task 4.4: Error Handling and Middleware
- [ ] **Files**: `backend/src/handlers/mod.rs`, `backend/src/utils/errors.rs`
  - Implement global error handler
  - Add request logging middleware
  - Create proper HTTP error responses
  - Add request validation middleware
  - **Expected outcome**: Errors are handled gracefully with proper HTTP status codes

### Task 4.5: Integration Tests for HTTP Layer
- [ ] **File**: `backend/tests/integration/tasks_test.rs`
  - Test all endpoints with real HTTP requests
  - Use test database for each test
  - Test success and error scenarios
  - Include authentication/authorization if added
  - **Expected outcome**: All integration tests pass

## Phase 5: Testing Infrastructure (Day 8)

### Task 5.1: Hurl API Tests
- [ ] **Files**: `backend/tests/api/health.hurl`, `backend/tests/api/tasks.hurl`
  - Create comprehensive API tests using Hurl
  - Test all endpoints with various inputs
  - Include negative test cases
  - Test API response formats and status codes
  - **Expected outcome**: `hurl --test backend/tests/api/*.hurl` passes all tests

### Task 5.2: Test Server Orchestration
- [ ] **Files**: Update `justfile`, `backend/tests/integration/common.rs`
  - Add commands to start/stop test server
  - Implement test database management
  - Add test data seeding and cleanup
  - Create test environment isolation
  - **Expected outcome**: Tests can run against live server reliably

### Task 5.3: Coverage Reporting
- [ ] **Files**: Update `justfile`, `backend/.gitignore`
  - Configure tarpaulin for coverage reporting
  - Set up HTML coverage reports
  - Add coverage thresholds and CI integration
  - Exclude test files from coverage metrics
  - **Expected outcome**: `just test-coverage` generates comprehensive coverage report

### Task 5.4: Test Documentation
- [ ] **File**: `backend/tests/README.md`
  - Document how to run different test types
  - Explain test database setup and management
  - Document Hurl test structure and conventions
  - Add troubleshooting guide for common test issues
  - **Expected outcome**: New developers can run all tests successfully

## Phase 6: Documentation & Polish (Day 9)

### Task 6.1: API Documentation
- [ ] **File**: `backend/docs/api.md` or OpenAPI spec
  - Document all endpoints with examples
  - Include request/response schemas
  - Add error response documentation
  - Create usage examples and common workflows
  - **Expected outcome**: API is fully documented

### Task 6.2: Performance Optimization
- [ ] **Files**: Various optimizations across codebase
  - Add database connection pooling optimizations
  - Implement request caching where appropriate
  - Optimize database queries and indexes
  - Add performance benchmarks if needed
  - **Expected outcome**: API responds quickly under normal load

### Task 6.3: Final Error Handling Review
- [ ] **Files**: Review all error handling across project
  - Ensure all errors have proper HTTP status codes
  - Add user-friendly error messages
  - Implement proper logging for debugging
  - Test error scenarios comprehensively
  - **Expected outcome**: All error cases are handled gracefully

### Task 6.4: Project Documentation
- [ ] **File**: `README.md` (project root)
  - Add project setup instructions
  - Document development workflow
  - Include testing instructions
  - Add deployment considerations
  - **Expected outcome**: New developers can get started quickly

## Dependencies and Key Technologies

### Core Dependencies (Cargo.toml)
```toml
[dependencies]
axum = "0.7"
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "sqlite", "uuid", "chrono"] }
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
uuid = { version = "1.0", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
anyhow = "1.0"
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace"] }
tracing = "0.1"
tracing-subscriber = "0.3"

[dev-dependencies]
tarpaulin = "0.27"
```

### Testing Tools
- **Unit Tests**: Standard Rust `cargo test`
- **Integration Tests**: Axum test utilities
- **API Tests**: Hurl for external API testing
- **Coverage**: Tarpaulin for code coverage reporting
- **Database**: In-memory SQLite for fast unit tests, file-based SQLite for integration tests

## Success Criteria
- [ ] All CRUD operations work correctly
- [ ] >80% backend code coverage achieved
- [ ] Integration tests cover all API endpoints
- [ ] Hurl tests validate API contracts
- [ ] Database migrations work correctly
- [ ] Error handling is comprehensive
- [ ] Performance is acceptable for MVP usage
- [ ] Documentation is complete and accurate

## Testing Strategy Summary
1. **Unit Tests**: Fast, isolated tests using in-memory database
2. **Integration Tests**: Full request-response cycle with test database
3. **Hurl Tests**: External API validation against running server
4. **Coverage**: Automated coverage reporting with tarpaulin
5. **CI Ready**: All tests can run in automated environment

This plan provides a comprehensive roadmap for implementing a robust, well-tested backend MVP that meets the requirements outlined in the original plan.md.