# 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

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

### Running in Development Mode

1. Clone the repository and navigate to the project directory:
   ```bash
   cd plex-playlist
   ```

2. Start the development environment:
   ```bash
   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

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

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