# AGENTS.md

## Project Overview

MediaLore is a **self-hosted media library browser** for images and videos. It provides a web UI for browsing, searching, tagging, and viewing media with thumbnail previews and doom-scroll/TikTok-style consumption. **All access requires authentication** — users must log in before accessing any media or UI pages.

**Monorepo** with two independent apps:
- `backend/` — Python FastAPI server
- `frontend/` — React SPA (TypeScript, Vite)

## Tech Stack

| Layer       | Technology                                              |
|-------------|---------------------------------------------------------|
| Backend     | Python 3.12+, FastAPI, Uvicorn                         |
| Database    | SQLite via SQLAlchemy (async aiosqlite), WAL mode       |
| Migrations  | Alembic                                                 |
| Auth        | JWT (python-jose) + bcrypt password hashing             |
| Thumbnails  | Pillow (images), ffmpeg (videos) — generated on-demand  |
| File Watch  | watchdog — live filesystem monitoring                   |
| Frontend    | React 19, TypeScript 6, Vite 8, React Router 7, TanStack Query v5 |
| Infra       | Docker Compose (backend: Python 3.12-slim, frontend: Nginx Alpine) |

## Directory Structure

```
medialore-web-app/
├── docker-compose.yml        # Orchestration (backend, frontend, volumes)
├── .env.example              # Environment variable template
├── .gitea/
│   └── workflows/
│       └── container-publish.yml  # CI: build & push Docker images
├── backend/
│   ├── Dockerfile
│   ├── pyproject.toml        # Python package config (hatchling build)
│   ├── alembic.ini
│   ├── alembic/              # DB migrations
│   │   ├── env.py
│   │   └── versions/
│   └── app/
│       ├── main.py           # FastAPI app, CORS, lifespan, router registration
│       ├── config.py         # Pydantic Settings (DATABASE_URL, MEDIA_ROOT, etc.)
│       ├── database.py       # SQLAlchemy async engine, session, WAL pragma
│       ├── models.py         # ORM models: Library, MediaItem, Tag, User, media_item_tags
│       ├── schemas.py        # Pydantic request/response schemas (incl. auth)
│       ├── auth.py           # bcrypt hashing, JWT create/decode, auth dependencies
│       ├── routers/
│       │   ├── auth.py       # Login, token validation, user CRUD (admin)
│       │   ├── libraries.py  # Library CRUD, browse, doom-scroll, scan-status, rescan
│       │   ├── media.py      # Media item get, file serve, thumbnail, tag assignment
│       │   ├── tags.py       # Tag CRUD, grouped by category
│       │   └── search.py     # Fuzzy filename + tag search
│       └── services/
│           ├── scanner.py    # Dir walk, SHA-256 hashing, moved file detection
│           ├── watcher.py    # watchdog event handler (create/move/delete)
│           └── thumbnails.py # Pillow + ffmpeg thumbnail generation
└── frontend/
    ├── Dockerfile            # Multi-stage: Node build + Nginx serve
    ├── nginx.conf            # SPA fallback, /api proxy to backend
    ├── package.json
    ├── tsconfig.json         # Root references
    ├── tsconfig.app.json     # App TS config
    ├── tsconfig.node.json    # Vite config TS config
    ├── vite.config.ts        # Vite + React plugin, dev proxy /api -> localhost:8000
    ├── eslint.config.js      # Flat config: JS + TS + React hooks + refresh
    ├── index.html
    ├── public/
    │   ├── favicon.svg
    │   └── icons.svg
    └── src/
        ├── main.tsx          # React entry point
        ├── App.tsx           # Router, QueryClient, sidebar, theme, responsive layout
        ├── index.css         # CSS custom properties for light/dark themes
        ├── api/
        │   └── client.ts     # Typed fetch wrapper; all endpoint functions
        ├── auth/
        │   ├── AuthTypes.ts   # AuthUser, AuthState interfaces, AuthContext
        │   ├── AuthContext.tsx # AuthProvider component (login/logout/token mgmt)
        │   └── useAuth.ts     # useAuth hook
        ├── pages/
        │   ├── LoginPage.tsx
        │   ├── SearchPage.tsx
        │   ├── BrowserPage.tsx
        │   ├── SettingsPage.tsx
        ├── components/
        │   ├── FileBrowser/FileBrowser.tsx
        │   ├── MediaViewer/MediaViewer.tsx
        │   ├── DoomScrollViewer/DoomScrollViewer.tsx
        │   └── TagPanel/TagPanel.tsx
        └── assets/
            ├── hero.png
            └── vite.svg
```

## Common Commands

