# project-kino

Docker-hosted web GUI for searching and downloading movies/series, with Jellyfin integration.

> **Current runtime snapshot (2026-08-21):** The latest VM207/CT201 FastAPI implementation, browser extension, tests, Docker stack, token monitor, and migration report are under [`runtime-current/`](runtime-current/README.md). The older root frontend/backend/worker layout below remains as project history and has not been overwritten.

## Quick Start

```bash
cp .env.example .env
# edit .env — set DB_PASSWORD, SECRET_KEY, JELLYFIN_URL, JELLYFIN_API_KEY
docker compose up --build
```

- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- Health: http://localhost:8000/health

## Architecture

```
frontend (React/Vite + nginx)
    └─ /api/* → backend (FastAPI)
                    └─ PostgreSQL
worker (Python polling)
    └─ reads pending downloads from DB, simulates job execution
```

## API

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health check |
| GET | /api/search?q= | Search across configured providers |
| POST | /api/downloads | Queue a download |
| GET | /api/downloads | List all downloads |
| GET | /api/downloads/:id | Get one download |
| POST | /api/downloads/:id/retry | Retry a failed download |

## Providers

Providers are operator-configured search sources. The default `mock` provider returns
test data. Add real providers by implementing `BaseProvider` in `backend/src/providers.py`
and registering them in the `_registry`.

No hardcoded piracy sources. All download URLs come from operator-configured providers only.

## Configuration

All secrets via environment variables or `.env` (never committed):

| Variable | Description |
|----------|-------------|
| `DB_PASSWORD` | PostgreSQL password |
| `SECRET_KEY` | App secret key |
| `JELLYFIN_URL` | Jellyfin base URL |
| `JELLYFIN_API_KEY` | Jellyfin API key |
| `MEDIA_PATH` | Local path for downloaded media |