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

**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

1. **Clone the repository**

2. **Unified Development (Recommended):**
   ```bash
   # Complete setup and start development environment
   poe setup

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

3. **Traditional Setup:**
   ```bash
   # Backend development
   cd backend
   pip install -e .

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

4. **Docker Development:**
   ```bash
   # Using Poe (recommended)
   poe docker-dev-up

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

5. **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

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

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

### 2. Install dependencies

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

### 3. Install dev tools

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

```sh
uvicorn app.main:app --reload
```

---

## 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

### 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
- **[Gitea API Token Setup](docs/GITEA_TOKEN_SETUP.md)** - Step-by-step guide for creating organization API tokens with proper permissions

### 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.