root
d4d8d8a3b6
- 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
102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# 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`.*
|