plex-playlist/README.md

# 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/DEPLOYABLE_RUNTIME_CONTRACT.md)
- [docs/adr/ADR003-deployable_runtime_image_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:

```bash
# 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)

```bash
pip install pre-commit
pre-commit install
```

### Quick Start

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

#### Unified Development

```bash
# Complete setup and start development environment
poe setup

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

#### Traditional Setup

```bash
# Backend development
cd backend
pip install -e .

# Frontend development
cd frontend
npm install
npm run dev
```

#### Docker Development

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

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

#### Production Build

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

### Running in Production Mode

```bash
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

```text
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

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

### 2. Install dependencies

```sh
uv sync --all-groups
```

### 3. Install dev tools

```sh
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

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

---

## Frontend Setup (Vue 3, Vite, TypeScript)

### 1. Create the project

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

### 2. Recommended: Enable strictest TypeScript settings

Edit `tsconfig.json` and set:

```json
{
  "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

```sh
npm run dev
```

---

## Documentation

### Development & Workflow

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

### Architecture & CI/CD

- **[CI/CD Multi-stage Build](docs/CICD_MULTI_STAGE_BUILD.md)**
  - Docker multi-stage build strategy, architecture decisions,
    and performance optimizations
- **[CI/CD Troubleshooting Guide](docs/CICD_TROUBLESHOOTING_GUIDE.md)**
  - Comprehensive troubleshooting, optimization decisions,
    and performance monitoring for Docker builds and E2E testing
- **[CI/CD Success Summary](docs/CICD_SUCCESS_SUMMARY.md)**
  - Complete validation results and performance metrics
    for the optimized pipeline

### Dependency Management & Automation

- **[Renovate Bot Setup](docs/RENOVATE_SETUP_GUIDE.md)**
  - Automated dependency updates with Renovate for Python,
    Node.js, and Docker dependencies

### Operations & Troubleshooting

- **[Gitea Actions Troubleshooting](docs/GITEA_ACTIONS_TROUBLESHOOTING.md)**
  - Solutions for CI/CD pipeline issues,
    including the critical "jobs waiting forever" problem
- **[Secure Docker CI/CD](docs/SECURE_DOCKER_CICD.md)**
  - Security considerations and setup for Docker-based CI/CD pipelines

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