Aniworld/ServerTodo.md

Web Migration TODO: Flask to FastAPI

This document contains tasks for migrating the web application from Flask to FastAPI. Each task should be marked as completed with [x] when finished.

📋 Project Analysis and Setup

Initial Assessment

• Review current Flask application structure in /src/web/ directory
• Identify all Flask routes and their HTTP methods
• Document current template engine usage (Jinja2)
• List all static file serving requirements
• Inventory all middleware and extensions currently used
• Document current error handling patterns
• Review authentication/authorization mechanisms

FastAPI Setup

• Install FastAPI dependencies: pip install fastapi uvicorn jinja2 python-multipart
• Update requirements.txt or pyproject.toml with new dependencies
• Remove Flask dependencies: flask, flask-* packages
• Create new FastAPI application entry point

🔧 Core Application Migration

Main Application Structure

• Create new main.py or update existing app entry point with FastAPI app instance
• Migrate Flask app configuration to FastAPI settings using Pydantic BaseSettings
• Convert Flask blueprints to FastAPI routers
• Update CORS configuration from Flask-CORS to FastAPI CORS middleware

Route Conversion

• Convert all @app.route() decorators to FastAPI route decorators (@app.get(), @app.post(), etc.)
• Update route parameter syntax from <int:id> to {id: int} format
• Convert Flask request object usage (request.form, request.json) to FastAPI request models
• Update response handling from Flask jsonify() to FastAPI automatic JSON serialization
• Convert Flask redirect() and url_for() to FastAPI equivalents

Request/Response Models

• Create Pydantic models for request bodies (replace Flask request parsing)
• Create Pydantic models for response schemas
• Update form handling to use FastAPI Form dependencies
• Convert file upload handling to FastAPI UploadFile

🎨 Template and Static Files Migration

Template Engine Setup

• Configure Jinja2Templates in FastAPI application
• Set up template directory structure
• Create templates directory configuration in FastAPI app

HTML Template Migration

• Review all .html files in templates directory
• Update template rendering from Flask render_template() to FastAPI templates.TemplateResponse()
• Verify Jinja2 syntax compatibility (should be mostly unchanged)
• Update template context passing to match FastAPI pattern
• Test all template variables and filters still work correctly

Static Files Configuration

• Configure StaticFiles mount in FastAPI for CSS, JS, images
• Update static file URL generation in templates
• Verify all CSS file references work correctly
• Verify all JavaScript file references work correctly
• Test image and other asset serving

💻 JavaScript and Frontend Migration

Inline JavaScript Review

• Scan all HTML templates for inline <script> tags
• Review JavaScript code for Flask-specific URL generation (e.g., {{ url_for() }})
• Update AJAX endpoints to match new FastAPI route structure
• Convert Flask CSRF token handling to FastAPI security patterns

External JavaScript Files

• Review all .js files in static directory
• Update API endpoint URLs to match FastAPI routing
• Verify fetch() or XMLHttpRequest calls use correct endpoints
• Update any Flask-specific JavaScript patterns
• Test all JavaScript functionality after migration

CSS Files Review

• Verify all .css files are served correctly
• Check for any Flask-specific CSS patterns or URL references
• Test responsive design and styling after migration

🔐 Security and Middleware Migration

Authentication/Authorization

• Convert Flask-Login or similar to FastAPI security dependencies
• Update session management (FastAPI doesn't have built-in sessions)
• Migrate password hashing and verification
• Convert authentication decorators to FastAPI dependencies

Middleware Migration

• Convert Flask middleware to FastAPI middleware
• Update error handling from Flask error handlers to FastAPI exception handlers
• Migrate request/response interceptors
• Update logging middleware if used

🚀 Application Flow & Setup Features

Setup and Authentication Flow

• Implement application setup detection middleware
• Create setup page template and route for first-time configuration
• Implement configuration file/database setup validation
• Create authentication token validation middleware
• Implement auth page template and routes for login/registration
• Create main application route with authentication dependency
• Implement setup completion tracking in configuration
• Add redirect logic for setup → auth → main application flow
• Create Pydantic models for setup and authentication requests
• Implement session management for authenticated users
• Add token refresh and expiration handling
• Create middleware to enforce application flow priorities

🧪 Testing and Validation

Functional Testing

• Test all web routes return correct responses
• Verify all HTML pages render correctly
• Test all forms submit and process data correctly
• Verify file uploads work (if applicable)
• Test authentication flows (login/logout/registration)

Frontend Testing

• Test all JavaScript functionality
• Verify AJAX calls work correctly
• Test dynamic content loading
• Verify CSS styling is applied correctly
• Test responsive design on different screen sizes

Integration Testing

• Test database connectivity and operations
• Verify API endpoints return correct data
• Test error handling and user feedback
• Verify security features work correctly

📚 Documentation and Cleanup

Code Documentation

• Update API documentation to reflect FastAPI changes
• Add OpenAPI/Swagger documentation (automatic with FastAPI)
• Update README with new setup instructions
• Document any breaking changes or new patterns

Code Cleanup

• Remove unused Flask imports and dependencies
• Clean up any Flask-specific code patterns
• Update imports to use FastAPI equivalents
• Remove deprecated or unused template files
• Clean up static files that are no longer needed

🚀 Deployment and Configuration

Server Configuration

• Update server startup to use uvicorn instead of Flask development server
• Configure production ASGI server (uvicorn, gunicorn with uvicorn workers)
• Update any reverse proxy configuration (nginx, Apache)
• Test application startup and shutdown

Environment Configuration

• Update environment variables for FastAPI
• Configure logging for FastAPI application
• Update any deployment scripts or Docker configurations
• Test application in different environments (dev, staging, prod)

✅ Final Verification

Complete System Test

• Perform end-to-end testing of all user workflows
• Verify performance is acceptable or improved
• Test error scenarios and edge cases
• Confirm all original functionality is preserved
• Validate security measures are in place and working

Monitoring and Observability

• Set up health check endpoints
• Configure metrics collection (if used)
• Set up error monitoring and alerting
• Test logging and debugging capabilities

---

📝 Migration Notes

Important FastAPI Concepts to Remember:

• FastAPI uses async/await by default (but sync functions work too)
• Automatic request/response validation with Pydantic
• Built-in OpenAPI documentation
• Dependency injection system
• Type hints are crucial for FastAPI functionality

Common Gotchas:

• FastAPI doesn't have built-in session support (use external library if needed)
• Template responses need explicit media_type for HTML
• Static file mounting needs to be configured explicitly
• Request object structure is different from Flask

Performance Considerations:

• FastAPI is generally faster than Flask
• Consider using async functions for I/O operations
• Use background tasks for long-running operations
• Implement proper caching strategies