Artist Module Backend

Related documentation: Artist Source of Truth Registry · Artist Product Vision · Artist Endpoint Map · Frontend Artist · Artist Module Backend API · Base Modules Backend · Data ownership

Purpose

This page explains what the artist base module is in Kisum today.

The current runtime repository is Backend-Kisum-Artists, and in product taxonomy this backend is the Artist module backend.

This documentation should be read as a description of the current system.

What the Artist module is

The Artist module is Kisum’s artist/agency commercial network and booking backend.

It is where the platform handles:

• artist and agency directory records
• representation and roster ownership
• availability management
• booking negotiation and booking confirmation
• booking-linked contracts
• touring and itinerary coordination
• logistics submissions and artist-side approvals
• relationship memory and trust
• promoter and agency read models
• booking-linked finance visibility

Short version:

• this is not just artist CRUD
• this is not just a public marketplace
• this is the operational artist/agency side of the live-entertainment network inside Kisum

What the Artist module owns

The Artist module runtime is the source of truth for:

• artists
• artist profiles
• market companies
• people / contacts
• genres / subgenres
• Market geo reference data
• platform accounts
• provider references
• roster links
• artist team assignments
• company claims
• artist representation claims and disputes
• artist availabilities
• booking requests / offers / holds / bookings / booking activity
• contract templates and booking-linked contract workflow
• tours, stops, routing, itinerary, logistics, and logistics approvals
• relationship memory, notes, flags, ratings, trust scoring
• dashboards, shortlists, and marketplace read models
• booking-level finance visibility and finance handoff audit

What the Artist module does not own

Auth

• users
• sessions
• JWT
• memberships
• permission truth

Core

• tenant companies
• business units
• subscriptions
• packages
• add-ons
• entitlement truth

Finance

• deposits as source of truth
• invoices
• settlements
• payouts
• accounting / ledger truth

Venue

• venue inventory
• space operations
• venue execution workflows
• venue-owned contract truth

Runtime shape

• runtime: Go + Fiber
• route base: /api/v1
• source of truth: Market Postgres
• docs artifact: generated OpenAPI plus hand-written system docs

Auth modes:

• browser / user flows: Authorization: Bearer <JWT> + x-org
• trusted machine flows: X-Internal-API-Key

Browser CORS:

• preferred env: CORS_ORIGIN (comma-separated Kisum frontend origins)
• legacy fallback: non-wildcard CORS_ALLOWED_ORIGINS
• when CORS_ORIGIN is set, CORS_ALLOWED_ORIGINS=* is ignored
• explicit allowlists enable Access-Control-Allow-Credentials for credentialed browser clients

How the system is organized

The Artist module should be understood as one connected system with these capability areas:

1. Directory and identity

Used to maintain:

• artist records
• agencies / market companies
• contacts / people
• taxonomy
• geo
• platform and provider identities

2. Ownership and representation

Used to answer:

• who owns this company profile
• who represents this artist
• which representation is approved
• which claims are disputed

3. Availability and discovery

Used to:

• publish artist availability
• search avails
• drive artist discovery and booking opportunities

4. Booking workflow

Used to:

• receive inquiries
• turn requests into offers
• manage holds
• confirm bookings
• retain booking activity history

5. Contract workflow

Used to:

• manage company template libraries
• create booking-linked contracts
• manage versions
• manage signers and signatures
• retain contract audit history

6. Touring and logistics coordination

Used to:

• group bookings into tours
• manage stops and routing
• retain itinerary items
• retain booking logistics
• manage promoter-submitted hotels / hospitality / technical / transport proposals
• approve, reject, or request changes from the artist-side crew

7. Relationship intelligence

Used to:

• retain relationship memory
• keep internal notes / flags / ratings
• compute trust signals
• expose booking history

8. Read models and visibility

Used to:

• power agency dashboards
• power promoter dashboards
• power shortlists
• power marketplace search
• show downstream finance visibility relevant to bookings

9. Agency provisioning (2026-05-25)

Used to bridge a fresh Auth/Core company to an artists-company (the “agency”) before any operational surface is meaningful. Two flows:

• takeover — claim an existing unclaimed artists_companies row
• creation — propose a brand-new agency spec for admin approval

Hosted in internal/artists/provisioning/ (separate submodule from workflow/ which owns the in-app claims). Mirror of the Venues provisioning pattern with no file upload and strict one-Auth-company-per-agency enforced via DB unique partial indexes:

• one pending request per Auth org globally
• one pending takeover per (target company, requester) pair
• existing artists_company_claims_approved_uniq keeps enforcing “one approved org per company”

Backed by a new artists_provisioning_requests table (migration 20260525_market_provisioning_requests.sql). On approve (single tx): the service writes a real artists_company_claims row (status=‘approved’) + flips companies.claimed=TRUE + closes the request. Creation also inserts the new companies row from the stored spec first. The existing claim-based ownership checks (IsCompanyOwnedByOrg, etc.) continue to work unchanged.

Admin review goes through Backend-Kisum-Admin → /admin/artist-company-requests/* (X-Internal-API-Key proxy into this module). See the endpoint map for the 9 routes (5 tenant + 4 admin) under /api/v1/artists-companies/{sleeping,takeover-requests,creation-requests,requests} + /api/v1/me/agency + /internal/admin/artist-company-requests/*.

Frontend reading model

Frontend teams should think about the Artist module as product sections, not as route groups.

Main frontend sections are:

1. directory and profiles
2. ownership and representation
3. availability
4. booking pipeline
5. contracts
6. touring
7. logistics approvals
8. relationship memory and trust
9. dashboards and shortlists
10. finance visibility
11. marketplace search

The dedicated frontend guidance is in:

• Frontend Artist

Main integration boundaries

Important remaining cross-service follow-up:

• Finance still needs explicit booking-facing internal endpoints for finance visibility
• Auth still needs final permission / role-grant alignment for the Artist module surface
• Core still needs cleaner explicit tenant-company ↔ Artist-directory company linkage
• product frontends still need to consume the backend in coherent screen flows

Recommended reading order

Use the docs in this order:

1. this page for ownership and scope
2. Artist Product Vision for the conceptual product definition
3. Artist Endpoint Map for what each endpoint is for and where frontend should use it
4. Frontend Artist for screen structure and UI flows
5. Artist Module Backend API for exact runtime route inventory