refactor: migrate main.py to modular routers and add project roadmap

- Migrated monolithic main.py to feature-scoped routers in app/routers/ - Added GEMINI.md for project context and AI instructional guidelines - Updated README.md with a comprehensive modernization plan (SQL migration, robust scraping DSL, frontend modernization) - Improved authentication with cookie support and modular JS - Updated test suite and documentation
2026-03-24 10:12:04 +00:00
parent 1b5d7f9238
commit d4d8d8a3b6
42 changed files with 4518 additions and 2426 deletions
@@ -0,0 +1,101 @@
+# GEMINI.md - Project Context & Instructions
+
+This file provides foundational context and instructions for AI agents working on the **Ohm Stream Downloader** project.
+
+## 🚀 Project Overview
+
+**Ohm Stream Downloader** is a full-stack web application designed for searching, streaming, and downloading anime and TV series from various French and international providers. It features a modern SPA-like interface, automated watchlist tracking, and integration with ecosystem tools like Sonarr.
+
+-   **Backend:** Python 3.11+ with **FastAPI**, Uvicorn, Pydantic (v2), and APScheduler.
+-   **Frontend:** Vanilla JavaScript (modular), Jinja2 templates, and CSS.
+-   **Testing:** Pytest (backend), Vitest & Playwright (frontend).
+-   **Architecture:** Modular routers and a specialized three-tier downloader system.
+
+---
+
+## 🛠️ Quick Start
+
+### Installation
+```bash
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+npm install  # For frontend tests
+```
+
+### Running the Application
+```bash
+# Start development server (Port 3000)
+uvicorn main:app --reload --host 0.0.0.0 --port 3000
+```
+Access the web interface at `http://localhost:3000/web`.
+
+### Running Tests
+```bash
+# Backend (Pytest)
+pytest                          # Run all tests
+pytest -m "unit"                # Fast unit tests
+pytest -m "integration"         # API integration tests
+
+# Frontend (Vitest)
+npm test                        # Run JS tests
+npx playwright test             # E2E tests
+```
+
+---
+
+## 🏗️ Architecture & Core Logic
+
+### Three-Tier Downloader System
+Logic is separated into three distinct layers in `app/downloaders/`:
+1.  **Anime/Series Catalogs** (`anime_sites/`, `series_sites/`): Handles searching, metadata extraction (synopsis, posters), and episode listing (e.g., Anime-Sama, FS7).
+2.  **Video Players** (`video_players/`): Extracts direct download links from embedded players (e.g., VidMoly, DoodStream, 1fichier).
+3.  **Download Manager** (`app/download_manager.py`): Orchestrates the actual file transfer, supporting parallel downloads, pause/resume (via HTTP Range), and progress tracking.
+
+### Key Modules
+-   `app/routers/`: Modular API endpoints (Auth, Anime, Watchlist, Sonarr, etc.).
+-   `app/watchlist.py`: User-specific tracking and automated episode detection.
+-   `app/sonarr_handler.py`: Webhook integration for Sonarr.
+-   `static/js/`: Feature-scoped frontend logic (api.js, auth.js, watchlist-ui.js, etc.).
+
+---
+
+## 📝 Development Conventions
+
+### Coding Style (Python)
+-   **Formatting:** PEP 8, 120 chars max line length.
+-   **Typing:** Use explicit Pydantic models and type hints (`Optional[X]`, `list[X]`).
+-   **Async:** Always use `async/await` for I/O (httpx, aiofiles).
+-   **Naming:** `snake_case` for functions/variables, `PascalCase` for classes/enums.
+
+### Security & Safety
+-   **Filename Sanitization:** ALWAYS use `app.utils.sanitize_filename()` before any disk write.
+-   **Path Validation:** Use `app.utils.is_safe_filename()` to prevent traversal attacks.
+-   **Authentication:** JWT-based. `JWT_SECRET_KEY` must be at least 32 chars and never the default.
+-   **Secrets:** Never hardcode. Use `.env` (via `app/config.py`).
+
+### Testing Requirements
+-   All new features **must** include tests in `tests/`.
+-   Use pytest markers: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.network`.
+-   Verify changes with `pytest --cov=app` to ensure coverage.
+
+---
+
+## ⚙️ Configuration
+
+-   **Environment:** `.env` file (see `.env.example`).
+-   **JSON Storage:** Data persists in `config/` (users, watchlist, sonarr mappings).
+-   **Downloads:** Default directory is `downloads/`.
+
+## 📂 Key File Map
+| Path | Purpose |
+| :--- | :--- |
+| `main.py` | App entry & middleware |
+| `app/models/` | Pydantic schemas |
+| `app/routers/` | API Route definitions |
+| `app/downloaders/` | Provider-specific scraping logic |
+| `templates/` | HTML (Jinja2) |
+| `static/js/` | Frontend logic |
+| `config/` | Persistent JSON data |
+
+---
+*For detailed developer guides, refer to `CLAUDE.md` and `AGENTS.md`.*