ohm_streaming/GEMINI.md

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

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
npm install  # For frontend tests

Running the Application

# 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

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