Developer Docs

Global Catalog

The catalog contains normalized records for all known creators, feeds, content items, and content sources. Catalog data is source-agnostic at the API level — source-specific details live inside source adapters and metadata fields.

User-Owned Overlays

Overlay records are private to each user and reference catalog entities. Every overlay table has a userId column with cascade delete and is scoped by authenticated userId at the API boundary.

oRPC Router Structure

The API uses oRPC with two procedure types:

• publicProcedure — Accessible without authentication. Used for catalog browsing, session reading, health check, and migrated-password setup.
• protectedProcedure — Requires an authenticated session with an active account. A middleware validates the session and injects the user context. Used for all overlay mutations, ingestion, refresh, and migration.

The router is organized into namespaces:

appRouter = {
  healthCheck,                // Public
  session: { current },       // Public (returns null if unauthenticated)
  auth: { setupMigratedPassword },
  catalog: {
    creators,                 // Public - list creators with search/filter
    feeds,                    // Public - list feeds
    contentItems,             // Public - list content items
    contentDetail,            // Public - single content item with sources
  },
  refresh: {
    status,                   // Public - refresh run status
    startAll,                 // Protected - start background refresh
    runAll,                   // Protected - run refresh synchronously
    runCreator,               // Protected - refresh one creator
    runFeed,                  // Protected - refresh one feed
  },
  ingestion: {
    addSource,                // Protected - add single source URL
    batchAddSources,          // Protected - add multiple source URLs
  },
  overlays: {
    subscriptions,            // Protected - list user subscriptions
    subscribeToCreator,       // Protected - subscribe
    unsubscribeFromCreator,   // Protected - unsubscribe
    contentStatuses,          // Protected - list all user statuses
    markContentOpened,        // Protected - mark opened
    markContentPlayed,        // Protected - mark played
    toggleContentOpened,      // Protected - toggle opened
    toggleContentPlayed,      // Protected - toggle played
    toggleContentFavorite,    // Protected - toggle favorite
    favoriteContentItems,     // Protected - list favorited items
    contentHistory,           // Protected - opened/played history
    playlists,                // Protected - list user playlists
    createPlaylist,           // Protected
    updatePlaylist,           // Protected
    deletePlaylist,           // Protected
    playlistItems,            // Protected - list items in playlist
    addPlaylistItem,          // Protected
    removePlaylistItem,       // Protected
    reorderPlaylistItems,     // Protected
    settings,                 // Protected - list user settings
    saveSetting,              // Protected
    deleteSetting,            // Protected
  },
  migration: {
    runImport,                // Protected - import from Strapi export JSON
  },
}

Context and Authentication

Each request creates a context through createContext. The context contains:

• db — The Drizzle database instance for querying.
• session — The authenticated session and user, or null for anonymous requests. Includes accountState to distinguish active users from migrated users pending password setup.
• sourceRegistry — The source adapter registry with YouTube, Odysee, and PeerTube adapters registered.

The protected procedure middleware rejects requests with no session (UNAUTHORIZED) or with a non-active accountState (FORBIDDEN).

Adding a New API Procedure

1. Define the input schema. Use Zod schemas at the top of the router file. Follow the naming convention of descriptive input names (e.g., playlistNameInput).
2. Choose the procedure. Use publicProcedure for anonymous catalog reads or protectedProcedure for authenticated mutations and user-scoped data.
3. Implement the handler. Use repository functions from repositories/catalog or repositories/overlays. Keep the handler thin — delegate to services or repositories.
4. Validate existence. For operations that reference catalog entities, validate the entity exists before proceeding. Throw ORPCError("NOT_FOUND") when missing.
5. Scope by userId. All user-owned data must pass context.session.user.id to repository functions. Never trust client-supplied user IDs.
6. Write tests. Add test coverage through the API procedure (public interface), not private internals.

Source Adapter Interface

interface SourceAdapter<TSourceType extends SourceType = SourceType> {
  readonly sourceType: TSourceType;
  detect(input: string): SourceDetectionResult;
  resolveInput(input: DetectedSourceInput): Promise<SourceAdapterResult<ResolvedSourceInput>>;
  normalizeCatalogPayload(input: ResolvedSourceInput, payload: string): SourceAdapterResult<NormalizedCatalogPayload>;
  fetchCatalog(input: ResolvedSourceInput): Promise<SourceAdapterResult<NormalizedCatalogPayload>>;
}

