add agents and readme
This commit is contained in:
Garret Patti
226
AGENTS.md
Normal file
226
AGENTS.md
Normal 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
|
||||
Reference in New Issue
Block a user