drew/captains-log
1
0
Fork 0
Code Pull requests Packages 2 Activity Actions

Create a plan for implementing a backend mvp.

Browse source
This commit is contained in:
Drew 2025-08-22 18:13:18 -07:00
parent c337161576
commit cbda65e963
1 changed files with 303 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

303
plan/01_CORE_MVP/backend.md Normal file
View file

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