# 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`.*