Sync from /srv/compose/unified-media-manager

AGENTS.md

@@ -0,0 +1,326 @@
+<!-- GSD:project-start source:PROJECT.md -->
+## Project
+
+**Unified Media Manager (UMM)**
+
+A single Go + React service that replaces the entire \*arr stack (Sonarr, Radarr, Lidarr, Readarr, Prowlarr, Jellyseerr, Bazarr, Recyclarr, Analyzarr — 12 containers) with one unified media management platform. UMM handles media acquisition, download management, quality tracking, and library organization for movies, TV series, music, books, audiobooks, and podcasts.
+
+**Core Value:** Media downloads and imports correctly — searching indexers, grabbing releases, downloading via SABnzbd/qBittorrent, and importing completed files to the library with proper naming and hardlinks. If this works, the arr stack is replaceable.
+
+### Constraints
+
+- **Tech stack**: Go 1.22+ (Echo v4), PostgreSQL 16, React 18 + TypeScript + Tailwind — already chosen and in use
+- **Network**: Backend must share Gluetun's network namespace for VPN-routed indexer/download traffic
+- **Filesystem**: Hardlinking requires download dir and media library on same filesystem (TrueNAS NFS)
+- **Compatibility**: File naming conventions must match existing library structure so Jellyfin/Navidrome/Calibre continue working
+- **Protocol**: Must support Torznab/Newznab XML APIs and Cardigann YAML definitions for indexer compatibility
+- **Existing services preserved**: Gluetun, SABnzbd, qBittorrent, FlareSolverr, Tdarr — UMM replaces acquisition/management layer only
+<!-- GSD:project-end -->
+
+<!-- GSD:stack-start source:codebase/STACK.md -->
+## Technology Stack
+
+## Languages
+- Go 1.22 — Backend API server, all `internal/` and `cmd/` packages
+- TypeScript 5.4+ — Frontend React application in `frontend/src/`
+- SQL (PostgreSQL dialect) — Database schema in `internal/db/migrations/`
+- YAML — Docker Compose config (`docker-compose.yml`)
+- Nginx config — Frontend reverse proxy (`frontend/nginx.conf`)
+## Runtime
+- Backend: Linux container (Alpine 3.19), compiled with `CGO_ENABLED=0`
+- Frontend: Node.js 20-alpine (build), Nginx Alpine (serve)
+- Docker + Docker Compose v3.8
+- Go Modules — `go.mod` + `go.sum` present
+- npm — `frontend/package-lock.json` present (lockfile committed)
+## Frameworks
+- Echo v4.12.0 — Go HTTP framework for REST API (`github.com/labstack/echo/v4`)
+- React 18.3.1 — Frontend UI library
+- React Router DOM 6.23.1 — Client-side routing
+- Tailwind CSS 3.4.4 — Utility-first CSS framework
+- No testing framework detected — no test files, no test config
+- Vite 5.3.1 — Frontend build tool and dev server
+- @vitejs/plugin-react 4.3.0 — Vite React plugin
+- PostCSS 8.4.38 + Autoprefixer 10.4.19 — CSS processing pipeline
+- Multi-stage Docker builds — `backend/Dockerfile` and `frontend/Dockerfile`
+## Key Dependencies
+- `github.com/labstack/echo/v4` v4.12.0 — HTTP routing, middleware, JSON binding
+- `github.com/jackc/pgx/v5` v5.5.5 — PostgreSQL driver and connection pool
+- `github.com/jackc/pgx/v5/pgxpool` — Connection pool (used in `internal/db/db.go`)
+- `log/slog` (stdlib) — Structured logging
+- `react` ^18.3.1 + `react-dom` ^18.3.1 — UI rendering
+- `react-router-dom` ^6.23.1 — SPA routing
+- PostgreSQL 16 (external) — Primary database, shared instance at `postgres-shared:5432`
+- Nginx (Alpine) — Frontend static file server + API reverse proxy
+- Traefik (external) — TLS termination and routing at `umm.local.tophermayor.com`
+## Configuration
+- Config loaded from env vars in `internal/config/config.go`
+- `DATABASE_URL` — PostgreSQL connection string (default: `postgres://localhost:5432/unified_media_manager?sslmode=disable`)
+- `QDRANT_URL` — Qdrant vector DB URL (default: `http://localhost:6333`)
+- `OLLAMA_URL` — Ollama AI service URL (default: `http://localhost:11434`)
+- `PORT` — Backend HTTP port (default: `8084`)
+- `VITE_API_URL` — Frontend API base URL (build-time, default: `http://umm.local.tophermayor.com`)
+- Backend: `go build -o /umm ./cmd/server/` via multi-stage Dockerfile
+- Frontend: `tsc && vite build` → output to `frontend/dist/`
+- Backend currently copies `frontend/dist/` into binary container (see `backend/Dockerfile:13`)
+## Platform Requirements
+- Go 1.22+ SDK
+- Node.js 20+
+- Docker + Docker Compose
+- PostgreSQL 16 accessible (or use Docker default)
+- Docker host with external network `proxy-net`
+- PostgreSQL instance (shared, `postgres-shared:5432`)
+- Traefik reverse proxy on same Docker network
+- Gluetun VPN container (planned: backend will use `network_mode: service:gluetun`)
+- NFS mount from TrueNAS for media files (`/mnt/truenas/mediadata:/data`)
+## Database Schema
+- 3 custom enum types: `MEDIA_TYPE`, `MEDIA_STATUS`, `QUEUE_STATUS`
+- 24 tables total across single `umm` database
+- Partitioned `media` table (9 partitions by media type)
+- Partitioned `download_history` (time-range partitioning, 90-day retention)
+- Full-text search via GIN index on `media.title`
+- JSONB columns for flexible metadata (`external_ids`, `metadata`, `images`, `quality`)
+- Migration system: embedded SQL files in `internal/db/migrations/`, tracked via `schema_migrations` table
+<!-- GSD:stack-end -->
+
+<!-- GSD:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+## Project Overview
+## Naming Patterns
+### Go (Backend)
+- Use short, lowercase, single-word package names: `api`, `db`, `config`
+- Package `internal/api/` contains all HTTP handlers in a single package (no sub-packages)
+- Package `internal/db/` contains database pool, migrations, and embedded SQL files
+- Package `internal/config/` contains environment config loading
+- One domain entity per file: `media.go`, `queue.go`, `blocklist.go`, `indexers.go`, `dashboard.go`, `health.go`
+- File names are lowercase, singular: `router.go`, not `routers.go`
+- Use `_test.go` suffix for tests (none exist yet)
+- Handler factory functions use the pattern `func <verb><Entity>(database *db.DB) echo.HandlerFunc` — e.g., `listMedia`, `createMedia`, `updateMedia`, `deleteMedia`
+- Private helper functions use camelCase: `parsePagination`, `buildMediaWhere`, `scanMedia`, `scanMediaRows`
+- Scanner functions accept an interface: `func scanQueueItem(scanner interface{ Scan(...interface{}) error })`
+- Constants for column lists: `const queueColumns = \`id, media_id, ...\``
+- Local variables: camelCase — `pageSize`, `totalPages`, `setClauses`
+- Struct fields: PascalCase — `TotalPages`, `PageSize`, `ReleaseTitle`
+- Abbreviations stay uppercase: `ID`, `URL`, `API` — e.g., `MediaID`, `ReleaseURL`, `APIKey`
+- Exported structs: PascalCase — `Media`, `QueueItem`, `BlocklistItem`, `Indexer`, `DashboardStats`
+- Request DTOs: PascalCase with `Request` suffix — `createMediaRequest`, `updateMediaRequest`
+- Response DTOs: PascalCase with `Response` suffix — `mediaDetailResponse`, `paginatedResponse`
+- Use unexported structs for request/response types that don't leave the package
+- JSON tags use snake_case: `` `json:"media_type"` ``, `` `json:"release_title"` ``
+- Use `omitempty` on nullable/optional fields: `` `json:"original_title,omitempty"` ``
+- Required fields never have `omitempty`
+### TypeScript (Frontend)
+- PascalCase for components: `Dashboard.tsx`, `Library.tsx`, `Queue.tsx`
+- camelCase for utilities: `client.ts`
+- Directories: lowercase — `pages/`, `api/`, `components/`
+- Default exports for page components: `export default function Dashboard()`
+- Functional components only (no class components)
+- One component per file
+- camelCase: `search`, `typeFilter`, `fetchAPI`
+- PascalCase for types/interfaces: `DashboardData`
+- Generic type parameter: `<T>` in API functions
+- Generic fetch wrappers in `frontend/src/api/client.ts`
+- Three functions: `fetchAPI<T>`, `postAPI<T>`, `deleteAPI<T>`
+## Code Style
+### Go Formatting & Linting
+- Use `gofmt` / `goimports` — standard Go formatting
+- Tabs for indentation (Go standard)
+- No linter config detected (no `.golangci.yml`)
+- Follow standard Go conventions
+- Grouped imports: stdlib first, then project imports, then third-party
+- Error wrapping with `fmt.Errorf("verb: %w", err)` — never raw error return
+- Struct literal field alignment not enforced but generally consistent
+### TypeScript Formatting & Linting
+- No Prettier config detected
+- 2-space indentation
+- Single quotes for strings (JSX attributes use double quotes in some places)
+- Trailing commas not enforced
+- No ESLint config detected in the project (only in node_modules)
+- `strict: true` enabled
+- `noUncheckedIndexedAccess: true` — must check array/object access
+- `exactOptionalPropertyTypes: true` — optional properties must be explicitly `undefined`
+- `verbatimModuleSyntax: true` — use `import type` for type-only imports
+- `jsx: "react-jsx"` — automatic JSX runtime (no need to import React in every file)
+- `isolatedModules: true` — Vite compatibility
+## Import Organization
+### Go
+### TypeScript
+- None configured — use relative paths: `'../api/client'`, `'./pages/Dashboard'`
+## Error Handling
+### Go Backend
+- Always return `map[string]string{"error": "message"}` for error JSON
+- Use appropriate HTTP status codes:
+- Wrap errors with context using `fmt.Errorf("verb: %w", err)`
+- Log with `slog.Error("message", "key", value, "error", err)` before returning HTTP error
+- Check `tag.RowsAffected()` after UPDATE/DELETE for not-found detection
+- Every handler creates a context with timeout: `context.WithTimeout(c.Request().Context(), <duration>)`
+- Read operations: 10-second timeout
+- Write operations: 5-second timeout
+- Indexer test: 15-second timeout
+- Always `defer cancel()` immediately after creating context
+### Frontend
+- `fetchAPI`/`postAPI`/`deleteAPI` throw `Error` on non-OK responses: `throw new Error(\`API error: ${res.status}\`)`
+- Currently swallowing errors in components: `.catch(() => {})` — this needs improvement
+- No global error boundary or toast notification system
+## Logging
+- Use `slog.Info` for startup, shutdown, migration events
+- Use `slog.Error` for all failures before returning HTTP errors
+- Use `slog.Warn` for recoverable issues
+- Key-value pairs use string keys: `"error"`, `"id"`, `"port"`, `"query"`
+- Never use `fmt.Println` or `log.Println` — always use `slog`
+## Comments
+- Public functions: no doc comments in current codebase (should be added)
+- Inline comments for SQL query construction: `// addCol helper for dynamic UPDATE`
+- Column constant definitions explain the SQL: `const mediaColumns = \`...\``
+- No file-level comments
+- No Go doc comments on exported types or functions — this is a gap
+- No JSDoc/TSDoc on frontend functions
+- No inline documentation for complex SQL queries
+## Function Design
+### Go Handlers
+- Always return `c.JSON(statusCode, body)` — never return raw values
+- Success responses use typed structs or `map[string]string{"status": "updated"}`
+- Creation responses return `map[string]int64{"id": id}` with `http.StatusCreated`
+### Frontend Components
+## Database Query Conventions
+### Query Building
+- Define column list constants at file scope: `const queueColumns = \`id, media_id, ...\``
+- Use `fmt.Sprintf("SELECT %s FROM table", columns)` to compose queries
+- Use `deleted_at IS NULL` in WHERE clauses for soft-deleted tables (`media`, `media_files`)
+- Hard delete for `blocklist`, `download_queue` (use status changes instead)
+- Use `parsePagination(c)` to extract `page` and `page_size` from query params
+- Default: page 1, page_size 50, max 100
+- Return `paginatedResponse` struct with `data`, `total`, `page`, `page_size`, `total_pages`
+### NULL Handling
+- Use `sql.NullString`, `sql.NullInt64`, `sql.NullTime` for nullable columns
+- Check `.Valid` then dereference: `if origTitle.Valid { m.OriginalTitle = &origTitle.String }`
+- For `json.RawMessage` nullable fields, use `[]byte` scanner then convert
+## CSS/Styling Conventions
+- Background: `bg-gray-950` (page), `bg-gray-900` (nav/containers), `bg-gray-800` (inputs)
+- Text: `text-white` (primary), `text-gray-400` (secondary), `text-gray-500` (placeholder)
+- Accent: `text-indigo-400`, `focus:border-indigo-500`
+- Status colors: `bg-blue-600`, `bg-green-600`, `bg-red-600`, `bg-orange-600`, etc.
+## Module Design
+### Go Exports
+- `internal/config` → `Config` struct, `Load()` function
+- `internal/db` → `DB` struct, `New()` constructor, `MigrationsFS` embedded FS
+- `internal/api` → `NewRouter()` function (the only entry point into the API layer)
+### Frontend Exports
+## Configuration Conventions
+- Read from environment variables via `os.Getenv()`
+- Provide sensible defaults when env vars are unset
+- Return a `*Config` struct — no global state, passed explicitly
+- Use Vite env: `import.meta.env.VITE_API_URL`
+- Empty string fallback means same-origin API calls
+<!-- GSD:conventions-end -->
+
+<!-- GSD:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+## Pattern Overview
+- Backend serves both API (`/api/*`) and static frontend assets from the same Echo server
+- Frontend is a separate Docker container with nginx that proxies `/api/*` to backend — but backend also has `e.Static("/", "frontend/dist")` as a fallback
+- Handler-per-function pattern: each API endpoint is a standalone function returning `echo.HandlerFunc` via closure over `*db.DB`
+- No service/repository layer — handlers directly execute SQL against `pgxpool.Pool`
+- Database migrations embedded at compile time via `go:embed`
+- PostgreSQL partitioned tables used for multi-tenant media types and time-bounded history
+## Layers
+- Purpose: Route registration, middleware, request parsing, response serialization
+- Location: `internal/api/router.go`
+- Contains: Echo route group definitions, CORS config, pagination helpers
+- Depends on: Echo v4 framework, `internal/config`, `internal/db`
+- Used by: `cmd/server/main.go` which calls `api.NewRouter()`
+- Purpose: Per-resource CRUD handlers — business logic and SQL queries are inline
+- Location: `internal/api/*.go` (one file per domain: `media.go`, `queue.go`, `blocklist.go`, `indexers.go`, `dashboard.go`, `health.go`)
+- Contains: Type structs (request/response), scan helpers, handler functions
+- Depends on: `internal/db` (for `*db.DB` pool access), `pgx/v5` for scanning
+- Used by: Router layer via closure: `g.GET("/media", listMedia(database))`
+- Purpose: Connection pool management, migration runner
+- Location: `internal/db/db.go`
+- Contains: `DB` struct wrapping `pgxpool.Pool`, `New()` constructor, `RunMigrations()` method
+- Depends on: `pgx/v5/pgxpool`, embedded `migrations/*.sql` files
+- Used by: All handler functions, `cmd/server/main.go`
+- Purpose: Environment variable loading with defaults
+- Location: `internal/config/config.go`
+- Contains: `Config` struct with `DatabaseURL`, `QdrantURL`, `OllamaURL`, `Port`
+- Depends on: `os` standard library only
+- Used by: `cmd/server/main.go`, `internal/api/health.go`
+- Purpose: User interface for media management
+- Location: `frontend/src/`
+- Contains: React components, API client wrapper, Tailwind-styled pages
+- Depends on: React 18, react-router-dom 6, Tailwind CSS
+- Used by: End users via browser; served by nginx container or backend static fallback
+## Data Flow
+- Backend: Stateless — all state in PostgreSQL. No in-memory caching, no sessions.
+- Frontend: Local `useState` per component. No global state store (no Redux/Zustand). Each page fetches data independently via `useEffect`.
+## Key Abstractions
+- Purpose: Inject `*db.DB` dependency into handlers without global state
+- Examples: `listMedia(database *db.DB) echo.HandlerFunc`, `dashboard(database *db.DB) echo.HandlerFunc`
+- Pattern: Every handler is a function that takes `*db.DB` and returns a closure
+```go
+```
+- Purpose: Standardized envelope for all list endpoints
+- Examples: Used in `listMedia`, `searchMedia`, `searchMissing`, `searchUpgrades`, `listQueue`, `listBlocklist`
+- Pattern: `{data: [], total: N, page: N, page_size: N, total_pages: N}`
+- Purpose: Reusable row scanning for types that appear in both single and multi-row queries
+- Examples: `scanBlocklistItem(scanner interface{ Scan(...interface{}) error })`, `scanQueueItem(scanner)`
+- Pattern: Accept `interface{ Scan(...interface{}) error }` so both `pgx.Row` and `pgx.Rows` can be passed
+- Purpose: Construct parameterized SQL with variable WHERE clauses
+- Examples: `buildMediaWhere()` in `media.go`, inline in `searchMedia`, `listQueue`
+- Pattern: Maintain `idx` counter, build `[]string` conditions, `[]interface{}` args, format with `$N` placeholders
+```go
+```
+- Purpose: Ship SQL migrations inside the compiled binary
+- Example: `internal/db/db.go:17` — `//go:embed migrations/*.sql`
+- Pattern: `embed.FS` read at runtime, sorted lexicographically, applied transactionally
+## Entry Points
+- Location: `cmd/server/main.go`
+- Triggers: Docker container start (`CMD ["./umm"]`)
+- Responsibilities:
+- Location: `frontend/vite.config.ts`
+- Triggers: `npm run dev` (development only)
+- Responsibilities: Vite dev server on port 3000 with HMR
+- Location: `frontend/Dockerfile`
+- Triggers: Docker container start (nginx)
+- Responsibilities: Serves built SPA from `/usr/share/nginx/html`, proxies `/api/*` to backend
+## Error Handling
+- Handlers return `c.JSON(http.StatusN, map[string]string{"error": "message"})` for errors
+- Database errors logged via `slog.Error()` with context fields then returned as HTTP 500
+- Validation errors return HTTP 400 with descriptive message
+- Not-found returns HTTP 404 after checking `tag.RowsAffected() == 0`
+- Scan errors in row iterators are logged and skipped (`continue`) rather than failing the whole request
+- Migration failures are logged as warnings and don't stop server startup (`main.go:33`)
+- All handlers use `context.WithTimeout` (5–15s) with deferred cancel
+- No centralized error middleware
+- No structured error types or error codes
+- No request-level error logging correlation (no request IDs)
+## Cross-Cutting Concerns
+<!-- GSD:architecture-end -->
+
+<!-- GSD:skills-start source:skills/ -->
+## Project Skills
+
+No project skills found. Add skills to any of: `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
+<!-- GSD:skills-end -->
+
+<!-- GSD:workflow-start source:GSD defaults -->
+## GSD Workflow Enforcement
+
+Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
+
+Use these entry points:
+- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
+- `/gsd-debug` for investigation and bug fixing
+- `/gsd-execute-phase` for planned phase work
+
+Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
+<!-- GSD:workflow-end -->
+
+
+
+<!-- GSD:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
+> This section is managed by `generate-OpenCode-profile` -- do not edit manually.
+<!-- GSD:profile-end -->