• detect — Determines if a URL is supported by this adapter and classifies the input kind (feed URL, creator URL, content URL, unknown). Returns a DetectedSourceInput or an error.
• resolveInput — Resolves a detected input into creator/feed identity with a canonical URL and optional title.
• normalizeCatalogPayload — Parses raw feed or API response data (XML, JSON) into the normalized catalog structure: creator, feeds, and content items with sources.
• fetchCatalog — Fetches data from the remote source and normalizes it in one step. Combines HTTP fetch and normalization.

Source Adapter Registry

The SourceAdapterRegistry holds all registered adapters. On source detection, it iterates adapters in registration order and returns the first match. The registry is created in the context module with the three built-in adapters:

const defaultSourceRegistry = createSourceAdapterRegistry([
  youtubeAdapter,
  odyseeAdapter,
  peertubeAdapter,
]);

Adding a New Source

To add support for a new video platform:

1. Add the source type to the union. Update SourceType in packages/api/src/domain/catalog.ts and the corresponding sourceTypeValues in packages/db/src/schema/catalog.ts.
2. Create the adapter file. Add a new file in packages/api/src/sources/. Implement the full SourceAdapter interface with detect, resolveInput, normalizeCatalogPayload, and fetchCatalog.
3. Write fixture-backed tests. Test detection against real URL forms, normalization against saved response fixtures, and error handling for malformed input. Do not depend on live network calls.
4. Register the adapter. Export the adapter from packages/api/src/sources/index.ts and add it to the registry in packages/api/src/context.ts.
5. Update the router input schema. Add the new source type to sourceTypeInput in the router if you want filter support.

Schema Structure

Drizzle schema is in packages/db/src/schema/ split into three files:

• auth.ts — User, session, account, and verification tables managed by better-auth.
• catalog.ts — Global catalog tables (creator, feed, contentItem, contentSource, feedContent, refreshRun, refreshFeedResult) with Drizzle relations.
• overlays.ts — User-owned overlay tables (subscription, contentStatus, playlist, playlistItem, userSetting, migrationRun, migrationMapping) with cross-references to catalog and auth tables.

All tables use text primary keys (UUID), integer timestamps in millisecond mode, and appropriate indexes for query patterns. Unique indexes enforce source identity deduplication and user-data constraints.

Migration Workflow

bun run db:generate   # Generate SQL migration files from schema changes
bun run db:migrate    # Apply pending migrations to the database
bun run db:push       # Push schema directly (dev only, no migration files)
bun run db:studio     # Open Drizzle Studio to inspect data
bun run db:local      # Start local libSQL server on port 5000

Adding a New Table

1. Choose the right file. Auth-related tables go in auth.ts, catalog tables in catalog.ts, user overlay tables in overlays.ts.
2. Define the table. Use sqliteTable with text IDs, integer timestamps (mode: timestamp_ms), and the shared currentTimestampMs helper.
3. Add indexes. Include a unique index for natural identity columns and regular indexes for foreign keys and common query patterns.
4. Define relations. Add a Drizzle relations definition for the table if it has foreign keys to other tables.
5. Export from index. The file re-exports through schema/index.ts.
6. Generate and apply migration. Run db:generate to produce the SQL migration, then db:migrate to apply it.

Ingestion Pipeline

The ingestion service handles adding new sources and creating catalog records. The flow is:

1. Detect the source type from the input URL via the registry.
2. Resolve the input to a canonical creator/feed identity.
3. Fetch the remote catalog data through the adapter.
4. Normalize into creator, feed, content items, and content sources.
5. Persist to the database with upsert semantics (deduplicate by source identity).
6. Create a subscription linking the user to the creator.

Batch ingestion processes each URL independently and reports per-item success or failure without aborting the entire batch.

Refresh Service

The refresh service re-fetches feed data and updates the catalog. Two modes:

• Normal refresh — Selects feeds where nextRefreshAfter has passed or is null. Skips feeds that are not due.
• Force refresh — Selects all feeds regardless of cadence metadata.

Refresh runs produce a refreshRun record and per-feed refreshFeedResult records with counts and error summaries. The startAll procedure returns immediately while the refresh continues in the background.