Aniworld/instruction.md

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:

   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:

   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.