gpatti/MediaLore-Web-App
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add agents and readme

Browse Source
This commit is contained in:
Garret Patti
2026-06-28 16:54:51 -04:00
parent 39bd815ff0
commit d48c1e973e
2 changed files with 419 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
AGENTS.md Normal file
View File

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

193
README.md Normal file
View File

@@ -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 <repo-url>
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]