Catalog Metadata

The supporting metadata that classifies and describes the catalog: genres, moods, labels, contributor roles, image variants and the GeoNames-backed places dataset. These models are shared across Albums, Artists and Tracks.

1 Genre

A musical genre. Genres form a two-level hierarchy via the ParentSlug self-link, and attach to both Tracks (track_genres) and Artists (artist_genres) as many-to-many relations.

public class Genre : BaseModel
{
    public required string Slug { get; set; }
    public string? ParentSlug { get; set; }
    public bool IsActive { get; set; } = true;
    public int DisplayOrder { get; set; }
}

Table: genres. Slug is uniquely indexed.

2 Mood

A curated, editorial mood tag — distinct from the continuous mood scores computed by the audio enricher (see TrackAudioFeatures). Moods attach to Tracks (track_moods) and Albums (album_moods).

public class Mood : BaseModel
{
    public required string Slug { get; set; }
    public bool IsActive { get; set; } = true;
    public int DisplayOrder { get; set; }
}

Table: moods. Slug is uniquely indexed. Unlike Genre, Mood has no hierarchy.

3 Label

A record label. An Album may reference a Label via Album.LabelId.

LabelType

4 ContributorRole

The shared role catalog used by both TrackContributor and AlbumContributor. Values are grouped by numeric range so a category can be queried arithmetically — Role / 100 yields the category number (e.g. 500 / 100 == 5 → all production roles).

Performance · 300+

Writing · 400+

Production · 500+

Engineering · 600+

Business · 700+

5 Images

Album and Artist artwork is stored as a set of pre-resized variants. Both AlbumImage and ArtistImage implement the shared IImageVariantRecord interface, so the same rendering and source-set logic works for either.

public interface IImageVariantRecord
{
    ImageVariant Variant { get; }
    ImageSize Size { get; }
    string ObjectKey { get; }
    bool IsPrimary { get; }
}

ImageVariant

The crop/shape of an image variant.

ImageSize

The resolution tier of an image variant.

6 Places & Geography

The places dataset provides structured geography for artist origin (Artist.OriginStateId / OriginCityId). It is backed by GeoNames: the primary keys are GeoNames geonameId values, stable across dataset refreshes. These three models do not inherit BaseModel — they use a long primary key.

PlaceState

A state / province / region — backed by GeoNames admin1 entries (e.g. BR.27 = São Paulo, US.CA = California).

PlaceCity

A city — backed by GeoNames cities1000 entries (population ≥ 1000).

PlaceTranslation

A localized name for a place (state or city). Because states and cities share the same GeoNames geonameId space, PlaceId references either places_states.id or places_cities.id — there is no hard FK.