SEEN/project.md

# /seen/

/seen/ is a modern self-hosted platform for managing personal movies, TV shows, and games.

It combines the functionality of a media tracker, streaming dashboard, download manager, and recommendation engine into a single application.

The system allows users to discover content, track watched media, manage downloads, watch their personal media library, and manage a game backlog from a single modern dashboard-style interface.

/seen/ is designed to feel like a **personal streaming control center** that runs entirely on your own infrastructure.

---

# Core Philosophy

The platform should be:

- self-hosted
- fast
- modular
- visually premium
- simple to operate
- scalable

This project should **not resemble a generic admin dashboard**.

Instead it should feel like a combination of:

- Plex
- Letterboxd
- Netflix-style UI
- personal media server
- game backlog manager

---

# Core Features

## Personal Media Tracking

Users can:

- mark movies as watched
- mark movies or shows as watch later
- track TV episode progress
- track game completion states
- organize active, paused, completed, and wishlist games
- maintain personal collections
- assign personal ratings
- mark favorites
- view watch history

---

## Continue Watching

Playback progress is tracked per user.

Features include:

- resume playback
- per-episode progress tracking
- automatic watched detection
- dashboard continue watching section

Fast reads for progress are cached using DragonflyDB.

---

## Discover Content

Content discovery is powered by TMDB for movies and TV, and IGDB for games.

Sections include:

- trending
- popular
- top rated
- upcoming
- now playing
- airing today
- recently released games
- most anticipated games
- genre browsing

Users can also perform global search.

Game metadata should be fetched through the backend using IGDB and Twitch OAuth credentials, never directly from the browser.

---

## Recommendations

Recommendations are based on:

- user watch history
- favorite genres
- TMDB similarity
- IGDB genre, platform, and franchise similarity
- internal recommendation scoring

Recommendation results may be cached for performance.

---

## Download Manager

Users can add downloads through:

- magnet links
- torrent files
- direct download links
- HTTP URLs

The download manager handles:

- job queue
- progress
- download speed
- estimated completion
- status reporting

Download states include:

- queued
- downloading
- stalled
- completed
- failed

Downloaded files are stored on mounted storage volumes.

---

## Media Library

Downloaded or imported files are scanned and linked to TMDB metadata.

Users can:

- browse their media library
- stream media inside the platform
- access files via mounted storage
- view metadata and artwork

A background **media scanner service** automatically matches files to movies or shows.

---

## Built-in Player

The application includes a browser-based player.

Capabilities:

- playback resume
- subtitle support
- episode autoplay
- theater mode

Playback progress updates during viewing.

---

## Release Calendar

Calendar showing upcoming releases.

Includes:

- movie premieres
- new TV episodes
- next season releases
- game launches
- expansion and DLC release windows

Users can filter by:

- watchlist
- movie vs show
- game platform
- genre

---

## Dashboard

The dashboard is the main hub.

Widgets include:

- continue watching
- watch later
- game backlog
- recently played
- active downloads
- recommendations
- upcoming releases
- trending media
- recently watched

---

# Technology Stack

## Backend

- Golang
- Gin web framework
- PostgreSQL
- sqlc
- goose migrations
- zap structured logging
- DragonflyDB caching

Backend responsibilities:

- API
- authentication
- metadata management
- downloads orchestration
- background jobs
- TMDB integration
- IGDB integration

---

## Frontend

- SolidJS
- TypeScript
- Vite
- TailwindCSS
- shadcn-style component system
- Ark UI primitives

The frontend should behave like a **modern SaaS dashboard**.

---

## Infrastructure

- Docker
- Docker Compose
- Nginx reverse proxy

The system must be easy to deploy on a home server or VPS.

---

# UI Design

Design inspiration:

https://haptics.lochie.me/

The UI should feel:

- minimal
- spacious
- elegant
- modern
- smooth

Subtle motion and polished transitions should be used.

---

# Color Palette

Primary accent


#00b7ff


Secondary accent


#5800a9


Base background


#111111


The color scheme should be used subtly to maintain a premium appearance.

---

# Themes

The platform must support:

- dark mode
- light mode
- system preference detection
- persistent theme storage

Dark mode should be the primary visual style.

---

# Application Layout

Main application routes:


/app/dashboard
/app/discover
/app/movies
/app/shows
/app/watch-later
/app/watched
/app/downloads
/app/calendar
/app/recommendations
/app/library
/app/collections
/app/settings
/app/admin


