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.13 + FastAPI + uv + ruff
• Frontend: TypeScript + Vue.js + Vite
• Database: PostgreSQL 16
• Containerization: Docker + Docker Compose

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
• darglint - 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

General:

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

Setting up pre-commit hooks

pip install pre-commit
pre-commit install

Running in Development Mode

1. Clone the repository and navigate to the project directory:

   cd plex-playlist
   

2. Start the development environment:

   docker compose -f compose.yml -f compose.dev.yml up --build
   

This will start:

• PostgreSQL database on port 5433
• FastAPI backend on port 8001 (with hot reload)
• Vue.js frontend on port 5173 (with hot reload)

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

Environment Variables

Backend

• DATABASE_URL: PostgreSQL connection string
• ENVIRONMENT: development or production
• RELOAD: Enable uvicorn auto-reload (development only)

Frontend

• NODE_ENV: development or production

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.13, uv, ruff, pyright)

1. Create and activate the uv virtual environment

uv venv plex-playlist
source plex-playlist/bin/activate

2. Install dependencies

uv pip install fastapi uvicorn[standard]
uv pip install ruff

3. Install dev tools

uv pip install pyright

4. Project structure

• app/ - FastAPI application code
• tests/ - Test suite
• pyrightconfig.json - Pyright type checking config
• ruff.toml - Ruff linter config

5. Run the development server

uvicorn app.main:app --reload

---

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

• Gitea Actions Troubleshooting - Solutions for CI/CD pipeline issues, including the critical "jobs waiting forever" problem

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