# AniWorld FastAPI Refactoring Instructions

This guide details the steps for refactoring `fastapi_app.py` to improve modularity and maintainability, following project and Copilot conventions.

---

## 1. Move Settings to `src/config/settings.py`

**Goal:**  
Centralize configuration logic.

**Steps:**

3. Update all imports in `fastapi_app.py` and other files to:
    ```python
    from src.config.settings import settings
    ```
4. Ensure `.env` loading and all environment variable logic remains functional.

---

## 2. Move API Endpoint Code to Controllers

**Goal:**  
Organize endpoints by concern.

**Steps:**

1. Create controller modules in `src/server/controllers/`:
    - `auth_controller.py` (authentication endpoints)
    - `anime_controller.py` (anime endpoints)
    - `episode_controller.py` (episode endpoints)
    - `system_controller.py` (system/config/health endpoints)
    - `setup_controller.py` (setup endpoints)
2. In each controller, define a FastAPI `APIRouter` and move relevant endpoint functions from `fastapi_app.py`.
3. Import and include routers in `fastapi_app.py`:
    ```python
    from src.controllers.auth_controller import router as auth_router
    app.include_router(auth_router)
    ```
    Repeat for other controllers.
4. Remove endpoint definitions from `fastapi_app.py` after moving.
5. Ensure all dependencies (e.g., `get_current_user`, models, utilities) are properly imported in controllers.

---

## 3. General Clean-Up

-   Remove unused code/imports from `fastapi_app.py`.
-   Confirm all endpoints are registered via routers.
-   Test application startup and endpoint accessibility.

---

## 4. Coding Conventions

-   Use type hints, docstrings, and PEP8/black formatting.
-   Use dependency injection (`Depends`) and repository pattern.
-   Validate data with Pydantic models.
-   Centralize error handling.
-   Do not hardcode secrets/configs; use `.env`.

---

**Summary:**

-   `Settings` → `src/server/config/settings.py`
-   Endpoints → `src/server/controllers/*_controller.py`
-   Main app setup and router wiring remain in `fastapi_app.py`

---

## 5. Tests (new)

Add unit tests under `src/server/tests/`. Only write tests for:

-   Settings loading/validation
-   Controllers (basic router contracts, inclusion, and minimal runtime sanity)

Guidelines:

-   Use `pytest`.
-   Keep tests deterministic: mock env-vars with `monkeypatch`.
-   Controllers tests should not rely on external services — use `fastapi.TestClient` and import controller `router` objects directly.
-   When the exact setting fields or route paths are unknown, provide templates and TODOs. Update templates to match real field names / route names.
-   Run tests with:
    ```
    pytest -q src/server/tests
    ```

Example test templates to add (place and adapt as needed):

-   settings test template: `src/server/tests/test_settings.py`

    -   Checks that `settings` is a Pydantic BaseSettings-like object and that environment variables affect values. Replace placeholder names with real fields from your `Settings` class.

-   controllers test template: `src/server/tests/test_controllers.py`
    -   Imports controller modules, ensures each exposes a `router`, that the router has at least one route, and that routers can be included in a FastAPI app without raising.

Add these templates and update TODOs to match your actual codebase.