### Backend

```bash
# Install (from backend/)
pip install -e .

# Run dev server
cd backend && uvicorn app.main:app --reload --port 8000

# Generate a new Alembic migration
cd backend && alembic revision --autogenerate -m "description"

# Apply migrations
cd backend && alembic upgrade head
```

### Frontend

```bash
# Install dependencies (from frontend/)
npm install

# Dev server (proxies /api to localhost:8000)
npm run dev

# Production build
npm run build

# Lint
npm run lint

# Preview production build
npm run preview
```

### Docker

```bash
docker compose up -d
```

## Environment Variables

| Variable                | Default                             | Purpose                      |
|-------------------------|-------------------------------------|------------------------------|
| `DATABASE_URL`          | `sqlite+aiosqlite:////data/medialore.db` | SQLite connection string     |
| `MEDIA_ROOT`            | `/media`                            | Root path for media libraries |
| `THUMBNAIL_DIR`         | `/data/thumbnails`                  | Cached thumbnail storage     |
| `SECRET_KEY`            | auto-generated                      | JWT signing key              |
| `ADMIN_USERNAME`        | `admin`                             | Initial admin user           |
| `ADMIN_PASSWORD`        | (required)                          | Initial admin password       |
| `ACCESS_TOKEN_EXPIRE_DAYS` | `30`                             | JWT token lifetime in days   |

Pydantic Settings reads from `.env` at startup (via `model_config = {"env_file": ".env"}`). For Docker, these are set in `docker-compose.yml`.

## Database

SQLite with **WAL mode** and a 10-second busy timeout (see `app/database.py:14-18`). Tables are auto-created at startup via `Base.metadata.create_all` in the FastAPI lifespan.

### Schema

- **libraries**: `id`, `name`, `path` (unique)
- **media_items**: `id`, `library_id` (FK), `rel_path`, `filename`, `file_hash` (SHA-256), `media_type` ("image" or "video"), `size_bytes`, `missing`, `created_at`, `updated_at` — unique on `(library_id, rel_path)`
- **tags**: `id`, `name`, `category` — unique on `(name, category)`
- **media_item_tags**: `media_item_id` (FK), `tag_id` (FK), composite PK
- **users**: `id`, `username` (unique), `password_hash`, `is_admin`, `created_at`

**Migrations**: Use Alembic. The initial migration is at `backend/alembic/versions/0001_initial_schema.py` and the users table migration at `0002_add_users_table.py`.

## API Conventions

All endpoints are prefixed with `/api`. All responses are JSON except `/api/media/:id/file` (binary stream) and `/api/media/:id/thumbnail` (JPEG).

