1 Development-Guide

xpltd_admin edited this page 2026-04-03 23:05:51 -06:00

Table of Contents

• Development Guide
• Testing
• Backend (pytest)
• Frontend (Vitest)
• Linting
• CI/CD
• CI (.github/workflows/ci.yml)
• Publish (.github/workflows/publish.yml)
• Code Patterns
• Adding an API Endpoint
• Adding a Theme
• Adding a Background Service
• Conventions

Development Guide

Meta	Value
Repo	xpltdco/media-rip
Page	Development-Guide
Audience	developers, agents
Last Updated	2026-04-04
Status	current

Testing

Backend (pytest)

cd backend
pip install -r requirements.txt
pytest tests/ -v -m "not integration"

14 test files covering: API routes, database, download service, SSE broker, sessions, config, models, themes, health, purge, output templates.

Frontend (Vitest)

cd frontend
npm install
npx vitest run

5 test files covering: Pinia stores, SSE composable, type definitions.

Linting

cd backend && ruff check .
cd frontend && npx vue-tsc --noEmit

CI/CD

CI (.github/workflows/ci.yml)

Runs on every push/PR to main:

1. Backend: ruff lint + pytest
2. Frontend: vue-tsc + vitest
3. Docker: smoke build (no push)

Publish (.github/workflows/publish.yml)

Triggers on v*.*.* tags:

• Multi-arch build (amd64 + arm64)
• Push to ghcr.io/xpltdco/media-rip
• Creates GitHub Release

Code Patterns

Adding an API Endpoint

1. Create/edit router in backend/app/routers/
2. Add Pydantic models in backend/app/models/
3. Register router in backend/app/main.py
4. Add Depends(get_session_id) for session-scoped endpoints
5. Add frontend API call in frontend/src/api/client.ts

Adding a Theme

1. Create CSS file in frontend/src/themes/
2. Define all CSS custom properties (copy existing theme as template)
3. Import in frontend/src/main.ts
4. Add to theme picker component

Adding a Background Service

1. Create service in backend/app/services/
2. Initialize in main.py lifespan context
3. Attach to app.state for access in route handlers
4. Clean up in lifespan shutdown

Conventions

• Python: async/await throughout, Pydantic for validation, ruff for linting
• TypeScript: Vue 3 Composition API, Pinia stores, strict mode
• Files: snake_case (Python), PascalCase (Vue components), camelCase (TS utilities)
• Testing: pytest markers for integration tests (@pytest.mark.integration)