From cbda65e963ae12d50a6abc54a240c5cb38ec2eec Mon Sep 17 00:00:00 2001 From: Drew Galbraith Date: Fri, 22 Aug 2025 18:13:18 -0700 Subject: [PATCH] Create a plan for implementing a backend mvp. --- plan/01_CORE_MVP/backend.md | 303 ++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 plan/01_CORE_MVP/backend.md diff --git a/plan/01_CORE_MVP/backend.md b/plan/01_CORE_MVP/backend.md new file mode 100644 index 0000000..e6fe826 --- /dev/null +++ b/plan/01_CORE_MVP/backend.md @@ -0,0 +1,303 @@ +# 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) +```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.