**All endpoints require authentication** except `POST /api/auth/login`. The `Authorization: Bearer <token>` header must be included. File and thumbnail endpoints also accept `?token=` as a query parameter (for `<img>`/`<video>` tags that can't send headers).

### Auth Endpoints

| Method | Path              | Auth   | Purpose                     |
|--------|-------------------|--------|-----------------------------|
| `POST` | `/auth/login`     | Public | Returns JWT `access_token`  |
| `GET`  | `/auth/me`        | User   | Current user info           |
| `GET`  | `/auth/users`     | Admin  | List all users              |
| `POST` | `/auth/users`     | Admin  | Create a new user           |
| `DELETE` | `/auth/users/{id}` | Admin | Delete a user (not self)   |

### Async Database Access

Routers use FastAPI's `Depends` injection with the `get_db` async generator from `database.py`:

```python
from app.database import get_db

@router.get("/...")
async def endpoint(db: AsyncSession = Depends(get_db)):
    ...
```

### Authentication Dependency

All protected endpoints use `get_current_user` (from `app/auth.py`) as a FastAPI dependency:

```python
from app.auth import get_current_user
from app.models import User

@router.get("/...")
async def endpoint(
    db: AsyncSession = Depends(get_db),
    _user: User = Depends(get_current_user),
):
    ...
```

Admin-only endpoints chain `get_current_admin_user`:

```python
from app.auth import get_current_admin_user

@router.delete("/users/{user_id}")
async def delete_user(
    user_id: int,
    current_user: User = Depends(get_current_admin_user),
    ...
):
```

File and thumbnail endpoints use `get_current_user_from_query_or_header` which accepts the token via `Authorization` header or `?token=` query parameter.

### Frontend API Client

All API calls go through the typed `api` object in `frontend/src/api/client.ts`. Use `useQuery` / `useMutation` from TanStack Query. Never call `fetch` directly from components.

```ts
import { api } from "../api/client";
import { useQuery } from "@tanstack/react-query";

const { data } = useQuery({
  queryKey: ["libraries", id, "browse", path],
  queryFn: () => api.libraries.browse(id, path),
});
```

## Code Patterns & Conventions

### Backend (Python)
- **No linter configured** — follow the existing style (4-space indent, snake_case)
- Models use SQLAlchemy 2.0-style `mapped_column` (not `Column()`)
- Schemas use Pydantic `BaseModel`
- Service modules handle business logic; routers handle HTTP concerns
- Background scanning runs via `asyncio.create_task`; watchers run in separate threads via `watchdog.Observer`
- Logging: use `logging.getLogger(__name__)` — the `app` namespace has a StreamHandler configured in `main.py`
- Auth: use `bcrypt` directly (not passlib) for password hashing; `python-jose` for JWT tokens
- All protected endpoints must include `_user: User = Depends(get_current_user)` as a parameter

### Frontend (TypeScript/React)
- **ESLint flat config** with strict TypeScript-ESLint rules
- Inline `style={{ ... }}` objects for CSS (no CSS modules, no Tailwind)
- TypeScript interfaces for all API types live in `client.ts`
- Components use `useState`/`useEffect`/`useQuery` hooks, not class components
- Theme state persisted in `localStorage` key `"theme"`, applied as `data-theme` attribute
- Auth token persisted in `localStorage` key `"token"`, managed via `AuthProvider` context
- Responsive via `window.matchMedia("(max-width: 767px)")` listener
- File/thumbnail URLs constructed with `api.media.fileUrl(id)` and `api.media.thumbnailUrl(id)` (not fetched)
- API client automatically injects `Authorization: Bearer <token>` header; handles 401 by clearing token

### TypeScript Configuration
- `tsconfig.app.json`: strict mode, `noUnusedLocals`, `noUnusedParameters`, `erasableSyntaxOnly`
- `tsconfig.node.json`: for `vite.config.ts` only
- Build command: `tsc -b && vite build` (type-check via project references)

## Testing

**There are no test files in this project.** No test framework is configured. When adding tests:
- Frontend: consider Vitest (pairs with Vite) + React Testing Library
- Backend: consider pytest + pytest-asyncio + httpx (for FastAPI TestClient)
- No existing test commands in CI, so add them and consider a GitHub Action or similar

## Docker / Deployment

- `docker compose up -d` starts both services
- Images are pulled from the Gitea container registry (`git.gpatti.com/<owner>/medialore-backend` and `...frontend`)
- Backend runs on port 8000 (internal), frontend Nginx on port 80 (mapped to 8080 on host)
- Nginx proxies `/api/` to `http://backend:8000`
- Media paths from the host are volume-mounted into the container at `/media`
- Persistent data (DB, thumbnails) stored in Docker volume `medialore-data`
- Set `OWNER` in `.env` to control which registry namespace images are pulled from

### CI/CD (Gitea Actions)

The workflow at `.gitea/workflows/container-publish.yml` automatically builds and pushes Docker images to the Gitea container registry on push to `main` or version tags (`v*`).

**Required secrets** (set in repo Settings → Actions → Secrets):
| Secret | Purpose |
|--------|---------|
| `REGISTRY_USER` | Gitea username for docker login |
| `REGISTRY_TOKEN` | Gitea PAT with `read:packages` and `write:packages` scopes |

To pull images from the private registry on a host, run `docker login git.gpatti.com` first with the same credentials.

### Local Development (without registry)

For local development without pulling from the registry, switch docker-compose.yml back to local builds:
```yaml
services:
  backend:
    build: ./backend    # instead of image: ...
  frontend:
    build: ./frontend   # instead of image: ...
```

## Important Notes

- **Authentication is required** for all endpoints and UI pages except `/api/auth/login`. JWT tokens are signed with `SECRET_KEY` (auto-generated if unset, so set it for persistent sessions). File/thumbnail endpoints also accept `?token=` as a query parameter since `<img>`/`<video>` tags can't send headers.
- Thumbnails are generated on first request and cached to disk (`THUMBNAIL_DIR`)
- The scanner computes SHA-256 hashes to detect moved/renamed files and avoid re-processing
- File watcher uses watchdog with per-library `PollingObserver` (necessary for Docker volumes)
- `media_items.missing` flag is set when a scanned file no longer exists on disk
- The frontend `build` command runs `tsc -b` first, which checks types across project references — type errors will block the build
- Admin user is created automatically on first startup from `ADMIN_USERNAME`/`ADMIN_PASSWORD` env vars; additional users can be created via the Settings page by an admin