Artist Source of Truth Registry

Related documentation: Artist Endpoint Map (product flows) · Artist Module Backend API · Promoters API · Data Ownership

Artist Source of Truth Registry

Last verified: 2026-07-31
Scope: Backend-Kisum-Promoters, Frontend-Kisum-Promoters, Backend-Kisum-Artists, Frontend-Kisum-Artists

Purpose

This is the canonical dot-connector for artist-related APIs after the 2026-06 directory migration. For every artist-facing route it records:

1. Who owns the data (source of truth)
2. Which Promoters handler resolves it
3. Which upstream is called (if any)
4. Which Mongo / external stores are touched
5. Which frontend file(s) call the route
6. Which UI screen consumes the response

Use this page when debugging wrong data, planning migrations, or adding new artist endpoints.

Backend-Kisum-AI’s mcp-kisum-artists is now an official machine consumer of this source of truth. It calls GET /api/v1/artists, artist detail, platform-accounts, and provider-refs with X-Internal-API-Key. It exposes four MCP tools and never connects directly to PostgreSQL. Its canonical artistId is the Artists numeric ID; external platform IDs remain separate.

---

Executive summary — three-way split

Concern	Source of truth	Promoters access pattern
Directory / profile shell — list, search, GET :id, name, image, country, genres (display), biography (read via network), platform external ids (Spotify, etc.)	Backend-Kisum-Artists Postgres	Machine BFF: artists-directory.upstream.js or /api/artists-network/* transparent proxy
Analytics / enrichment — stats, demographics, chart presence, predictions, trend, historical, Soundcharts/Viberate/Songstats pipelines, Kworb chart rows	Mongo analytics stores (data_analyst.artist_data, Kworb charts.*, historical collections) + external music APIs	Resolve artist identity + Spotify id from Artists Postgres first (resolveArtistSpotifyFromMaster / resolveArtistMaster); then read analytics Mongo / external APIs. Do not use Mongo artists_v2 as artist master data.
Discography / Spotify album+track payloads	Spotify / MusicData (album lists, album detail, track enrich)	Spotify artist id from Artists Postgres artist_platform_accounts; album/track bodies from Spotify or MusicData
Booking / marketplace / roster / team / relationships / touring	Backend-Kisum-Artists Postgres (workflow + intelligence modules)	/api/artists-network/* → /api/v1/* transparent proxy

Hard rules (do not break)

• Profile + platform ids upstream: GET /api/artists, /search, /:id, event lineup display (resolveLineupArtists), and Spotify/platform external ids come from Artists Postgres — never from Mongo artist docs.
• Booking/event identity: marketplace officialArtistId and all new Promoters Event lineup writes use numeric PostgreSQL artists.id; they are never Mongo ObjectIds.
• Analytics Mongo is not artist master: getStatsById, getDemographicsById, predictions, trend, historical may still touch analytics Mongo collections, but must not treat Mongo artists_v2 as the source of name/image/platforms/slug.
• Discography / top-tracks: resolve via resolveArtistSpotifyFromMaster (Artists Postgres); album/track payloads from Spotify/MusicData; Kworb rows (if any) are analytics only.
• Event lineup stats use analytics paths keyed by resolved artist id — not Mongo as directory SoT.
• Browser never calls Backend-Kisum-Artists internal routes directly (except Frontend-Kisum-Artists agency app with Bearer to Artists public API).

---

Architecture flow

flowchart TB
  subgraph FE_Promoters["Frontend-Kisum-Promoters"]
    Legacy["/api/artists/*\n(data.ts)"]
    Network["/api/artists-network/*\n(artists-network/api.ts)"]
    Events["/api/events/*\n(lineup)"]
  end

  subgraph FE_Artists["Frontend-Kisum-Artists"]
    Direct["ARTISTS_API_BASE_URL\n/api/v1/*"]
  end

  subgraph Promoters["Backend-Kisum-Promoters :3099"]
    ArtistsRoute["artists.route.js"]
    ArtistsV2["artists-v2.route.js"]
    NetworkRoute["artists-network.route.js"]
    EventsQuery["events.query.js"]
    UpstreamDir["artists-directory.upstream.js"]
    ArtistsQuery["artists.query.js"]
  end

  subgraph ArtistsSvc["Backend-Kisum-Artists :3831"]
    PG["Postgres artist master\n+ booking/marketplace"]
  end

  subgraph Mongo["Mongo kisum_data"]
    ArtistsV2Col["artists_v2"]
    ArtistData["data_analyst.artist_data"]
    Charts["charts.*"]
  end

  subgraph External["External APIs"]
    Spotify["Spotify / MusicData"]
    SC["Soundcharts"]
    VB["Viberate"]
    SS["Songstats"]
    DFS["DataForSEO"]
    BIT["Bandsintown"]
    SLF["Setlist.fm"]
    N8N["n8n market-analysis"]
  end

  Legacy --> ArtistsRoute
  Network --> NetworkRoute
  Events --> EventsQuery
  Direct --> ArtistsSvc

  ArtistsRoute -->|"list/search/getById"| UpstreamDir
  UpstreamDir --> ArtistsSvc
  ArtistsRoute -->|"stats/demographics/..."| ArtistsQuery
  ArtistsQuery --> ArtistsV2Col
  ArtistsQuery --> ArtistData
  ArtistsQuery --> Charts
  ArtistsQuery --> External

  NetworkRoute -->|"X-Internal-API-Key + Bearer + x-org"| ArtistsSvc
  EventsQuery -->|"display"| UpstreamDir
  EventsQuery -->|"stats/predictions"| ArtistsQuery

---

Data stores inventory

Store	Database / service	Collection / table	Owns
Artist directory master	Backend-Kisum-Artists Postgres	artists, artist_profiles, artist_genres, artist_platform_accounts, artist_provider_refs, artist_team_assignments, company_needs_agent_artists, company_people, companies/people	Canonical artist identity, profile, bio, genres, platform links, staff-linked representation, booking graph
Analytics artist document	Mongo kisum_data	artists_v2	Legacy enrichment doc: data_platforms, platforms, streamingPlatforms, socials, ranks, Soundcharts/Viberate UUIDs
Aggregated stats	Mongo data_analyst	artist_data	Precomputed stats snapshots used by getStatsById / refresh pipelines
Historical series	Mongo kisum_data	artist_historical (via artistHistoricalModel)	Cached fanbase/stream historical per channel
Genre taxonomy (legacy list)	Mongo kisum_data	others doc id: 'genres'	GET /api/artists/genres filter dropdown
Chart presence	Mongo Kworb	charts.* collections	Chart ranking presence
Promoter CRM	Mongo kisum_data	events, offers, avails	Tenant-scoped business data; still reference artist ids from Mongo _id in many paths

---

Promoters internal resolvers

Function	File	Purpose	SoT
listArtistsFromUpstream / searchArtistsFromUpstream / getArtistByIdFromUpstream	artists/artists-directory.upstream.js	Machine GET to Artists /api/v1/artists*	Artists Postgres
resolveArtistMaster	artists/queries/artists.query.js	Single artist profile for display; maps legacy shape	Artists Postgres
resolveLineupArtists	artists/queries/artists.query.js	Batch upstream for event lineup name/image/country	Artists Postgres
getArtistFromMongo	artists/queries/artists.query.js	Lookup artists_v2 by numeric id, gid, or Mongo _id	Mongo
getArtistsFromMongoByRefs	artists/queries/artists.query.js	Batch Mongo for predictions	Mongo
artistsClient.request	services/artists.client.js	HTTP to ARTISTS_INTERNAL_BASE_URL with X-Internal-API-Key	Artists service

Env (Promoters):

Variable	Required for	Notes
ARTISTS_INTERNAL_BASE_URL	Directory + network BFF	e.g. http://artists.local.kisum.io:3831
ARTISTS_INTERNAL_API_KEY	All Artists machine calls	Must match Artists deployment
ARTISTS_API_TIMEOUT_MS	Optional	Default 30000

Directory routes return 503 when Artists env is unset.

---

Section A — Backend-Kisum-Promoters legacy /api/artists/*

Route file: artists/artists.route.js
Handler: artists/artists.controller.js → ArtistsQuery / ArtistsCommand
Auth: Authorization Bearer + x-org (tenant). Most routes: optionalRequirePermissions([]). Writes: PERMISSIONS.ARTIST.EDIT.

#	Method	Promoters path	Query method	Source of truth	Upstream / stores	External APIs	Frontend caller(s)	UI / flow
1	POST	/api/artists/migrate	migrateArtistsImagePath	Promoters ops (image path fix)	Mongo artists_v2 writes	—	Internal/admin only	Migration utility
2	GET	/api/artists	get → listArtistsFromUpstream	Artists Postgres	GET /api/v1/artists via machine BFF	—	libs/data.ts → fetchArtists; hooks/use-artists.ts; combobox-artists.tsx; artists/page list	Artist directory list, comboboxes, event create
3	GET	/api/artists/search	search → searchArtistsFromUpstream	Artists Postgres	GET /api/v1/artists?q=	—	libs/data.ts → searchArtists; combobox-artists.tsx	Typeahead search
4	GET	/api/artists/genres	getGenres	Mongo others	kisum_data.others where id: 'genres'	—	libs/data.ts → getArtistGenres; combobox-artist-genres.tsx	Genre filter dropdowns
5	GET	/api/artists/:id/trend	getTrendById	DataForSEO (artist name from Mongo)	getArtistFromMongo for name	Google Trends via DataForSEO	libs/data.ts → getArtistTrend*; some paths via Amplify ROUTER_URL	Analytics → trend charts
6	GET	/api/artists/:id/data	getDataById	Mongo analytics bundle	getArtistFromMongo + artist_data	Various per field	Legacy integrations	Country-scoped data bundle
7	GET	/api/artists/:id/data-v2	getDataByIdV2	Mongo analytics bundle	Same as data	Various	Legacy	v2 data bundle
8	GET	/api/artists/:id/stats	getStatsById	Mongo artist_data + refresh	getArtistFromMongo; may refresh via Soundcharts/Viberate/Songstats	Spotify, SC, VB, SS	libs/data.ts → getArtistStats; artist-overview-audience.tsx; artist-analytics-statistic.tsx; getArtistDetailOverview uses /api/artist/:id/stats (typo path — verify proxy)	Overview audience, analytics stats
9	GET	/api/artists/:id/card-stats	getCardStats	Mongo	getArtistFromMongo; may update socials	—	libs/data.ts → getArtistCardStats; artist-hero.tsx	Hero card metrics
10	GET	/api/artists/:id/demographics	getDemographicsById	Mongo + platform APIs	getArtistFromMongo; data_platforms enrichment writes	Soundcharts/Viberate/Songstats per channel	libs/data.ts → getArtistDemographics_v2; artist-analytics-demographics.tsx; demographics *.tsx per platform; Next route app/api/artists/[id]/demographics	Demographics tabs
11	GET	/api/artists/:id/setlistfm	getSetlistfmById	Mongo + Setlist.fm	getArtistFromMongo	Setlist.fm API	Legacy setlist components	Setlists
12	GET	/api/artists/:id/prediction/:countryCode	getPredictionByIdAndCountryCode	Mongo	getArtistFromMongo	Internal prediction models	libs/data.ts → getArtistPrediction	Prediction by country
13	GET	/api/artists/:id/bandsintown/events	getBandsInTownEventsById	Mongo + Bandsintown	getArtistFromMongo	Bandsintown	libs/data.ts → getArtistBandsintownEvents; artist-overview-upcoming-shows.tsx; artist-shows.tsx	Upcoming shows
14	GET	/api/artists/:id/bandsintown	getBandsInTownById	Mongo + Bandsintown	getArtistFromMongo	Bandsintown	libs/data.ts	Bandsintown profile
15	GET	/api/artists/:id/historical	getHistorical	Mongo artist_historical + Viberate/Soundcharts	getArtistFromMongo; cache collection	Viberate, Soundcharts	libs/data.ts → getArtistHistorical	Historical fanbase charts
16	GET	/api/artists/:id/discography/:albumId	getDiscographyAlbumById	Artists Postgres + MusicData / Spotify	resolveArtistSpotifyFromMaster for Spotify id (slug/id/uuid); album from MusicData/Spotify	MusicData /spotify/albums/:id or local Spotify	artist-discography.tsx	Album detail
17	GET	/api/artists/:id/discography	getDiscographyById	Artists Postgres + Spotify / MusicData	resolveArtistSpotifyFromMaster for Spotify id; albums/tracks from Spotify (or MusicData when ?ids=)	Spotify / MusicData /spotify/*	libs/data.ts → getArtistDiscography*; artist-discography.tsx; artist-overview-latest-release.tsx	Discography list
18	GET	/api/artists/:id/top-tracks	getTopTracksById	Artists Postgres + Kworb charts + Spotify / MusicData	resolveArtistSpotifyFromMaster; Kworb charts.* by Spotify id; enrich via Spotify/MusicData	Kworb Mongo + Spotify / MusicData	libs/data.ts → getArtistTopTracks; artist-overview-top-tracks.tsx	Top tracks
19	GET	/api/artists/:id/top-songs-regional	getRegionalTopSongsById	Mongo + analytics APIs	getArtistFromMongo	Songstats / Soundcharts	libs/data.ts; artist-regional-top-songs.shared.tsx	Regional top songs
20	GET	/api/artists/:id/chart-presence	getChartPresenceById	Mongo Kworb charts.*	getArtistFromMongo	Kworb chart DB	libs/data.ts → getArtistChartPresence; artist-overview-chart-presence.tsx	Chart presence
21	GET	/api/artists/:id/top-countries	getTopCountriesById	Mongo (may write soundcharts_uuid)	getArtistFromMongo; optional Mongo update	Soundcharts	libs/data.ts → getArtistTopCountries; artist-overview-top-countries.tsx	Top countries
22	GET	/api/artists/:id/charts/song/ranks/:platform	getChartSongRanksById	Soundcharts (proxy)	getArtistFromMongo; resolve/persist soundcharts_uuid	Soundcharts GET /v2/artist/{uuid}/charts/song/ranks/{platform}	(pending frontend)	Chart song entries / peaks
23	GET	/api/artists/:id/events	getEventByArtistId	Promoters events collection	Mongo events where artist in lineup	—	Event-artist cross views	Artist’s events
24	GET	/api/artists/:id/performance	getPerformanceById	Mongo analytics	getArtistFromMongo	—	Performance analytics	Performance tab
25	GET	/api/artists/:id/contacts	getContactsById	Mongo artists_v2.team	Aggregation on team.agencies / management peoples	—	Legacy contacts (prefer network team)	Contacts drawer
26	GET	/api/artists/:id	getById → resolveArtistMaster	Artists Postgres	GET /api/v1/artists/:id?include=profile,genres,platforms,providers	—	libs/data.ts → getArtist; legacy paths; Note: detail shell prefers artists-network	Artist detail fallback
27	POST	/api/artists/:id/prediction-v2	getPredictionByIdV2	Mongo	getArtistFromMongo	Internal models	libs/data.ts	Prediction v2
28	POST	/api/artists/:id/prediction-v3	getPredictionByIdV3	Mongo	getArtistFromMongo	Internal models	libs/data.ts; app/api/artists/[id]/prediction-v3; Amplify ROUTER_URL	artist-analytics-prediction.tsx
29	POST	/api/artists/market-analysis	getMarketAnalysis	n8n workflow	Body from Mongo-enriched context	n8n webhook	libs/data.ts → getArtistMarketAnalysis; artist-analytics-prediction.tsx	Market analysis AI
30	POST	/api/artists/:id/bio	createBio (command)	Mongo bio write (legacy)	Approval workflow in Promoters	—	Legacy bio submit	Prefer PUT /api/artists-network/artists/:id/profile

Section A — ID resolution notes

getArtistFromMongo accepts:

• Numeric Kisum id (artists_v2.id)
• Legacy Mongo gid string
• Mongo _id ObjectId

resolveArtistMaster / upstream accept:

• Bigint id, UUID, slug, or legacy gid (Artists service resolves)

---

Section B — GET /api/v2/artists*

Route file: artists/artists-v2.route.js

Method	Path	Handler	SoT	Notes
GET	/api/v2/artists	ArtistsQuery.get	Artists Postgres	Same as GET /api/artists
GET	/api/v2/artists/:id	ArtistsQuery.getById	Artists Postgres	Same as GET /api/artists/:id

No Mongo layer models on live v2 list/detail path.

---

Section C — Backend-Kisum-Promoters /api/artists-network/*

Route file: artists-network/artists-network.route.js
Proxy: artists-network/artists-network.controller.js → services/artists.client.js
SoT: Backend-Kisum-Artists Postgres (all transparent proxies unless noted)
Auth: JWT + x-org + permission keys (promoter.artist, promoter.artist_offer, etc.)
Upstream headers: X-Internal-API-Key, forwarded Authorization, x-org

#	Method	Promoters BFF path	Artists upstream	Permission	FE function (artists-network/api.ts)	UI screen(s)
1	GET	/marketplace/artist-availabilities	/api/v1/marketplace/artist-availabilities	VIEW_AVAIL	searchMarketplaceAvails	booking/marketplace/page.tsx
2	GET	/marketplace/artists	/api/v1/marketplace/artists	VIEW_ARTIST	(marketplace browse)	Marketplace
3	GET	/marketplace/agencies	/api/v1/marketplace/agencies	VIEW_ARTIST	listMarketplaceAgencies	Marketplace agencies
4	GET	/companies/:id	/api/v1/companies/:id	VIEW_ARTIST	getArtistsCompany	Agency/company detail
5	GET	/companies/:id/roster	/api/v1/companies/:id/roster	VIEW_ARTIST	listArtistsCompanyRoster	Roster views
6	GET	/companies/:id/people	/api/v1/companies/:id/people	VIEW_ARTIST	listArtistsCompanyPeople	Staff/people
7	GET	/people/:id	/api/v1/people/:id	VIEW_ARTIST	getArtistsPerson	Person detail
8	GET	/people/:id/companies	/api/v1/people/:id/companies	VIEW_ARTIST	listArtistsPersonCompanies	Person ↔ companies
9	GET	/artists	/api/v1/artists	VIEW_ARTIST	listArtistsDirectory	Directory (network shape)
10	GET	/artists/:id	/api/v1/artists/:id	VIEW_ARTIST	getArtistsArtist	Base shell
11	GET	/artists/:id/profile	/api/v1/artists/:id/profile	VIEW_ARTIST	fetchArtistProfileRow	artist-detail-context.tsx, artist-biography.tsx
12	PUT	/artists/:id/profile	/api/v1/artists/:id/profile	EDIT_ARTIST	(profile edit)	Bio edit
13	POST	/artists/:id/profile/ensure-short-bio	BFF-only (Gemini → PUT profile)	EDIT_ARTIST	ensureArtistsArtistShortBio	artist-biography.tsx
14	POST	/artists/:id/profile/ensure-bio-formatted	BFF-only (Gemini → PUT profile)	EDIT_ARTIST	ensureArtistsArtistBioFormatted	artist-biography.tsx
15	GET	/artists/:id/genres	/api/v1/artists/:id/genres	VIEW_ARTIST	fetchArtistSubresourceRows	Detail tabs
16	GET	/artists/:id/subgenres	/api/v1/artists/:id/subgenres	VIEW_ARTIST	fetchArtistSubresourceRows	Detail tabs
17	GET	/artists/:id/platform-accounts	/api/v1/artists/:id/platform-accounts	VIEW_ARTIST	fetchArtistSubresourceRows	Platforms
18	GET	/artists/:id/provider-refs	/api/v1/artists/:id/provider-refs	VIEW_ARTIST	fetchArtistSubresourceRows	Provider refs
19	GET	/artists/:id/team	/api/v1/artists/:id/team	VIEW_ARTIST	getArtistsArtistContacts	Contacts / team
20	GET	/artists/:id/roster	/api/v1/artists/:id/roster	VIEW_ARTIST	fetchArtistSubresourceRows	Roster links
21	GET	/promoters/:id/dashboard	/api/v1/promoters/:id/dashboard	VIEW_ARTIST	getPromoterDashboard	dashboard-booking-network.tsx
22	GET	/promoters/:id/shortlists	/api/v1/promoters/:id/shortlists	VIEW_ARTIST	listPromoterShortlists	booking/shortlists/page.tsx
23	POST	/promoters/:id/shortlists	/api/v1/promoters/:id/shortlists	EDIT_OFFER	createPromoterShortlist	create-shortlist-dialog.tsx
23a	GET	/promoters/:id/shortlists/:shortlistId	same	VIEW_ARTIST	getPromoterShortlist	booking/shortlists/[id]/page.tsx
23b	DELETE	/promoters/:id/shortlists/:shortlistId	same	EDIT_OFFER	deletePromoterShortlist	shortlist detail
24	POST	/promoters/:id/shortlists/:shortlistId/artists	same	EDIT_OFFER	addArtistToShortlist	add-artist-to-shortlist-dialog.tsx
24a	DELETE	/promoters/:id/shortlists/:shortlistId/artists/:artistId	same	EDIT_OFFER	removeArtistFromShortlist	shortlist detail
25	GET	/promoters/:id/booking-history	/api/v1/promoters/:id/booking-history	VIEW_OFFER	—	Dashboard/history
26	GET	/promoters/:id/inquiries	/api/v1/promoters/:id/inquiries	VIEW_OFFER	—	Inquiries
27	GET	/promoters/:id/offers	/api/v1/promoters/:id/offers	VIEW_OFFER	—	Legacy offers list
28	GET	/booking-requests	/api/v1/booking-requests	VIEW_OFFER	listBookingRequests	booking/requests/page.tsx
29	POST	/booking-requests	/api/v1/booking-requests	EDIT_OFFER	createBookingRequest	send-booking-request-sheet.tsx
30	GET	/booking-requests/:requestId	/api/v1/booking-requests/:requestId	VIEW_OFFER	getBookingRequest	booking/requests/[id]/page.tsx
31	PATCH	/booking-requests/:requestId	/api/v1/booking-requests/:requestId	EDIT_OFFER	patchBookingRequest	Request edit
32	POST	/booking-requests/:requestId/withdraw	/api/v1/booking-requests/:requestId/withdraw	EDIT_OFFER	withdrawBookingRequest	withdraw-request-dialog.tsx
33	POST	/booking-requests/:requestId/convert-to-offer	/api/v1/booking-requests/:requestId/convert-to-offer	EDIT_OFFER	convertBookingRequestToOffer	convert-to-offer-dialog.tsx
34	GET	/booking-offers	/api/v1/booking-offers	VIEW_OFFER	listBookingOffers	booking/offers/page.tsx
35	POST	/booking-offers	/api/v1/booking-offers	EDIT_OFFER	—	Create offer
36	GET	/booking-offers/:offerId	/api/v1/booking-offers/:offerId	VIEW_OFFER	getBookingOffer	booking/offers/[id]/page.tsx
37	POST	/booking-offers/:offerId/counter	/api/v1/booking-offers/:offerId/counter	EDIT_OFFER	counterBookingOffer	counter-offer-dialog.tsx
38	POST	/booking-offers/:offerId/accept	/api/v1/booking-offers/:offerId/accept	EDIT_OFFER	acceptBookingOffer	accept-offer-dialog.tsx
39	POST	/booking-offers/:offerId/decline	/api/v1/booking-offers/:offerId/decline	EDIT_OFFER	declineBookingOffer	decline-offer-dialog.tsx
40	POST	/booking-offers/:offerId/cancel	/api/v1/booking-offers/:offerId/cancel	EDIT_OFFER	cancelBookingOffer	cancel-offer-dialog.tsx
41	GET	/booking-offers/:offerId/holds	/api/v1/booking-offers/:offerId/holds	VIEW_OFFER	listOfferHolds	offer-holds-panel.tsx
42	POST	/booking-offers/:offerId/holds	/api/v1/booking-offers/:offerId/holds	EDIT_OFFER	createOfferHold	Holds panel
43	PATCH	/booking-offers/:offerId/holds/:holdId	/api/v1/booking-offers/:offerId/holds/:holdId	EDIT_OFFER	releaseOfferHold (release action)	Holds panel
44	GET	/bookings	/api/v1/bookings	VIEW_OFFER	—	booking/confirmed/page.tsx
45	GET	/bookings/:bookingId	/api/v1/bookings/:bookingId	VIEW_OFFER	getBooking	booking/confirmed/[id]/page.tsx
46	GET	/bookings/:bookingId/activity	/api/v1/bookings/:bookingId/activity	VIEW_OFFER	listBookingActivity	booking-activity-timeline.tsx
47	POST	/bookings/:bookingId/activity	/api/v1/bookings/:bookingId/activity	EDIT_OFFER	postBookingActivity	Activity timeline
48	GET	/bookings/:bookingId/finance-status	/api/v1/bookings/:bookingId/finance-status	VIEW_DEAL	getBookingFinanceStatus	booking-finance-tab.tsx
49	GET	/bookings/:bookingId/payment-schedule	/api/v1/bookings/:bookingId/payment-schedule	VIEW_DEAL	getBookingPaymentSchedule	Finance tab
50	GET	/bookings/:bookingId/deposit-status	/api/v1/bookings/:bookingId/deposit-status	VIEW_DEAL	getBookingDepositStatus	Finance tab
51	POST	/bookings/:bookingId/finance-handoff	/api/v1/bookings/:bookingId/finance-handoff	EDIT_OFFER	postBookingFinanceHandoff	finance-handoff-dialog.tsx
52–61	GET/POST	/relationships/*	/api/v1/relationships/*	VIEW_ARTIST / EDIT_OFFER	listRelationships, getRelationship*, etc.	booking/relationships/*
62–69	GET/POST	/artists/:id/tour-plans, /tour-plans/*, /bookings/:id/logistics*	/api/v1/*	VIEW_LOGISTICS / EDIT_LOGISTICS	logistics helpers in api.ts	booking-logistics-tab.tsx, touring

Finance note: Booking finance visibility routes read Artists-computed handoff status; money truth remains Backend-Kisum-Finance.

---

Section D — Events cross-cutting (artist data)

File: events/queries/events.query.js

Event endpoint	Artist concern	Resolver	SoT
GET /api/events/:id/lineup	Lineup display (name, image, country)	resolveLineupArtists	Artists Postgres
Same	Lineup stats per artist	getStatsById(..., null)	Mongo artist_data
Event predictions / financial artist bundle	Artist enrichment for prediction	getArtistsFromMongoByRefs	Mongo artists_v2
Offer flow artist display	Single artist shell	resolveArtistMaster	Artists Postgres

Frontend: libs/data.ts → getEventLineup; useEventArtists.ts (main + public events).

---

Section E — Other Promoters modules still on Mongo artists_v2

These modules have not been migrated to Artists upstream for artist master reads:

Module	File(s)	Usage
Avails	avails/*	Artist refs on avail rows; marketplace browse moved to network
Offer	offer/commands/offer.command.js	artistsModel.find for offer artist snapshot
Agencies	agencies/queries/agencies.query.js	Roster artist details from Mongo + artist_data
Rankings	rankings queries	Rank sort from Mongo
Setlistfm	setlist module	Artist lookup
Kisum AI	kisumAi/*	Artist context for AI
Artist utils	utils/artist-stats-refresh.utils.js	Mongo updateOne for platform UUID normalization

Rule: New features should use Artists Postgres for identity and Mongo only for analytics enrichment.

---

Section F — Backend-Kisum-Artists canonical API

Base: /api/v1 (Fiber)
Auth: Bearer JWT (+ tenant context per route); internal machine routes use service keys as configured.

F.1 — CRUD entities (internal/artists/routes/routes.go)

Resource	List	Get	Create	Update	Delete
/artists	✓	✓	✓	✓	✓
/companies	✓	✓	✓	✓	✓
/people	✓	✓	✓	✓	✓
/genres, /subgenres, /regions, /countries, /states, /cities, /platforms, /provider-sources	✓	✓	✓	✓	✓

F.2 — Artist relations (same file)

Path	Methods	Postgres tables (conceptual)
/artists/:id/profile	GET, PUT	artist_profiles
/artists/:id/genres	GET, PUT	artist_genres
/artists/:id/subgenres	GET, PUT	subgenres link
/artists/:id/platform-accounts	GET, PUT	platform accounts
/artists/:id/provider-refs	GET, PUT	external provider refs
/artists/:id/team	GET, PUT	team members
/artists/:id/roster	GET, PUT	roster links

F.3 — Workflow / marketplace / booking (workflow, intelligence, touring, contracts, provisioning modules)

Registered in internal/artists/module.go:

• Marketplace: /marketplace/artist-availabilities, /marketplace/artists, /marketplace/agencies
• Booking: /booking-requests, /booking-offers, /bookings (+ activity, holds, finance visibility)
• Promoter: /promoters/:id/dashboard, shortlists, booking-history
• Relationships, touring, logistics, contracts — see OpenAPI internal/openapi/spec.go

SoT for all F.3 routes: Artists Postgres (+ Finance handoff references only).

---

Section G — Frontend-Kisum-Promoters caller matrix (by screen)

UI route / component	API surface	SoT consumed
/artists list	GET /api/artists	Artists Postgres (legacy envelope)
/artists/[id] layout shell	artists-network → profile, genres, platforms, team	Artists Postgres
/artists/[id] overview audience	GET /api/artists/:id/stats	Mongo analytics
/artists/[id] hero	GET /api/artists/:id/card-stats	Mongo
/artists/[id] demographics *	GET /api/artists/:id/demographics	Mongo + APIs
/artists/[id] discography	/discography, /top-tracks	Artists Postgres (Spotify id) + Spotify/MusicData (+ Kworb for top-tracks)
/artists/[id] chart presence	/chart-presence	Mongo Kworb
/artists/[id] top countries	/top-countries	Mongo
/artists/[id] regional songs	/top-songs-regional	Mongo
/artists/[id] shows	/bandsintown/events	Mongo + BIT
/artists/[id] analytics prediction	/trend, /prediction-v3, /market-analysis	Mongo + DataForSEO + n8n
/artists/[id] biography	artists-network profile + ensure-bio	Artists Postgres
/booking/*	/api/artists-network/*	Artists Postgres
/events/[id] lineup	GET /api/events/:id/lineup	Mixed: display=Artists, stats=Mongo
combobox-artists	fetchArtists, searchArtists	Artists Postgres
form-event / EventCreateDrawer	fetchArtists	Artists Postgres

G.1 — Amplify / Next.js route proxies

Some analytics calls bypass direct Promoters URL:

Next/Amplify path	Proxies to	Notes
app/api/artists/[id]/demographics/route.tsx	Promoters /api/artists/:id/demographics	May use ROUTER_URL
app/api/artists/[id]/prediction-v3/route.tsx	Promoters POST .../prediction-v3	Lambda router
libs/data.ts trend/demographics	${ROUTER_URL}/api/artists/...	Legacy Amplify path for cache

---

Section H — Frontend-Kisum-Artists (agency app)

API client: src/lib/api-client.ts → ARTISTS_API_BASE_URL + /api/v1/*
Service: src/services/artists/api.ts (2000+ lines — full Artists surface)

Pattern	SoT
Direct Bearer to Artists public API	Artists Postgres (no Promoters BFF)
Agency roster, booking, contracts, touring	Same as Section F

Promoters browser app must not copy this pattern — it uses Promoters BFF only.

---

Section I — Implementation file map

Concern	Path
Legacy artist routes	Backend-Kisum-Promoters/artists/artists.route.js
v2 artist routes	Backend-Kisum-Promoters/artists/artists-v2.route.js
Network BFF routes	Backend-Kisum-Promoters/artists-network/artists-network.route.js
Query / resolver logic	Backend-Kisum-Promoters/artists/queries/artists.query.js
Directory upstream	Backend-Kisum-Promoters/artists/artists-directory.upstream.js
Legacy shape mapper	Backend-Kisum-Promoters/artists/artists-directory.mapper.js
Artists HTTP client	Backend-Kisum-Promoters/services/artists.client.js
Event lineup	Backend-Kisum-Promoters/events/queries/events.query.js
FE legacy API	Frontend-Kisum-Promoters/src/libs/data.ts
FE network API	Frontend-Kisum-Promoters/src/services/apis/artists-network/api.ts
Artists Go routes	Backend-Kisum-Artists/internal/artists/routes/routes.go
Artists module mount	Backend-Kisum-Artists/internal/artists/module.go

---

Section J — Known gaps & follow-ups

Gap	Status
iso2 query filter on GET /api/artists	Mapped (2026-07-10) — Promoters forwards iso2 to Artists; Artists filters artists.country_id via countries.iso2 (comma-separated OK)
genres query filter on GET /api/artists	Not fully mapped to Artists upstream list params
GET /api/artists/:id/contacts	Mongo team aggregation; prefer artists-network/.../team
Offer/avails/agencies/rankings artist reads	Still Mongo artists_v2
Event lineup rank field	May differ between Mongo rank vs Artists profile — verify product intent
GET /api/artist/:id/stats (singular) in getArtistDetailOverview	Possible typo vs /api/artists/:id/stats — verify API gateway

---

Section K — Middle Agent Workspace (parallel workflow)

Middle-agent data is not stored on booking_requests / booking_offers. It lives in parallel tables under Backend-Kisum-Artists (workspace_artists, middle_agent_offers, …).

Concern	Owner	Browser path	Upstream
Operator deal desk	Frontend-Kisum-Artists	/middle-agent/*	GET/PATCH /api/v1/middle-agent/*
Promoter marketplace browse	Frontend-Kisum-Promoters	/booking/marketplace (Non-direct tab)	GET /api/artists-network/middle-agent/listings
Promoter enquiry	Frontend-Kisum-Promoters	SendMiddleAgentEnquirySheet	POST /api/artists-network/middle-agent/enquiries
Promoter outbox	Frontend-Kisum-Promoters	/booking/middle-agent-enquiries	GET /api/artists-network/middle-agent/enquiries
Source-agent inbox	Frontend-Kisum-Artists	/middle-agent/inbound-source-offers	GET /api/v1/middle-agent/inbound-source-offers
Direct booking (unchanged)	Both apps	/booking-requests, /booking-offers	/api/v1/booking-requests, /api/v1/booking-offers

Platform doc: Middle Agent Workspace. ADR: Backend-Kisum-Artists/docs/adr/20260625-middle-agent-parallel-workflow.md.

---

Maintenance

When adding or changing any artist route:

1. Update this registry (same PR as code).
2. Update Backend-Kisum-Promoters/docs/ARTIST_SOURCE_OF_TRUTH_REGISTRY.md (mirror).
3. Update Frontend-Kisum-Promoters/docs/ARTIST_API_SOURCE_OF_TRUTH.md if FE callers change.
4. Update Backend-Kisum-Artists/docs/artist-source-of-truth-registry.md if upstream contract changes.
5. Add row to Data Ownership if ownership moves.

---

Related package docs

• Backend-Kisum-Promoters/docs/ARTISTS_NETWORK_BFF.md — network proxy details
• Backend-Kisum-Promoters/docs/ARTIST_SOURCE_OF_TRUTH_REGISTRY.md — package mirror
• Frontend-Kisum-Promoters/docs/ARTIST_API_SOURCE_OF_TRUTH.md — FE caller index
• Backend-Kisum-Artists/docs/artist-source-of-truth-registry.md — upstream owner index