The layout consists of:

- sidebar navigation
- top bar with search and profile
- dashboard content area

---

# Backend Architecture

Directory layout example:


cmd/
internal/
api/
services/
repositories/
domain/
middleware/
workers/
integrations/
downloader/
scanner/
pkg/
migrations/
sql/


The architecture separates:

- transport layer
- business logic
- data access
- integrations

---

# Background Workers

Background services handle tasks such as:

- TMDB metadata synchronization
- recommendation generation
- download monitoring
- media scanning
- scheduled cleanup

---

# Downloader Service

Downloader responsibilities include:

- torrent downloads
- HTTP downloads
- queue management
- status reporting
- file path tracking

The downloader should be modular so engines can be replaced later.

---

# Media Scanner

The scanner links downloaded files to metadata.

Process:

1. scan library folders
2. parse file names
3. query TMDB
4. match metadata
5. create library entries

---

# Database

PostgreSQL acts as the primary data store.

Main tables include:


users
sessions
movies
tv_shows
seasons
episodes
genres
user_watch_status
user_watchlist
user_progress
user_ratings
collections
collection_items
downloads
download_files
library_items


Indexes and foreign keys must be properly defined.

---

# Caching Strategy

DragonflyDB is used for:

- session storage
- API caching
- TMDB response cache
- continue watching cache
- search suggestions
- recommendation snapshots

PostgreSQL remains the source of truth.

---

# API

All endpoints follow versioned REST design.

Example routes:


/api/v1/auth
/api/v1/movies
/api/v1/shows
/api/v1/search
/api/v1/watchlist
/api/v1/progress
/api/v1/downloads
/api/v1/library
/api/v1/recommendations


Endpoints must support pagination and filtering.

---

# Authentication

Authentication system features:

- email and password login
- secure password hashing
- refresh token or session strategy
- role-based access

Roles include:


user
admin


---

# Security

Security measures include:

- input validation
- rate limiting
- secure cookie handling
- CSRF protection
- environment-based configuration
- safe file handling

---

# Deployment

The application runs in Docker containers.

Services include:


seen-backend
seen-frontend
postgres
dragonfly
nginx
downloader


The system should run with a single docker compose setup.

---

# Long-Term Vision

/seen/ aims to become a complete self-hosted media platform combining the strengths of:

- Plex
- Letterboxd
- Netflix UI
- personal media tracking

All while remaining open, customizable, and fully controlled by the user.


# UI Component Reference

- https://pro.alignui.com/blocks

Use this as visual reference for selected layout and component patterns.
The final result should stay clean, minimal, and modern SaaS style while keeping
the /seen/ brand direction.

---

# Implementation Snapshot (March 10, 2026)

This section reflects the repository state on **March 10, 2026**.

## Frontend status

Implemented:

- app shell (sidebar + top bar)
- route guards and auth session bootstrap
- dashboard page with live widgets contract
- discover page with search, filters, pagination behavior
- watch later page with authenticated add/remove flow
- continue watching widget actions wired to persisted progress updates
- dark/light/system theme persistence
- typed service layer with mock/live API switch

Scaffolded but still placeholder pages:

- /app/movies
- /app/shows
- /app/watched
- /app/downloads
- /app/calendar
- /app/recommendations
- /app/library
- /app/collections
- /app/settings
- /app/admin

## Backend status

Implemented:

- Gin server with request id, access logging, and recovery middleware
- health endpoints and readiness checks
- auth endpoints: register, login, refresh, me
- JWT access token + persisted refresh sessions
- live catalog endpoints: dashboard, continue watching, discover, search
- authenticated watch later endpoints: list, add, remove
- authenticated progress update endpoint with continue watching refresh
- persistent catalog schema for media, genres, and discover sections
- seeded catalog dataset for discover/search/dashboard rails
- PostgreSQL catalog repository wired into catalog service
- user_watch_later persistence with per-user ordering
- user_progress persistence with ordered continue watching reads
- worker manager with downloader and scanner worker scaffolding

Not implemented yet:

- write endpoints for watched history, ratings, favorites, and downloads
- real TMDB synchronization jobs
- production downloader engine integration
- scanner-to-library persistence flow

## Database status

Current migration provides:

- users
- sessions
- media_items
- genres
- media_genres
- discover_sections
- discover_section_items
- user_watch_later
- user_progress

