1fcc7344cb
One "video" kind meant every video library behaved the same, so a film shelf tried to parse episode numbers and a TV library could not be told apart from it. The kinds are now a declaration rather than a special case. Five video kinds, all owning the same containers and differing only in how their files become items: movies flat tv series/season/episode adult flat hentai series/season/episode video series/season/episode (kept: existing libraries already use it) The scanner dispatches on library.GroupModeFor(lib.Kind) instead of comparing the kind to "video", so a new episodic kind is a registry entry and nothing in the scanner changes. The decision worth recording, because it could have gone the other way: media_items.kind stays STRUCTURAL. Every video library stores 'video' on its rows, not its own kind. media_items.kind answers "is this a playable video", which is what the playback, catalog and Jellyfin paths actually ask, and migration 0013 already committed to that rule when it decided an episode would stay kind='video'. Storing the library kind instead would have meant teaching every query that says kind='video' about five new values - catalog's episode and next-episode reads, Jellyfin's episodes-only filter, the item-type mapping, the web player's routing - and every kind added later would have had to do it again. So the two jobs are split: the ROW kind says what a thing is, the LIBRARY kind says how it is classified, and the library kind is what routes metadata. The enricher now reads the library to choose providers, because a movies library and an adult library hold identical rows and must not query the same catalogue. The adult kinds have no metadata provider. There is no mainstream catalogue for that content - the ecosystem uses StashDB or local NFO files - so they scan and browse and stay unenriched until someone registers one. That is stated in the registry rather than left as a surprise. Verified end-to-end: the same tree under a movies library stays flat, under a tv library builds series/season/episodes, and every row in both is stored as kind='video'. The UI needs no change - it reads /api/v1/media-types, so the new kinds appeared in the picker by themselves. Red-green: dispatching on the literal kind fails the tv and hentai cases; storing the library kind on rows fails the structural-kind assertion. |
||
|---|---|---|
| cmd/vellum | ||
| docs | ||
| internal | ||
| migrations | ||
| scripts | ||
| web | ||
| .dockerignore | ||
| .gitignore | ||
| compose.yml | ||
| DEPLOY.md | ||
| Dockerfile | ||
| entrypoint.sh | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
Vellum
One application, one process, one database for every media type — ebooks, comics, audiobooks, music, photos, games, and video — behind a single account system with real per-user progress and per-library permissions.
A modular monolith. One Go binary, one SQLite file, one web frontend.
The full plan lives in ~/.opencode/plan/vellum.md.
Status
| Phase | Scope | State |
|---|---|---|
| 0 | Repo, config, migrations, health, Docker | done |
| 1 | Users, sessions, library grants | done |
| 2 | Scanner, items, assets | done |
| 2b | FTS5 search | done |
| 3 | EPUB reader + progress | done |
| 4 | CBZ comic reader | done |
| PDF reading (pdf.js) | done | |
| 5 | Job queue, metadata (Open Library, Google Books, MusicBrainz, ComicVine, IGDB, TMDB) | done |
| 6a | Audiobooks + music playback | done |
| 6c | Photos + thumbnails | done |
| 7 | Games: ROM scanning, platforms, cloud saves, EmulatorJS | done |
| UI | Svelte app: home, browse, item pages, readers | done |
| 6b | Music smart playlists | not started |
| — | Video (stays on Jellyfin) | deferred |
What works today: an administrator adds libraries pointing at server folders, scans them, and optionally enriches metadata. Users sign in and read EPUBs and PDFs, read CBZ comics, listen to audiobooks track-by-track, browse photos, and play emulated games in the browser with their own cloud saves — with position saved per account, per file.
Six media types work: ebooks, comics, audiobooks, music, photos, games. Video is the only one not implemented, and it stays on Jellyfin on purpose.
Of the services in the existing stack, this covers Stump, Kavita, Audiobookshelf, Navidrome, and RomM. Only Jellyfin (video) is left.
Quick start
sudo dnf install golang # once; Go is not in the base image here
make build
make run
curl localhost:7788/healthz # {"database":"ok","status":"ok",...}
Run with media roots configured:
VELLUM_MEDIA_DIRS=/mnt/storage/media/ebooks:/mnt/storage/media/comics make run
Configuration
All configuration is environment variables. Every one has a default, so the binary runs with no configuration at all.
| Variable | Default | Meaning |
|---|---|---|
VELLUM_LISTEN |
:7788 |
Bind address |
VELLUM_DATA_DIR |
./data |
SQLite database lives here |
VELLUM_CONFIG_DIR |
./config |
Regenerable cache (covers, pages) |
VELLUM_MEDIA_DIRS |
(none) | Read-only library roots, colon-separated |
VELLUM_ADMIN_USER |
(none) | Creates the first admin, only on an empty database |
VELLUM_ADMIN_PASSWORD |
(none) | Password for that first admin (min 8 chars) |
VELLUM_COOKIE_SECURE |
false |
Set true when serving over TLS |
VELLUM_COMICVINE_API_KEY |
(none) | Enables comic metadata via ComicVine |
VELLUM_DISCOVERY |
on |
Set off to stop advertising over mDNS on the LAN |
VELLUM_IGDB_CLIENT_ID |
(none) | Enables game metadata via IGDB |
VELLUM_IGDB_CLIENT_SECRET |
(none) | IGDB client secret (both required) |
VELLUM_TMDB_API_KEY |
(none) | Enables movie and TV metadata via TMDB |
VELLUM_LOG_LEVEL |
info |
debug, info, warn, error |
VELLUM_LOG_FORMAT |
text |
text or json |
VELLUM_SESSION_TTL |
720h |
Login session lifetime |
VELLUM_SHUTDOWN_GRACE |
15s |
Graceful shutdown timeout |
The first admin is created only when no users exist, so setting these on an established install does nothing. If the database is empty and they are unset, the server logs a warning and refuses to invent a default password.
Layout
cmd/vellum/ main — wiring and lifecycle only, the one place packages meet
internal/
core/ config, logging, database, migrations, timestamps
httpx/ shared JSON helpers
httpapi/ router, middleware, security headers, static SPA serving
auth/ argon2id, sessions, grants, bootstrap
apitoken/ credentials for non-browser clients (Jellyfin, Subsonic)
catalog/ THE data seam: read an item, and check you may
library/ library CRUD and the media-type registry
scanner/ walk the filesystem and reconcile with the database
probe/ ffprobe wrapper — codec facts (optional dependency)
media/ generic item/file/cover/progress endpoints
home/ the five home shelves
search/ FTS5 queries
metadata/ the enrichment job and its matching policy
providers/ Open Library, Google Books, MusicBrainz, ComicVine, IGDB, TMDB
playback/ playback engine selection endpoint
engine/ playback engine registry (html5, mpv, vlc, mdk)
progress/ the polymorphic per-user progress store
stream/ range-capable file serving
jobs/ table-backed job queue
natsort/ natural ordering for pages and tracks
jellyfin/ Jellyfin protocol adapter (+ dto/)
subsonic/ Subsonic protocol adapter (+ dto/)
discovery/ mDNS advertisement on the LAN
arch/ import-rule tests; holds no code
modules/
ebooks/ EPUB parsing and cover extraction
comics/ CBZ page listing and extraction
games/ platforms, IGDB, cloud saves, EmulatorJS
photos/ thumbnail generation
web/ Svelte app; dist/ is embedded via web/embed.go
migrations/ embedded SQL, applied in order at boot
docs/ architecture guide and decision records
Module rule: the core never imports a feature module; modules import the core and mount their own routes, tables, and scanner rules. Adding a media type is a new package plus a migration, never a core edit.
Layer rule: packages are arranged in six layers and a package may never
import from a higher one. This is enforced by tests in internal/arch, not by
convention — see docs/ARCHITECTURE.md.
Schema rule: media items are global; everything user-specific is a join. Nothing may hold per-user state on a media row.
Documentation
- docs/ARCHITECTURE.md — how the pieces fit and why.
- docs/decisions/ — the decisions that were expensive to reverse, with the alternatives that were rejected.
Database
SQLite in WAL mode, opened through modernc.org/sqlite — a pure-Go driver, so
the binary builds with CGO_ENABLED=0 and cross-compiles without a toolchain
per target.
Migrations are embedded and applied in filename order; applied files are
recorded only by number in PRAGMA user_version, so never edit an applied
migration — add a new one.
Back up by copying the database (or its directory); VACUUM INTO 'backup.db'
takes a consistent snapshot while running.
Deploy
make docker # podman build
podman compose up -d # see compose.yml
The container mounts /data (database), /config (cache), and /media
(read-only). On SELinux hosts every bind mount needs :z — compose.yml
already has it.
The application never writes to /media.
Development
make dev # backend + Vite dev server together, with hot reload
make build # builds the frontend, then the Go binary with it embedded
make build-go # Go only, when the frontend is unchanged
make check # gofmt + vet + test
make run # run the server on :7788
cd web && pnpm dev # frontend only; needs the backend running on :7788
make dev is the one to reach for while developing: it builds and starts the
backend, waits for it to answer, then starts Vite. Vite proxies /api to the
backend so the browser sees a single origin and sessions behave exactly as in
production. Ctrl-C stops both.
If you run Vite on its own, the backend must already be running, or every
request fails with ECONNREFUSED on :7788.