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

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

• 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/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)

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