diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e1361d8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,226 @@ +# 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. + +**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 | +| 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 # MEDIA_ROOT env var template +├── 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, THUMBNAIL_DIR) +│ ├── database.py # SQLAlchemy async engine, session, WAL pragma +│ ├── models.py # ORM models: Library, MediaItem, Tag, media_item_tags +│ ├── schemas.py # Pydantic request/response schemas +│ ├── routers/ +│ │ ├── 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 + ├── pages/ + │ ├── 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 | + +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 + +**Migrations**: Use Alembic. The initial migration is at `backend/alembic/versions/0001_initial_schema.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). + +### 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)): + ... +``` + +### 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` + +### 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 +- Responsive via `window.matchMedia("(max-width: 767px)")` listener +- File/thumbnail URLs constructed with `api.media.fileUrl(id)` and `api.media.thumbnailUrl(id)` (not fetched) + +### 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 +- Backend runs on port 8000 (internal), frontend Nginx on port 80 (mapped to 8085 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` + +## Important Notes + +- **No auth/authentication** — CORS allows all origins, no login system +- 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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..4b65455 --- /dev/null +++ b/README.md @@ -0,0 +1,193 @@ +# MediaLore + +A self-hosted media library browser for images and videos. Organize your local media collections with tagged browsing, a file-system explorer, and a full-screen "doom scroll" viewer — all via a clean, responsive web UI. + +## Features + +- **Media Libraries** — Add local directories as named libraries; files are indexed by relative path within each library +- **File Browser** — Navigate your library's directory structure with a thumbnail grid, breadcrumbs, and lazy-loaded previews +- **Tagging System** — Organize media with named tags grouped into categories; create tags inline while viewing items +- **Search** — Filter by filename (fuzzy match), tag, and/or library +- **Doom Scroll** — Full-screen, swipe/scroll-driven media viewer for an immersive, social-media-like experience +- **Live File Watching** — Automatically detects new, moved, and deleted files via `watchdog` (no manual rescans needed) +- **Auto-Generated Thumbnails** — JPEG thumbnails for images (via Pillow) and videos (via ffmpeg) +- **Dark / Light Theme** — Toggle with persistence via `localStorage` +- **Responsive** — Mobile-friendly with a collapsible sidebar and touch gestures + +## Architecture + +``` +┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ Frontend │──────▶│ Backend │──────▶│ SQLite DB │ +│ React + │ HTTP │ FastAPI + │ ORM │ (SQLite + │ +│ TypeScript │ │ Uvicorn │ │ WAL mode) │ +│ Vite │ │ │ │ │ +└─────────────┘ └──────┬───────┘ └─────────────┘ + │ + ┌───────▼────────┐ + │ File System │ + │ (media root) │ + └─────────────────┘ +``` + +**Backend** — Python 3.12+, FastAPI, SQLAlchemy (async), aiosqlite, Alembic for migrations, `watchdog` for file-system events, Pillow for image thumbnails, ffmpeg for video thumbnails. + +**Frontend** — React 19, TypeScript, Vite 8, React Router 7, TanStack Query, Nginx (static serving + API proxy). + +## Quick Start (Docker Compose) + +### Prerequisites + +- Docker & Docker Compose +- ffmpeg (bundled in the backend container) +- Your media files accessible on the host (e.g. mounted from a NAS) + +### 1. Clone & configure + +```bash +git clone +cd MediaLore-Web-App +cp .env.example .env +``` + +Edit `.env` to point `MEDIA_ROOT` to your host media directory: + +```env +MEDIA_ROOT=/mnt/nas +``` + +> **Note:** Inside the container, `$MEDIA_ROOT` maps to `/media`. Library paths you add in the UI must be subdirectories of this mount. + +### 2. Start the stack + +```bash +docker compose up --build -d +``` + +The frontend is available at `http://localhost:8085`. + +### 3. Add a library + +1. Open **Settings** → **Libraries** +2. Enter a name and a path (e.g. `/media/Images/Photos`) +3. Click **Add Library** — scanning begins in the background + +The scanner walks the directory tree, computes SHA-256 hashes, detects moved files by hash, and starts a file watcher for live updates. + +## Docker Compose Configuration + +```yaml +services: + backend: + build: ./backend + volumes: + - medialore-data:/data # DB + thumbnails + - /data/smb/adult/Images:/media/Images + - /data/smb/adult/Video Clips:/media/Video Clips + environment: + - DATABASE_URL=sqlite+aiosqlite:////data/medialore.db + - THUMBNAIL_DIR=/data/thumbnails + + frontend: + build: ./frontend + ports: + - "8085:80" +``` + +Adjust the volume mounts to match your media layout. The `medialore-data` named volume persists the SQLite database and generated thumbnails across restarts. + +## API Endpoints + +All endpoints are under `/api` and return JSON (except file/thumbnail responses). + +### Libraries + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/libraries` | List all libraries | +| `POST` | `/libraries` | Create a library (`{ name, path }`) | +| `GET` | `/libraries/:id/scan-status` | Check if a library is currently scanning | +| `POST` | `/libraries/:id/rescan` | Trigger a manual rescan | +| `GET` | `/libraries/:id/browse` | Browse directory entries (`?path=/sub/dir`) | +| `GET` | `/libraries/:id/doom-scroll` | Get all media items in a library (optionally under a path) | +| `DELETE` | `/libraries/:id` | Remove a library (stops watcher, deletes records) | + +### Media + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/media/:id` | Get media item details (with tags) | +| `GET` | `/media/:id/file` | Stream the original media file | +| `GET` | `/media/:id/thumbnail` | Get or generate a thumbnail (JPEG) | +| `PUT` | `/media/:id/tags` | Set tags on an item (`{ tag_ids: [1, 2] }`) | + +### Tags + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/tags` | List all tags grouped by category | +| `POST` | `/tags` | Create a tag (`{ name, category }`) | +| `DELETE` | `/tags/:id` | Delete a tag | + +### Search + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/search?q=foo&tags=1,2&library_id=3` | Search media by filename, tags, and/or library | + +## Development + +### Backend (local) + +```bash +cd backend +python -m venv .venv +source .venv/bin/activate +pip install -e ".[dev]" # or: pip install fastapi uvicorn[standard] sqlalchemy aiosqlite alembic pydantic-settings watchdog Pillow python-multipart +uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 +``` + +### Frontend (local) + +```bash +cd frontend +npm install +npm run dev +``` + +The Vite dev server runs at `http://localhost:5173`. Configure your proxy or set `VITE_API_BASE` to point to the backend. + +## Data Model + +``` +┌──────────┐ 1..* ┌────────────┐ *..* ┌─────┐ +│ Library │─────────────────▶│ MediaItem │─────────────────▶│ Tag │ +└──────────┘ └────────────┘ └─────┘ + • id • id + • name • library_id + • path • rel_path + • filename + • file_hash (SHA-256) + • media_type (image | video) + • size_bytes + • missing (file deleted from disk) + • created_at + • updated_at + • tags[] +``` + +## Tech Stack + +| Layer | Technology | +|-------|-----------| +| Frontend | React 19, TypeScript, Vite, React Router, TanStack Query | +| Backend | Python 3.12+, FastAPI, Uvicorn | +| Database | SQLite (async via aiosqlite, WAL mode) | +| Migrations | Alembic | +| Thumbnails | Pillow (images), ffmpeg (videos) | +| File Watching | watchdog | +| Containerization | Docker (Python 3.12-slim, Node 20-alpine, Nginx Alpine) | + +## License + +[Add your license here]