Skip to content

🎼 Creators Context — Models & Schema

Last updated: 2025-10-09 (Europe/Paris)

This page documents the core tables that power artist management, team membership, and roster metadata. Use it as a companion to the Creators overview when designing migrations or integrating with other contexts.

🗺️ Database Diagram

%%{init: {'themeVariables': {'fontSize': '15px'}, 'class': {'useMaxWidth': true}}}%%
classDiagram
    direction LR

    class Artist {
        UUID id
        string name
        string slug (unique)
        text bio (nullable)
        UUID organization_id (nullable)
        string country_code (nullable)
        json links (nullable)
        json visuals (nullable)
        timestamps
    }

    class ArtistProfile {
        UUID id
        UUID artist_id
        text about (nullable)
        json socials (nullable)
        json press_kits (nullable)
        timestamps
    }

    class ArtistMember {
        UUID id
        UUID artist_id
        UUID user_id
        string role (enum)
        string status (enum)
        json permissions (nullable)
        timestamp joined_at (nullable)
        timestamps
    }

    class ArtistInvitation {
        UUID id
        UUID artist_id
        UUID inviter_id
        string email
        string role
        string status (enum)
        string token (unique)
        timestamp expires_at
        timestamps
    }

    class ArtistAlias {
        UUID id
        UUID artist_id
        string name
        string slug (unique)
        string status (enum)
        timestamps
    }

    Artist "1" -- "many" ArtistMember : has
    Artist "1" -- "many" ArtistInvitation : invites
    Artist "1" -- "many" ArtistAlias : alias
    Artist "1" -- "1" ArtistProfile : profile

    note for Artist "organization_id references Accounts.Organizations when rostered"
    note for ArtistMember "role maps to creator-level permissions"

🧱 Domain Models in Scope

Model Stored in Description
App\Models\Creators\Artist artists Canonical artist entity, optionally rostered under an organization.
App\Models\Creators\ArtistProfile artist_profiles Extended profile content (bio, socials, press kits).
App\Models\Creators\ArtistMember artist_members Pivot linking users/collaborators to artists with roles.
App\Models\Creators\ArtistInvitation artist_invitations Pending invitations for future collaborators.
App\Models\Creators\ArtistAlias artist_aliases Additional performer or project names under the same artist.

📋 Table Details

artists

artists holds the canonical entry for every creator, including optional linkage to a label (organization) for roster management.

Column Type Notes
id UUID Primary key.
name string Canonical creator name.
slug string URL-safe identifier; unique per artist.
bio text (nullable) Narrative biography for public pages.
organization_id UUID (nullable) Links artist to an Accounts organization for roster management.
country_code string (nullable) ISO code for search filters and compliance.
links JSON (nullable) External links (Bandcamp, socials).
visuals JSON (nullable) Artwork references (cover, banner, gallery). Each entry typically stores a Spatie Media Library identifier/conversion for first-party assets.
timestamps — Laravel managed.

artist_profiles

Extended profile information (long-form text, socials, media kits) lives in artist_profiles to keep the core artist row lean.

Column Type Notes
id UUID Primary key.
artist_id UUID FK to artists.
about text (nullable) Long-form story, EPK blurbs.
socials JSON (nullable) Structured social handles.
press_kits JSON (nullable) Links/assets for media kits (references to Spatie media items or external URLs).
timestamps — Audit metadata changes.

artist_members

artist_members map users to artists, recording their role, status, and any creator-level permission overrides.

Column Type Notes
id UUID Primary key.
artist_id UUID FK to artists.
user_id UUID FK to Accounts users.
role string owner, admin, member, collaborator.
status string pending, active, removed.
permissions JSON (nullable) Overrides for specific actions (release.publish). Label managers creating artists can seed additional abilities here when necessary.
joined_at timestamp (nullable) When invite was accepted.
timestamps — Track membership updates.

artist_invitations

Pending collaborator invites are stored in artist_invitations until the recipient accepts and an ArtistMember is created.

Column Type Notes
id UUID Primary key.
artist_id UUID FK to artists.
inviter_id UUID FK to users (sender).
email string Recipient; supports non-registered collaborators.
role string Proposed role on acceptance.
status string pending, accepted, declined, revoked.
token string Signed token for acceptance flows.
expires_at timestamp Invite validity window.
timestamps — Invite lifecycle tracking.

artist_aliases

Use artist_aliases to capture alternate project names, side projects, or transliterations under a single artist.

Column Type Notes
id UUID Primary key.
artist_id UUID FK to artists.
name string Alternate or project name.
slug string Unique handle for alias routes.
status string active, archived.
timestamps — Alias history.

🧪 Migration Notes

  • Use UUID primary keys for parity with Accounts context. Add composite uniqueness on (artist_id, user_id) in artist_members.
  • Index status columns for quick roster filtering; index organization_id on artists for label-level queries.
  • Consider soft deletes on artist_profiles only if versioning is required; otherwise rely on audit events.
  • Invitations should cascade delete when artists are removed to avoid orphaned tokens.
  • docs/contexts/creators/index.md — Overview and flows for the Creators context.
  • docs/contexts/auth/roles-permissions.md — Permission resolution involving artist members.
  • docs/contexts/diagrams/index.md — Central directory of ER diagrams.