PYTV/AGENTS.md

AGENTS.md

What this project is

• PYTV is a Django + Django-Ninja backend (core/, api/, pytv/) with a React/Vite frontend (frontend/) for a "cable TV" style experience.
• Core domain model is in core/models.py: Channel, ScheduleTemplate/ScheduleBlock, Airing, MediaSource, MediaItem.
• API entrypoint is api/api.py; all HTTP API routes are mounted under /api/ in pytv/urls.py.

Architecture and data flow to understand first

• Schedule generation: api/routers/schedule.py -> core/services/scheduler.py (ScheduleGenerator.generate_for_date) -> creates Airing rows.
• Playback signaling: api/routers/channel.py (/channel/{id}/now, /airings) computes exact_playback_offset_seconds for frontend sync.
• Media caching pipeline for YouTube sources:
  • metadata sync only: core/services/youtube.py::sync_source
  • just-in-time download: core/services/cache.py::run_cache + youtube.download_for_airing
  • emergency replacement (<1h before air with no cache): ScheduleGenerator.replace_undownloaded_airings.
• Local media serving in dev uses range-aware endpoint api/views.py::serve_video_with_range mounted at /media/* when DEBUG=True.

Backend conventions (project-specific)

• API style: Django Ninja Schema/Pydantic payloads in routers under api/routers/.
• Auth pattern: session auth + CSRF cookie (api/routers/auth.py); frontend sends withCredentials and X-CSRFToken (frontend/src/api.js).
• Session persistence is settings-driven; use SESSION_COOKIE_AGE/SESSION_EXPIRE_AT_BROWSER_CLOSE in pytv/settings.py (do not hardcode lifetimes in routers/frontend).
• Channel.requires_auth is actively enforced in channel endpoints (/now, /airings, /status).
• Source-rule behavior is business-critical: allow/prefer/avoid/block weighting in core/services/scheduler.py (not just CRUD metadata).
• In api/routers/sources.py, literal routes (e.g. /cache-upcoming) must stay before parameterized routes (explicitly documented in file).

Frontend/backend integration points

• Frontend API client is centralized in frontend/src/api.js (do not scatter fetch logic).
• Dev proxy is configured in frontend/vite.config.js for both /api and /media to http://localhost:8000.
• Channel playback UX depends on frontend/src/components/ChannelTuner.jsx triple-buffer behavior and backend-provided offset.

Developer workflows (discovered commands)

# Local backend (from repo root)
python manage.py migrate
python manage.py runserver 0.0.0.0:8000
python manage.py seed
python manage.py cache_upcoming --hours 24
python manage.py run_cache_worker --interval 600 --hours 24
python manage.py backup_now
python manage.py run_backup_worker --interval 60
python manage.py state --channel <id> --test-generate

# Tests (pytest configured via pytest.ini)
pytest

# Frontend (from frontend/)
npm install
npm run dev
npm run build
npm run lint

# Docker stack (repo root)
docker compose up --build

# Docker migrations (ALWAYS run inside the web container)
docker compose exec web python manage.py migrate

# Local DB reset (admin/dev only, destructive)
docker compose exec web python manage.py flush --no-input
docker compose exec web python manage.py migrate

# Optional: reseed mock data after reset
docker compose exec web python manage.py seed

# Optional: run tests in the same containerized environment
docker compose exec web pytest

Agent execution safety rails

• In this repo, assume the user controls long-running processes. Do not start/stop docker compose up, Django dev server, or Vite dev server unless explicitly asked.
• Prefer read-only investigation first (read_file, targeted tests) before broad edits.
• Keep business logic in core/services/; routers should remain thin orchestration/API layers.
• Preserve public API shapes used by frontend (frontend/src/api.js) unless the task explicitly includes coordinated frontend updates.
• Do not reorder literal and parameterized source routes in api/routers/sources.py in a way that changes URL matching behavior.
• Treat cached_file_path and /media/... URL behavior as compatibility-sensitive; verify signaling paths when changing cache/playback logic.
• Backups are compatibility-sensitive and stored at fixed path /Backups; do not add user-configurable backup destination paths.

Containerized dev/test expectations

• The user runs Docker and dev servers; agents should not spin them up by default.
• If a schema change is introduced, run migrations via container exec, not host Python:
  • docker compose exec web python manage.py makemigrations
  • docker compose exec web python manage.py migrate
• Prefer running validation commands inside web for parity with runtime dependencies (yt-dlp/node/ffprobe path assumptions).
• When sharing run steps in PR notes, provide container commands first, then local equivalents as secondary options.

Testing map and where to extend

• API router tests: api/tests/test_*.py.
• End-to-end domain behavior tests: tests/test_channel_actions.py, tests/test_source_rules.py, tests/test_playback_sync.py, tests/test_channel_auth.py.
• If changing scheduler/cache/youtube logic, update both API-level tests and service-behavior tests.

Practical guardrails for AI agents

• Prefer editing service-layer logic in core/services/ over embedding business rules in routers.
• Preserve idempotent schedule generation semantics (generate_for_date clears/rebuilds block window airings).
• Keep MediaItem.cached_file_path semantics intact: frontend playback and cache status depend on it.
• Validate cross-layer changes by exercising both API endpoints and frontend assumptions around /media/... URLs.