Remaining domain tables are planned below in the Data Model Expansion Plan.

---

# Current API Surface (v1)

## Live endpoints

- GET /api/v1/health/live
- GET /api/v1/health/ready
- POST /api/v1/auth/register
- POST /api/v1/auth/login
- POST /api/v1/auth/refresh
- GET /api/v1/auth/me
- GET /api/v1/dashboard
- GET /api/v1/progress/continue-watching
- GET /api/v1/discover
- GET /api/v1/search
- GET /api/v1/watch-later
- POST /api/v1/watch-later
- DELETE /api/v1/watch-later/:mediaId
- POST /api/v1/progress

## Placeholder endpoints

- GET /api/v1/movies
- GET /api/v1/shows
- GET /api/v1/watched
- GET /api/v1/watchlist
- GET /api/v1/progress
- GET /api/v1/downloads
- GET /api/v1/calendar
- GET /api/v1/library
- GET /api/v1/collections
- GET /api/v1/settings
- GET /api/v1/admin
- GET /api/v1/recommendations

---

# Phase Roadmap

## Phase 2A - Persistent catalog and metadata foundation

Goals:

- move catalog read models from in-memory seed data to PostgreSQL
- keep the current frontend API contracts stable

Deliverables:

- tables for media, genres, and linking tables
- repository + sqlc queries for catalog reads
- TMDB sync job for trending/popular/upcoming datasets
- cache keys and TTL policy for discovery and dashboard aggregates

Exit criteria:

- /dashboard, /discover, and /search responses come from persisted data
- API response shape remains backward compatible with current frontend types

## Phase 2B - User tracking and watch flows

Goals:

- enable user-specific state changes from UI interactions

Deliverables:

- watch later CRUD endpoints
- watched history writes
- per-episode progress updates
- rating and favorites persistence

Exit criteria:

- users can add/remove watch later items
- users can mark watched and resume playback positions
- dashboard widgets reflect real per-user data

## Phase 2C - Download manager (real jobs)

Goals:

- replace placeholder download data with executable jobs

Deliverables:

- create/list/cancel download endpoints
- queue persistence + job state transitions
- worker integration with selected download engine
- progress events polling contract for UI

Exit criteria:

- a submitted download moves through queued/downloading/completed or failed
- dashboard active downloads widget is fully live

## Phase 3A - Library and scanner

Goals:

- connect downloaded/imported files into a browsable library

Deliverables:

- scanner pipeline: file discovery, parsing, metadata matching, persistence
- library browse endpoints with filters
- artwork and metadata hydration strategy

Exit criteria:

- new media files appear in /library with matched metadata
- unmatched files are visible in a review queue

## Phase 3B - Recommendations and calendar

Goals:

- move recommendation and calendar from static placeholders to generated data

Deliverables:

- recommendation scoring job
- release calendar endpoint with watchlist filters
- cache snapshot pipeline for fast dashboard reads

Exit criteria:

- recommendation list and calendar are generated per user profile

---

# Data Model Expansion Plan

Already present (migrations 000001 to 000004):

- users
- sessions
- media_items
- genres
- media_genres
- discover_sections
- discover_section_items
- user_watch_later
- user_progress

Planned next:

- media_external_ids
- show_seasons
- show_episodes
- user_watched
- user_ratings
- user_favorites
- collections
- collection_items
- download_jobs
- download_files
- download_events
- library_items
- library_streams

Index priorities:

- (user_id, updated_at) on user activity tables
- (media_type, release_date) on media browsing tables
- (status, created_at) on download_jobs
- GIN/trigram search index for title/overview search

---

# Quality Gates

Before merging major slices:

1. backend unit tests pass (`go test ./...`)
2. frontend unit tests pass (`npm run test:unit`)
3. frontend smoke e2e passes (`npm run test:e2e`)
4. docker compose stack boots and health endpoints are green
5. no placeholder endpoint is silently reused for production behavior

---

# Immediate Next Build Order

1. Start TMDB sync worker to refresh discover sections in PostgreSQL.
2. Add `download_jobs` schema + worker state machine for Phase 2C.
3. Add cached dashboard aggregate reads in DragonflyDB.
4. Replace static dashboard recommendations with persisted recommendation snapshots.
5. Add watched history write endpoints and UI hooks.

---

# Phase 2C Delivery Blueprint (Downloads)

