captains-log/plan/01_CORE_MVP/backend.md

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 (Actual Implementation)

captains-log/
├── justfile                       # Task runner for development commands
├── CLAUDE.md                      # Claude Code guidance
├── plan/                          # Implementation plans and documentation
│   ├── 01_CORE_MVP/
│   │   ├── backend.md             # This file
│   │   └── plan.md                # Overall MVP plan
│   └── future_improvements.md     # Architectural improvement opportunities
└── backend/
    ├── Cargo.toml                 # Rust project manifest
    ├── 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 (Active Record)
    │   └── services/
    │       ├── mod.rs            # Error handling and exports
    │       └── tasks.rs          # HTTP handlers for task endpoints
    ├── tests/api/                 # Hurl API integration tests
    │   ├── tasks.hurl            # Main task API tests
    │   ├── list_tasks.hurl       # Task listing tests
    │   ├── update_tasks.hurl     # Task update tests
    │   └── delete_tasks.hurl     # Task deletion tests
    └── migrations/
        ├── 20250823023643_create_tasks.up.sql    # Create tasks table
        └── 20250823023643_create_tasks.down.sql  # Drop tasks table

Phase 1: Project Foundation (Days 1-2)

Task 1.1: Initialize Rust Project

• 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

• 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/models/task.rs
  • Create TaskModel struct with SQLx derives
  • Add TaskStatus enum (Todo, Done, Backlog)
  • Implement proper serialization/deserialization
  • Add CRUD methods using Active Record pattern
  • 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/models/task.rs (Active Record Pattern)
  • Implement CRUD operations directly on TaskModel
  • Add SQLx queries for all operations (insert, get_by_id, update, delete, list_all)
  • Include proper error handling
  • Add comprehensive unit tests
  • Expected outcome: All CRUD operations work against database

Task 2.4: Unit Tests for Database Layer

• File: backend/src/models/task.rs (integrated tests)
  • 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 comprehensive model testing

Task 2.5: Test Database Utilities

• File: backend/src/database/connection.rs (create_test_pool function)
  • 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/tasks.rs (HTTP handlers with business logic)
  • Implement HTTP handlers with integrated 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: HTTP layer handles all business logic correctly

Task 3.2: Input Validation

• Files: backend/src/services/tasks.rs, backend/src/models/task.rs
  • Add comprehensive input validation in handlers and model methods
  • Validate required fields, field lengths
  • 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/src/models/task.rs (comprehensive unit tests)
  • Test all model methods with valid/invalid inputs
  • Test business rule enforcement
  • Use in-memory database for testing
  • Test error handling scenarios
  • Expected outcome: Model tests provide comprehensive 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 logging with tracing
  • 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/main.rs (health function)
  • Implement GET /health endpoint
  • Return basic health status
  • Return proper HTTP status codes
  • Expected outcome: Health endpoint returns 200 OK when system is healthy

Task 4.3: Task HTTP Handlers

• File: backend/src/services/tasks.rs
  • Implement all task CRUD endpoints:
    • POST /api/tasks - Create task
    • GET /api/tasks - List tasks
    • GET /api/tasks/{id} - Get single task
    • PUT /api/tasks/{id} - Update task
    • 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/services/mod.rs
  • Implement global error handler (AppError)
  • Add proper HTTP error responses
  • Create error conversion traits
  • Handle validation and database errors
  • Expected outcome: Errors are handled gracefully with proper HTTP status codes

Task 4.5: Integration Tests for HTTP Layer

• File: backend/tests/api/*.hurl
  • Test all endpoints with real HTTP requests using Hurl
  • Use running server for integration tests
  • Test success and error scenarios
  • Comprehensive API contract validation
  • Expected outcome: All integration tests pass

Phase 5: Testing Infrastructure (Day 8)

Task 5.1: Hurl API Tests

• Files: backend/tests/api/*.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: just test-integration passes all tests

Task 5.2: Test Server Orchestration

• Files: Update justfile
  • Add commands to start/stop test server
  • Implement server startup detection
  • Add test runner that manages server lifecycle
  • Create test environment isolation
  • Expected outcome: Tests can run against live server reliably

Task 5.3: Coverage Reporting

• Files: Update justfile, backend/Cargo.toml
  • Configure tarpaulin for coverage reporting
  • Set up HTML coverage reports
  • Add coverage command to justfile
  • Current coverage: 32.41% (35/108 lines)
  • Expected outcome: just test-coverage generates comprehensive coverage report

Task 5.4: Test Documentation

• File: Available in CLAUDE.md and this plan
  • 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

Dependencies and Key Technologies

Core Dependencies (Cargo.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.