Aniworld/instructions.md

# Aniworld Web Application Development Instructions

This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.

## Project Overview

The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.

## Architecture Principles

-   **Single Responsibility**: Each file/class has one clear purpose
-   **Dependency Injection**: Use FastAPI's dependency system
-   **Clean Separation**: Web layer calls core logic, never the reverse
-   **File Size Limit**: Maximum 500 lines per file
-   **Type Hints**: Use comprehensive type annotations
-   **Error Handling**: Proper exception handling and logging

## Additional Implementation Guidelines

### Code Style and Standards

-   **Type Hints**: Use comprehensive type annotations throughout all modules
-   **Docstrings**: Follow PEP 257 for function and class documentation
-   **Error Handling**: Implement custom exception classes with meaningful messages
-   **Logging**: Use structured logging with appropriate log levels
-   **Security**: Validate all inputs and sanitize outputs
-   **Performance**: Use async/await patterns for I/O operations

## 📞 Escalation

If you encounter:

-   Architecture issues requiring design decisions
-   Tests that conflict with documented requirements
-   Breaking changes needed
-   Unclear requirements or expectations

**Document the issue and escalate rather than guessing.**

---

## 📚 Helpful Commands

```bash
# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
```

---

## Implementation Notes

1. **Incremental Development**: Implement features incrementally, testing each component thoroughly before moving to the next
2. **Code Review**: Review all generated code for adherence to project standards
3. **Documentation**: Document all public APIs and complex logic
4. **Testing**: Maintain test coverage above 80% for all new code
5. **Performance**: Profile and optimize critical paths, especially download and streaming operations
6. **Security**: Regular security audits and dependency updates
7. **Monitoring**: Implement comprehensive monitoring and alerting
8. **Maintenance**: Plan for regular maintenance and updates

## Task Completion Checklist

For each task completed:

-   [ ] Implementation follows coding standards
-   [ ] Unit tests written and passing
-   [ ] Integration tests passing
-   [ ] Documentation updated
-   [ ] Error handling implemented
-   [ ] Logging added
-   [ ] Security considerations addressed
-   [ ] Performance validated
-   [ ] Code reviewed
-   [ ] Task marked as complete in instructions.md
-   [ ] Infrastructure.md updated
-   [ ] Changes committed to git; keep your messages in git short and clear
-   [ ] Take the next task

---

### Prerequisites

1. Server is running: `conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload`
2. Password: `Hallo123!`
3. Login via browser at `http://127.0.0.1:8000/login`

### Notes

-   This is a simplification that removes complexity while maintaining core functionality
-   Improves user experience with explicit manual control
-   Easier to understand, test, and maintain
-   Good foundation for future enhancements if needed

---

## 📋 TODO Tasks

### Task 1: Add `get_all_series_from_data_files()` Method to SeriesApp

**Status**: [x] Completed

**Description**: Add a new method to `SeriesApp` that returns all series data found in data files from the filesystem.

**File to Modify**: `src/core/SeriesApp.py`

**Requirements**:

1. Add a new method `get_all_series_from_data_files() -> List[Serie]` to `SeriesApp`
2. This method should scan the `directory_to_search` for all data files
3. Load and return all `Serie` objects found in data files
4. Use the existing `SerieList.load_series()` pattern for file discovery
5. Return an empty list if no data files are found
6. Include proper logging for debugging
7. Method should be synchronous (can be wrapped with `asyncio.to_thread` if needed)

**Implementation Details**:

```python
def get_all_series_from_data_files(self) -> List[Serie]:
    """
    Get all series from data files in the anime directory.

    Scans the directory_to_search for all 'data' files and loads
    the Serie metadata from each file.

    Returns:
        List of Serie objects found in data files
    """
    # Use SerieList's file-based loading to get all series
    # Return list of Serie objects from self.list.keyDict.values()
```

**Acceptance Criteria**:

-   [x] Method exists in `SeriesApp`
-   [x] Method returns `List[Serie]`
-   [x] Method scans filesystem for data files
-   [x] Proper error handling for missing/corrupt files
-   [x] Logging added for operations
-   [x] Unit tests written and passing

---

### Task 2: Sync Series from Data Files to Database on Setup Complete

**Status**: [x] Completed

**Description**: When the application setup is complete (anime directory configured), automatically sync all series from data files to the database.

**Files to Modify**:

-   `src/server/fastapi_app.py` (lifespan function)
-   `src/server/services/` (if needed for service layer)

**Requirements**:

1. After `download_service.initialize()` succeeds in the lifespan function
2. Call `SeriesApp.get_all_series_from_data_files()` to get all series
3. For each series, use `SerieList.add_to_db()` to save to database (uses existing DB schema)
4. Skip series that already exist in database (handled by `add_to_db`)
5. Log the sync progress and results
6. Do NOT modify database model definitions

**Implementation Details**:

```python
# In lifespan function, after download_service.initialize():
try:
    from src.server.database.connection import get_db_session

    # Get all series from data files using SeriesApp
    series_app = SeriesApp(settings.anime_directory)
    all_series = series_app.get_all_series_from_data_files()

    if all_series:
        async with get_db_session() as db:
            serie_list = SerieList(settings.anime_directory, db_session=db, skip_load=True)
            added_count = 0
            for serie in all_series:
                result = await serie_list.add_to_db(serie, db)
                if result:
                    added_count += 1
            await db.commit()
            logger.info("Synced %d new series to database", added_count)
except Exception as e:
    logger.warning("Failed to sync series to database: %s", e)
```

**Acceptance Criteria**:

-   [x] Series from data files are synced to database on startup
-   [x] Existing series in database are not duplicated
-   [x] Database schema is NOT modified
-   [x] Proper error handling (app continues even if sync fails)
-   [x] Logging added for sync operations
-   [x] Integration tests written and passing

---

### Task 3: Validation - Verify Data File to Database Sync

**Status**: [x] Completed

**Description**: Create validation tests to ensure the data file to database sync works correctly.

**File to Create**: `tests/integration/test_data_file_db_sync.py`

**Requirements**:

1. Test `get_all_series_from_data_files()` returns correct data
2. Test that series are correctly added to database
3. Test that duplicate series are not created
4. Test that sync handles empty directories gracefully
5. Test that sync handles corrupt data files gracefully
6. Test end-to-end startup sync behavior

**Test Cases**:

```python
class TestDataFileDbSync:
    """Test data file to database synchronization."""

    async def test_get_all_series_from_data_files_returns_list(self):
        """Test that get_all_series_from_data_files returns a list."""
        pass

    async def test_get_all_series_from_data_files_empty_directory(self):
        """Test behavior with empty anime directory."""
        pass

    async def test_series_sync_to_db_creates_records(self):
        """Test that series are correctly synced to database."""
        pass

    async def test_series_sync_to_db_no_duplicates(self):
        """Test that duplicate series are not created."""
        pass

    async def test_series_sync_handles_corrupt_files(self):
        """Test that corrupt data files don't crash the sync."""
        pass

    async def test_startup_sync_integration(self):
        """Test end-to-end startup sync behavior."""
        pass
```

**Acceptance Criteria**:

-   [x] All test cases implemented
-   [x] Tests use pytest async fixtures
-   [x] Tests use temporary directories for isolation
-   [x] Tests cover happy path and error cases
-   [x] All tests passing
-   [x] Code coverage > 80% for new code

---