Skip to content

Technical Overview

Tuvima Library is a .NET 10 local-first media system. The product name is Tuvima Library; many projects and namespaces still use MediaEngine.*.

Runtime Apps

App Project Role
Engine src/MediaEngine.Api Composition root, API, ingestion, storage wiring, provider integration, AI services, background jobs, health checks, and SignalR
Dashboard src/MediaEngine.Web Blazor Server UI that talks to the Engine over HTTP and SignalR
Standalone ingestion worker src/MediaEngine.Ingestion Worker host for ingestion components; not the primary runtime path today

Normal local development starts the Engine first, then the Dashboard.

Main Data Flow

Library folders
  -> File watcher / import scan
  -> Settle, lock check, fingerprint
  -> File processor
  -> Identity/scoring
  -> Stage 1 retail provider stage
  -> Stage 2 Wikidata bridge stage
  -> Quick Hydration
  -> Stage 3 universe enrichment
  -> SQLite, .data/assets, organization, write-back
  -> Display/detail/search APIs
  -> Dashboard

The Engine owns business rules and persistence. Managed artwork and headshots are stored under .data/assets/... and referenced from SQLite. The Dashboard consumes contracts, typed HTTP clients, and SignalR events. Razor components must not contain direct SQL.

Repository Shape

Project Responsibility
MediaEngine.Domain Core aggregates, entities, enums, constants, and interfaces
MediaEngine.Contracts DTOs that cross the Engine/Dashboard boundary
MediaEngine.Application Read-model DTOs and cross-layer service contracts
MediaEngine.Storage SQLite repositories, schema bootstrap, migrations, configuration loading
MediaEngine.Intelligence Priority Cascade, scoring, fuzzy matching, identity matching, collection arbitration
MediaEngine.Processors File processors and media extraction helpers
MediaEngine.Providers Metadata providers, hydration pipeline, reconciliation, image/person/universe enrichment
MediaEngine.AI Local model lifecycle, hardware checks, AI features, Llama/Whisper inference
MediaEngine.Identity Profiles, roles, and user identity concepts
MediaEngine.Plugins Plugin contracts and plugin metadata
MediaEngine.Api API endpoints, DI, hosted services, SignalR, Swagger
MediaEngine.Web Dashboard UI, typed clients, route helpers, playback/editing/theming services

Current User Surfaces

  • / - Home/discovery
  • /read - books and comics lane
  • /watch - movies and TV lane
  • /listen - music and audiobooks lane
  • /collections and /collection/{id} - broader rollups and managed collections
  • /search - cross-library search
  • /details/{entityType}/{id} plus media-specific detail routes - item and group detail
  • /settings and /settings/{section} - user/admin settings
  • /settings/review - Review Queue
  • /settings/libraries - structured library configuration and profile Personal Space status
  • /settings/ingestion - ingestion operations dashboard
  • /settings/developer/options - temporary development wipe, reingest, and validation harness

Normal media corrections launch MediaEditorLauncherService and SharedMediaEditorShell from the surface where the issue appears. Review Queue uses the same editor in review mode.

Extension Points

  • Add supported file formats through processors in MediaEngine.Processors.
  • Add REST/JSON provider behavior through config/providers/*.json where config-driven adapters are sufficient.
  • Add deeper provider logic in MediaEngine.Providers when a provider cannot be expressed as config.
  • Add Dashboard Engine calls through IEngineApiClient and EngineApiClient.
  • Add settings destinations through SettingsNav and Components/Settings.
  • Add plugin capabilities through MediaEngine.Plugins and plugin projects.

Verification Workflow

Minimum verification before finalizing code changes:

dotnet restore MediaEngine.slnx
dotnet build MediaEngine.slnx --no-restore
dotnet test MediaEngine.slnx --no-build
./scripts/docs/build-docs.ps1

Docs-only changes still need ./scripts/docs/build-docs.ps1. Broader repo changes should run the full restore/build/test gate.