## Scope

Turn `/api/v1/downloads` from placeholder into a real per-user job system with queue state transitions, progress updates, cancellation, and dashboard integration.

## Schema draft

`download_jobs`

- id (uuid, primary key)
- user_id (uuid, not null, fk users.id)
- source_type (text, check in `magnet|torrent|direct|http`)
- source (text, not null)
- title (text, not null default '')
- status (text, check in `queued|preparing|downloading|stalled|retrying|completed|failed|cancelled`)
- queue_position (integer, nullable)
- progress_percent (integer, not null default 0, check 0-100)
- bytes_total (bigint, not null default 0)
- bytes_downloaded (bigint, not null default 0)
- download_speed_mbps (double precision, not null default 0)
- eta_seconds (integer, nullable)
- engine_job_id (text, nullable, unique)
- error_message (text, not null default '')
- retry_count (smallint, not null default 0)
- created_at (timestamptz, not null default now())
- updated_at (timestamptz, not null default now())
- started_at (timestamptz, nullable)
- completed_at (timestamptz, nullable)
- cancelled_at (timestamptz, nullable)

`download_events`

- id (bigserial, primary key)
- job_id (uuid, not null, fk download_jobs.id on delete cascade)
- status (text, not null)
- message (text, not null default '')
- progress_percent (integer, not null default 0)
- payload (jsonb, not null default '{}'::jsonb)
- created_at (timestamptz, not null default now())

Indexes:

- `(user_id, created_at desc)` on `download_jobs`
- `(user_id, status, updated_at desc)` on `download_jobs`
- `(status, created_at asc)` partial where status in (`queued`, `retrying`)
- `(job_id, created_at desc)` on `download_events`

## State machine

Transitions:

- queued -> preparing
- preparing -> downloading
- downloading -> stalled
- stalled -> retrying
- retrying -> preparing
- downloading -> completed
- downloading -> failed
- queued|preparing|downloading|stalled|retrying -> cancelled

Rules:

- progress is monotonic for active states
- completed implies `progress_percent = 100`
- cancelled jobs keep historical events and are excluded from active dashboard count
- retries capped (`retry_count <= 3`) before terminal `failed`

## API contract draft

`POST /api/v1/downloads`

- request body:
  - `sourceType`: `magnet|torrent|direct|http`
  - `source`: non-empty URL/magnet
  - `title`: optional UI label
- response:
  - `201 Created`
  - `{ "id": "...", "status": "queued", ... }`

`GET /api/v1/downloads`

- query params:
  - `status` optional
  - `limit` default 20
  - `cursor` optional for pagination
- response:
  - ordered by newest activity
  - includes progress and timing fields

`DELETE /api/v1/downloads/:id`

- semantics:
  - soft cancel if job is active
  - no-op if already terminal
- response:
  - `200 OK` with updated job payload

`GET /api/v1/downloads/:id/events`

- query params:
  - `after` optional RFC3339 timestamp
  - `limit` default 100
- response:
  - ordered events for timeline and debugging

## Worker split

`downloader-dispatcher`:

- pulls `queued/retrying` jobs
- reserves available concurrency slots
- sends Add call to selected engine

`downloader-monitor`:

- polls engine status
- writes progress updates + events
- finalizes terminal states

Runtime defaults:

- `DOWNLOAD_MAX_ACTIVE=3`
- `DOWNLOAD_POLL_INTERVAL=3s`
- `DOWNLOAD_RETRY_BACKOFF=15s`

## Exit criteria for Phase 2C

- dashboard `activeDownloads` comes from persisted jobs
- creating a job from API moves it through real states
- cancellation works for both queued and active jobs
- smoke e2e covers submit -> progress -> complete/cancel path

---

# Phase 3A Delivery Blueprint (Library + Scanner)

## Scope

Build a durable library index for local media files and expose browse + matching workflows.

## Schema draft

`library_items`

- id (uuid, primary key)
- media_id (bigint, nullable, fk media_items.id)
- source_job_id (uuid, nullable, fk download_jobs.id)
- absolute_path (text, not null, unique)
- file_name (text, not null)
- file_size_bytes (bigint, not null default 0)
- container_format (text, not null default '')
- video_codec (text, not null default '')
- audio_codec (text, not null default '')
- duration_seconds (integer, not null default 0)
- resolution_label (text, not null default '')
- match_state (text, check in `matched|unmatched|ignored`)
- match_confidence (double precision, not null default 0)
- discovered_at (timestamptz, not null default now())
- scanned_at (timestamptz, nullable)
- created_at (timestamptz, not null default now())
- updated_at (timestamptz, not null default now())

