owly-news/backend-rust/ROADMAP.md

Owly News Summariser - Project Roadmap

This document outlines the strategic approach for transforming the project through three phases: Python-to-Rust backend migration, CLI application addition, and Vue-to-Dioxus frontend migration.

Project Structure Strategy

Current Phase: Axum API Setup

owly-news-summariser/
├── src/
│   ├── main.rs              # Entry point (will evolve)
│   ├── db.rs                # Database connection & SQLx setup
│   ├── api.rs               # API module declaration
│   ├── api/                 # API-specific modules (no mod.rs needed)
│   │   ├── routes.rs        # Route definitions
│   │   ├── middleware.rs    # Custom middleware
│   │   └── handlers.rs      # Request handlers & business logic
│   ├── models.rs            # Models module declaration
│   ├── models/              # Data models & database entities
│   │   ├── user.rs
│   │   ├── article.rs
│   │   └── summary.rs
│   ├── services.rs          # Services module declaration
│   ├── services/            # Business logic layer
│   │   ├── news_service.rs
│   │   └── summary_service.rs
│   └── config.rs            # Configuration management
├── migrations/              # SQLx migrations (managed by SQLx CLI)
├── frontend/                # Keep existing Vue frontend for now
└── Cargo.toml

Phase 2: Multi-Binary Structure (API + CLI)

owly-news-summariser/
├── src/
│   ├── lib.rs               # Shared library code
│   ├── bin/
│   │   ├── server.rs        # API server binary
│   │   └── cli.rs           # CLI application binary
│   ├── [same module structure as Phase 1]
├── migrations/
├── frontend/
└── Cargo.toml               # Updated for multiple binaries

Phase 3: Full Rust Stack

owly-news-summariser/
├── src/
│   ├── [same structure as Phase 2]
├── migrations/
├── frontend-dioxus/         # New Dioxus frontend
├── frontend/                # Legacy Vue (to be removed)
└── Cargo.toml

Step-by-Step Process

Phase 1: Axum API Implementation

Step 1: Core Infrastructure Setup

• Set up database connection pooling with SQLx
• Create configuration management system (environment variables, config files)
• Establish error handling patterns with anyhow
• Set up logging infrastructure

Step 2: Data Layer

• Design your database schema and create SQLx migrations using sqlx migrate add
• Create Rust structs that mirror your Python backend's data models
• Implement database access layer with proper async patterns
• Use SQLx's compile-time checked queries

Step 3: API Layer Architecture

• Create modular route structure (users, articles, summaries, etc.)
• Implement middleware for CORS, authentication, logging
• Set up request/response serialization with Serde
• Create proper error responses and status codes

Step 4: Business Logic Migration

• Port your Python backend logic to Rust services
• Maintain API compatibility with your existing Vue frontend
• Implement proper async patterns for external API calls
• Add comprehensive testing

Step 5: Integration & Testing

• Test API endpoints thoroughly
• Ensure Vue frontend works seamlessly with new Rust backend
• Performance testing and optimization
• Deploy and monitor

Phase 2: CLI Application Addition

Step 1: Restructure for Multiple Binaries

• Move API code to src/bin/server.rs
• Create src/bin/cli.rs for CLI application
• Keep shared logic in src/lib.rs
• Update Cargo.toml to support multiple binaries

Step 2: CLI Architecture

• Use clap for command-line argument parsing
• Reuse existing services and models from the API
• Create CLI-specific output formatting
• Implement batch processing capabilities

Step 3: Shared Core Logic

• Extract common functionality into library crates
• Ensure both API and CLI can use the same business logic
• Implement proper configuration management for both contexts

Phase 3: Dioxus Frontend Migration

Step 1: Parallel Development

• Create new frontend-dioxus/ directory
• Keep existing Vue frontend running during development
• Set up Dioxus project structure with proper routing

Step 2: Component Architecture

• Design reusable Dioxus components
• Implement state management (similar to Pinia in Vue)
• Create API client layer for communication with Rust backend

Step 3: Feature Parity

• Port Vue components to Dioxus incrementally
• Ensure UI/UX consistency
• Implement proper error handling and loading states

Step 4: Final Migration

• Switch production traffic to Dioxus frontend
• Remove Vue frontend after thorough testing
• Optimize bundle size and performance

Key Strategic Considerations

1. Modern Rust Practices

• Use modern module structure without mod.rs files
• Leverage SQLx's built-in migration and connection management
• Follow Rust 2018+ edition conventions

2. Maintain Backward Compatibility

• Keep API contracts stable during Vue-to-Dioxus transition
• Use feature flags for gradual rollouts

3. Shared Code Architecture

• Design your core business logic to be framework-agnostic
• Use workspace structure for better code organization
• Consider extracting domain logic into separate crates

4. Testing Strategy

• Unit tests for business logic
• Integration tests for API endpoints
• End-to-end tests for the full stack
• CLI integration tests

5. Configuration Management

• Environment-based configuration
• Support for different deployment scenarios (API-only, CLI-only, full stack)
• Proper secrets management

6. Database Strategy

• Use SQLx migrations for schema evolution (sqlx migrate add/run)
• Leverage compile-time checked queries with SQLx macros
• Implement proper connection pooling and error handling
• Let SQLx handle what it does best - don't reinvent the wheel

What SQLx Handles for You

• Migrations: Use sqlx migrate add <name> to create, sqlx::migrate!() macro to embed
• Connection Pooling: Built-in SqlitePool with configuration options
• Query Safety: Compile-time checked queries prevent SQL injection and typos
• Type Safety: Automatic Rust type mapping from database types