Catalog & Song Management

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/catalogs/songs/route.ts
• lib/catalog/analyzeFullCatalog.ts
• lib/catalog/getCatalogSongs.ts
• lib/catalog/insertCatalogSongs.ts
• lib/songs/createCatalogSongsHandler.ts
• lib/songs/deleteCatalogSongsHandler.ts
• lib/songs/validateCatalogSongsRequest.ts
• types/database.types.ts
• lib/catalog/formatCatalogSongsAsCSV.ts
• lib/catalog/getCatalogDataAsCSV.ts

The Catalog & Song Management system is a core module of the Recoup API designed to organize, retrieve, and analyze music assets. It provides a structured way to link songs (identified by ISRCs) to specific catalogs and managing the associated metadata such as artist information, albums, and internal notes. This system serves as the foundation for complex tasks like AI-driven catalog analysis, playlist recommendations, and sync opportunity discovery.

Sources: lib/catalog/analyzeFullCatalog.ts, lib/songs/createCatalogSongsHandler.ts:10-20

Data Architecture & Schema

The system relies on a relational structure within Supabase (PostgreSQL) to maintain the integrity of music catalogs. The primary entities are Catalogs and Songs, which are joined through a many-to-many relationship table.

Entity Relationship Model

The following diagram illustrates the relationships between accounts (artists), catalogs, and songs.

Diagram shows the relational structure where songs are primary assets linked to artists and grouped into catalogs.
Sources: types/database.types.ts:518-540, types/database.types.ts:1210-1250

Core Tables Summary

Table	Primary Key	Description
catalogs	id (UUID)	Represents a collection of music assets.
songs	isrc (String)	Stores unique song data using the International Standard Recording Code.
catalog_songs	id (UUID)	A join table linking songs to catalogs using catalog_id and song_isrc.
song_artists	id (UUID)	Links songs to accounts/artists who performed them.

Sources: types/database.types.ts:544-570, types/database.types.ts:1240-1270

API Implementation

Catalog management follows a strict handler-route pattern where API routes delegate logic to specialized handlers and validators.

Validation Logic

All incoming requests for creating or deleting catalog-song relationships are validated using Zod schemas to ensure data integrity.

const catalogSongInputSchema = z.object({
  catalog_id: z.string().min(1, "catalog_id is required"),
  isrc: z.string().min(1, "isrc is required"),
  name: z.string().optional(),
  album: z.string().optional(),
  notes: z.string().optional(),
  artists: z.array(z.string()).optional(),
});

Sources: lib/songs/validateCatalogSongsRequest.ts:5-12

Creation Flow

When songs are added to a catalog, the system first ensures the song records exist via processSongsInput before creating the relationship in the catalog_songs table.

Catalog Retrieval & Analysis

The system supports both standard paginated retrieval and advanced AI-driven analysis of full catalogs.

Paginated Retrieval

Standard queries use the getCatalogSongs utility which supports filtering by artist name and handles pagination parameters (limit, page).
Sources: lib/catalog/getCatalogSongs.ts:28-40

Full Catalog Analysis

For comprehensive tasks, analyzeFullCatalog implements a parallel batching strategy to bypass single-page limits.

1. Parallel Fetching: It fetches the first page to determine the total count, then initiates parallel requests for all remaining pages using a BATCH_SIZE of 100.
2. Refinement: Once all songs are collected, they are passed to a refineResults function which uses AI to filter songs based on specific criteria.

Sources: lib/catalog/analyzeFullCatalog.ts:24-45

CSV Export for AI Scoring

To support AI evaluation (e.g., checking if recommended songs exist in a catalog), the system provides utilities to format catalog data as CSV strings.

/** 
 * Example output format: 
 * ISRC, "Track Name", "Album Name", "Artist Name 1, Artist Name 2"
 */
export function formatCatalogSongsAsCSV(songs: CatalogSong[]): string {
  const csvLines = songs.map(song => {
    const artistNames = song.artists.map(artist => artist.name).join(", ");
    return `${song.isrc},"${song.name}","${song.album}","${artistNames}"`;
  });
  return csvLines.join("\n");
}

Sources: lib/catalog/formatCatalogSongsAsCSV.ts:6-14, lib/catalog/getCatalogDataAsCSV.ts:10-25

Endpoint Specification

Method	Endpoint	Description
GET	/api/catalogs/songs	Retrieves a paginated list of songs for a given catalog_id.
POST	/api/catalogs/songs	Adds multiple songs to one or more catalogs.
DELETE	/api/catalogs/songs	Removes specific song-catalog relationships.

Sources: app/api/catalogs/songs/route.ts, lib/songs/deleteCatalogSongsHandler.ts:16-25

Conclusion

The Catalog & Song Management system provides a robust architecture for handling large-scale music metadata. By decoupling song storage from catalog organization and artist relationships, it allows for flexible asset management. The inclusion of parallel batching and CSV formatting utilities makes it uniquely suited for modern AI-driven analysis workflows required in the music industry.