`library_streams`

- id (uuid, primary key)
- library_item_id (uuid, not null, fk library_items.id on delete cascade)
- stream_type (text, check in `video|audio|subtitle`)
- codec (text, not null default '')
- language (text, not null default '')
- channels (smallint, not null default 0)
- bitrate_kbps (integer, not null default 0)
- is_default (boolean, not null default false)

Indexes:

- `(match_state, updated_at desc)` on `library_items`
- `(media_id, updated_at desc)` on `library_items`
- trigram index on `file_name` for unmatched review search

## Scanner workflow

1. discover files under configured library roots
2. normalize path and deduplicate by `absolute_path`
3. parse title/season/episode hints from filename
4. call TMDB search/match pipeline
5. upsert `library_items` + `library_streams`
6. mark low-confidence matches as `unmatched`

## API contract draft

`GET /api/v1/library`

- filters:
  - `matchState`
  - `mediaType`
  - `query`
  - `page`, `pageSize`
- returns enriched cards for UI browse grid

`POST /api/v1/library/rescan`

- optional body:
  - `paths`: array of roots
- returns:
  - scan job id + accepted count

`GET /api/v1/library/unmatched`

- paginated unmatched queue with confidence metadata

`POST /api/v1/library/:id/match`

- request body:
  - `mediaId`
  - `force` optional bool
- manually links file to a media entry

## Exit criteria for Phase 3A

- new files are indexed within one scan cycle
- unmatched queue is visible and manually resolvable
- `/api/v1/library` is no longer placeholder
- scanner worker persists state changes, not heartbeats only

---

# Cache Key Contract (DragonflyDB)

Use explicit versioned keys so invalidation is predictable:

- `seen:v1:discover:{query_hash}` (TTL: 10m)
- `seen:v1:dashboard:{user_id}` (TTL: 2m)
- `seen:v1:continue-watching:{user_id}` (TTL: 2m)
- `seen:v1:recommendations:{user_id}` (TTL: 30m)
- `seen:v1:calendar:{user_id}:{month}` (TTL: 6h)

Invalidation triggers:

- watch-later change -> invalidate `dashboard` and `recommendations`
- progress update -> invalidate `continue-watching` and `dashboard`
- TMDB sync refresh -> invalidate discover keys
- recommendation snapshot refresh -> invalidate recommendation key

---

# File-Level Build Plan

Backend additions:

- `backend/migrations/000005_init_downloads.up.sql`
- `backend/migrations/000005_init_downloads.down.sql`
- `backend/migrations/000006_init_library.up.sql`
- `backend/migrations/000006_init_library.down.sql`
- `backend/sql/queries/downloads.sql`
- `backend/sql/queries/library.sql`
- `backend/internal/repositories/postgres/download_repository.go`
- `backend/internal/repositories/postgres/library_repository.go`
- `backend/internal/services/download/service.go`
- `backend/internal/services/library/service.go`
- `backend/internal/api/handlers/download_handler.go`
- `backend/internal/api/handlers/library_handler.go`

Frontend additions:

- `frontend/src/services/download-service.ts`
- `frontend/src/services/library-service.ts`
- `frontend/src/pages/downloads-page.tsx`
- `frontend/src/pages/library-page.tsx`
- `frontend/src/pages/calendar-page.tsx`
- `frontend/src/pages/recommendations-page.tsx`

Tests to add:

- backend unit tests for download state transitions
- backend repository tests for scanner/library filtering
- frontend unit tests for downloads and library stores/services
- e2e flow covering download create/cancel and library browse

---

# Updated Build Priority (Next 2 Sprints)

Sprint A:

1. Implement download schema + SQL queries + repository.
2. Implement download service state machine + worker loops.
3. Ship `/api/v1/downloads` endpoints and replace dashboard download mock.
4. Add tests and smoke e2e for download lifecycle.

Sprint B:

1. Implement library schema + scanner persistence pipeline.
2. Ship `/api/v1/library` list/rescan/unmatched/match endpoints.
3. Replace placeholder library page with real browse + unmatched queue.
4. Add TMDB sync job and cache invalidation wiring for discover/dashboard.