Plex Playlist Project

A full-stack application for managing Plex playlists with a FastAPI backend and Vue.js frontend.

Architecture

• Backend: Python 3.14 + FastAPI + uv + ruff
• Frontend: TypeScript + Vue.js + Vite
• Database: PostgreSQL 16
• Containerization: Docker + Docker Compose

Deployable Runtime Contract

Deployable image requirements are defined in:

• docs/DEPLOYABLE_RUNTIME_CONTRACT.md
• docs/adr/ADR003-deployable_runtime_image_contract.md

These documents define backend/frontend runtime boundaries, startup and health behavior expectations, environment contracts, and disallowed non-runtime tooling classes in deployable artifacts.

Development Setup

Prerequisites

• Docker and Docker Compose
• Git
• pre-commit (for development)

Code Quality Tools

This project uses comprehensive linting and formatting:

Backend (Python):

• ruff - Fast Python linter and formatter
• pyright - Type checking
• pydoclint - Docstring linting (Google style)

Frontend (TypeScript/Vue):

• eslint - Linting with Vue and TypeScript support
• prettier - Code formatting
• vue-tsc - Vue TypeScript checking
• eslint-plugin-tsdoc - TSDoc documentation linting

Task Runner:

• poethepoet - Unified task runner for development workflows

General:

• pre-commit - Git hooks for automated quality checks
• TOML formatting and validation

Unified Development with Poe

This project uses Poe the Poet for streamlined development:

# Complete setup (installs deps, starts dev environment)
poe setup

# Code quality (format, lint, type-check all code)
poe ci-quick

# Run all tests
poe test-all

# See all available tasks
poe --help

Manual Setup (Alternative)

pip install pre-commit
pre-commit install

Quick Start

Clone the repository, then choose one of these startup paths.

Unified Development

# Complete setup and start development environment
poe setup

# Or manually:
cd backend
pip install -e .
poe dev-env-start

Traditional Setup

# Backend development
cd backend
pip install -e .

# Frontend development
cd frontend
npm install
npm run dev

Docker Development

# Using Poe (recommended)
poe docker-dev-up

# Or directly
docker compose -f compose.dev.yml up --build

Production Build

poe docker-prod-up
# Or: docker compose up --build

Running in Production Mode

docker compose up --build -d

This will start:

• PostgreSQL database on port 5432
• FastAPI backend on port 8000
• Vue.js frontend on port 80

Project Structure

plex-playlist/
├── backend/                 # FastAPI backend
├── frontend/               # Vue.js frontend
│   └── nginx.conf          # Nginx configuration
├── Dockerfile.backend      # Backend Docker image
├── Dockerfile.frontend     # Frontend Docker image
├── compose.yml             # Production Docker Compose
├── compose.dev.yml         # Development Docker Compose override
└── README.md

CI Operations

For Gitea Actions runner image mirror maintenance, use:

• source scripts/gitea-actions/repair_runner_mirror.xsh
• source scripts/gitea-actions/check_runner_images.xsh (checks ubuntu:22.04, GHCR act image, local mirror, and Renovate image)
• source scripts/gitea-actions/collect_runner_diagnostics.xsh [since] [trace_id]

For setup-stage failures with sparse logs, use:

• source scripts/gitea-actions/runner-prechange-capture.xsh [tail_lines]
• source scripts/gitea-actions/diagnose_runner_startup.xsh

For full troubleshooting context, see docs/GITEA_ACTIONS_TROUBLESHOOTING.md.

Environment Variables

Backend

• DATABASE_URL: PostgreSQL connection string
• BACKEND_REQUIRED_PYTHON: Runtime policy baseline (3.14 default)
• ENVIRONMENT: development or production
• RELOAD: Enable uvicorn auto-reload (development only)

Frontend

• No required runtime environment variables for production nginx serving

Database

The PostgreSQL database is configured with:

• Database: plex_playlist
• User: plex_user
• Password: plex_password

Development Workflow

1. Make changes to your code
2. The development containers will automatically reload:
   • Backend: uvicorn with --reload flag
   • Frontend: Vite dev server with hot module replacement

API Documentation

When running, the FastAPI automatic documentation is available at:

• Development: http://localhost:8001/docs
• Production: http://localhost:8000/docs

---

Manual Setup (if not using Docker)

Backend Setup (FastAPI, Python 3.14, uv, ruff, pyright)

1. Create and activate the uv virtual environment

cd backend
uv venv .venv
source .venv/bin/activate

2. Install dependencies

uv sync --all-groups

3. Install dev tools

uv run poe format
uv run poe lint
uv run poe test

4. Project structure

• src/backend/ - FastAPI application code
• tests/ - Test suite
• pyrightconfig.json - Pyright type checking config
• pyproject.toml - Ruff, pytest, and task configuration

5. Run the development server

uv run uvicorn backend.main:app --reload --app-dir src

---

Frontend Setup (Vue 3, Vite, TypeScript)

1. Create the project

cd frontend
npm create vite@latest . -- --template vue-ts
npm install

2. Recommended: Enable strictest TypeScript settings

Edit tsconfig.json and set:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

3. Run the frontend

npm run dev

---

Documentation

Development & Workflow

• Development Environment Setup
  • Comprehensive guide for setting up your development environment, git workflow, pre-commit hooks, manual tool usage, and CI/CD pipeline understanding
• Poe Task Reference
  • Complete guide to unified development tasks and workflows using Poe the Poet
• Deployable Runtime Contract
  • Canonical backend/frontend deployable runtime image requirements and exclusions
• ADR003: Deployable Runtime Image Contract Boundaries
  • Architectural decision that locks deployable image boundary policy

Architecture & CI/CD

• CI/CD Multi-stage Build
  • Docker multi-stage build strategy, architecture decisions, and performance optimizations
• CI/CD Troubleshooting Guide
  • Comprehensive troubleshooting, optimization decisions, and performance monitoring for Docker builds and E2E testing
• CI/CD Success Summary
  • Complete validation results and performance metrics for the optimized pipeline

Dependency Management & Automation

• Renovate Bot Setup
  • Automated dependency updates with Renovate for Python, Node.js, and Docker dependencies

Operations & Troubleshooting

• Gitea Actions Troubleshooting
  • Solutions for CI/CD pipeline issues, including the critical "jobs waiting forever" problem
• Secure Docker CI/CD
  • Security considerations and setup for Docker-based CI/CD pipelines

See the backend/ and frontend/ folders for more details.