captains-log/plan/future_improvements.md

Future Improvements

This document tracks architectural improvements and refactoring opportunities identified during development.

Architecture Refactoring

Repository + Service Pattern Migration

Current State: Using Active Record pattern where TaskModel handles its own persistence and HTTP handlers contain business logic directly.

Future Improvement: Migrate to Repository + Service pattern for better separation of concerns:

// Repository trait for data access abstraction
trait TaskRepository {
    async fn create(&self, task: &NewTask) -> Result<Task>;
    async fn find_by_id(&self, id: Uuid) -> Result<Option<Task>>;
    async fn update(&self, task: &Task) -> Result<Task>;
    async fn delete(&self, id: Uuid) -> Result<()>;
    async fn list_all(&self) -> Result<Vec<Task>>;
}

// Service layer for business logic
struct TaskService {
    repository: Box<dyn TaskRepository>,
}

impl TaskService {
    async fn create_task(&self, title: String, description: Option<String>) -> Result<Task> {
        // Input validation
        // Business rules (e.g., auto-set completed_at when status changes)
        // Call repository
    }
}

Benefits:

• Better testability through repository mocking
• Centralized business logic in service layer
• Cleaner separation between data access, business logic, and HTTP handling
• Easier to add complex business rules as the application grows

Implementation Plan:

1. Create TaskRepository trait and SqliteTaskRepository implementation
2. Move database operations from TaskModel to repository
3. Create TaskService with business logic
4. Update HTTP handlers to use services instead of models directly
5. Add comprehensive unit tests for service layer with mocked repositories

Priority: Medium - Good for maintainability as the codebase grows, but current Active Record pattern works fine for MVP scope.

Documentation & Polish Enhancements

API Documentation

Current State: API endpoints are documented in Hurl tests and code comments.

Future Improvement: Comprehensive API documentation with OpenAPI specification.

Implementation Plan:

• Create OpenAPI spec for all endpoints with examples
• Include request/response schemas and validation rules
• Add error response documentation with status codes
• Create usage examples and common workflows
• Generate interactive documentation (Swagger UI)

Benefits: Better developer experience, easier API integration, clear contract specifications.

Enhanced Error Handling

Current State: Basic error handling with AppError enum and HTTP status codes.

Future Improvement: Production-ready error handling and monitoring.

Implementation Plan:

• Enhance error messages with contextual information
• Implement structured logging for debugging
• Add error tracking and monitoring (e.g., Sentry integration)
• Create error response standardization
• Add comprehensive error scenario testing
• Implement graceful degradation patterns

Benefits: Better debugging experience, improved monitoring, user-friendly error responses.

Project Documentation

Current State: Basic documentation in CLAUDE.md and plan files.

Future Improvement: Comprehensive project documentation for contributors.

Implementation Plan:

• Create detailed README.md with setup instructions
• Document development workflow and contribution guidelines
• Add deployment guides for different environments
• Create architecture decision records (ADRs)
• Add troubleshooting guides and FAQs
• Document database schema and migrations

Benefits: Easier onboarding for new developers, better maintainability, clear deployment process.

Priority: Low-Medium - Important for production deployment and team collaboration, but not critical for MVP functionality.