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-06-07
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.

---

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)	Backend-Kisum-Artists Postgres	Machine BFF: artists-directory.upstream.js or /api/artists-network/* transparent proxy
Analytics / enrichment — stats, demographics, discography, chart presence, predictions, trend, historical, platform UUIDs, Soundcharts/Viberate/Songstats/Spotify pipelines	Mongo kisum_data.artists_v2 + data_analyst.artist_data + Kworb charts.* + external music APIs	ArtistsQuery.getArtistFromMongo — must not route through Artists upstream
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-only upstream: GET /api/artists, /search, /:id, /v2/artists*, event lineup display (resolveLineupArtists).
• Analytics stay Mongo: getStatsById, getDemographicsById, discography, predictions, trend, etc. use getArtistFromMongo.
• Event lineup stats use Mongo (getStatsById with null company).
• Event predictions use Mongo batch (getArtistsFromMongoByRefs).
• 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, companies/people/roster	Canonical artist identity, profile, bio, genres, platform links, team, 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/search/new	searchNew	Spotify (live search)	—	Spotify client (this.spotify.searchArtists)	libs/data.ts → searchArtistsNew; artists/add/page.tsx	Add artist — external discovery
5	GET	/api/artists/search/new/music-brainz	searchNewMusicBrainz	MusicBrainz	—	MUSIC_BRAINZ_URL WS API	libs/data.ts → searchArtistsMusicBrainz	Add artist — MB lookup
6	GET	/api/artists/genres	getGenres	Mongo others	kisum_data.others where id: 'genres'	—	libs/data.ts → getArtistGenres; combobox-artist-genres.tsx	Genre filter dropdowns
7	GET	/api/artists/platforms	getByPlatform	Mongo + live platform APIs	getArtistFromMongo for UUIDs; then Viberate/Songstats/Soundcharts	Platform resolver APIs	libs/data.ts → getArtistPlatforms	Platform linking UI
8	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
9	GET	/api/artists/:id/data	getDataById	Mongo analytics bundle	getArtistFromMongo + artist_data	Various per field	Legacy integrations	Country-scoped data bundle
10	GET	/api/artists/:id/data-v2	getDataByIdV2	Mongo analytics bundle	Same as data	Various	Legacy	v2 data bundle
11	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
12	GET	/api/artists/:id/card-stats	getCardStats	Mongo	getArtistFromMongo; may update socials	—	libs/data.ts → getArtistCardStats; artist-hero.tsx	Hero card metrics
13	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
14	GET	/api/artists/:id/setlistfm	getSetlistfmById	Mongo + Setlist.fm	getArtistFromMongo	Setlist.fm API	Legacy setlist components	Setlists
15	GET	/api/artists/:id/prediction/:countryCode	getPredictionByIdAndCountryCode	Mongo	getArtistFromMongo	Internal prediction models	libs/data.ts → getArtistPrediction	Prediction by country
16	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
17	GET	/api/artists/:id/bandsintown	getBandsInTownById	Mongo + Bandsintown	getArtistFromMongo	Bandsintown	libs/data.ts	Bandsintown profile
18	GET	/api/artists/:id/historical	getHistorical	Mongo artist_historical + Viberate/Soundcharts	getArtistFromMongo; cache collection	Viberate, Soundcharts	libs/data.ts → getArtistHistorical	Historical fanbase charts
19	GET	/api/artists/:id/discography/:albumId	getDiscographyAlbumById	MusicData / Spotify	Album id from Mongo artist context	API-MusicData proxy	artist-discography.tsx	Album detail
20	GET	/api/artists/:id/discography	getDiscographyById	Mongo + MusicData	getArtistFromMongo for Spotify id	MusicData /spotify/*	libs/data.ts → getArtistDiscography*; artist-discography.tsx; artist-overview-latest-release.tsx	Discography list
21	GET	/api/artists/:id/top-tracks	getTopTracksById	Mongo + Spotify	getArtistFromMongo	Spotify / MusicData	libs/data.ts → getArtistTopTracks; artist-overview-top-tracks.tsx	Top tracks
22	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
23	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
24	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
25	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
26	GET	/api/artists/:id/events	getEventByArtistId	Promoters events collection	Mongo events where artist in lineup	—	Event-artist cross views	Artist’s events
27	GET	/api/artists/:id/performance	getPerformanceById	Mongo analytics	getArtistFromMongo	—	Performance analytics	Performance tab
28	GET	/api/artists/:id/contacts	getContactsById	Mongo artists_v2.team	Aggregation on team.agencies / management peoples	—	Legacy contacts (prefer network team)	Contacts drawer
29	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
30	POST	/api/artists/:id/prediction-v2	getPredictionByIdV2	Mongo	getArtistFromMongo	Internal models	libs/data.ts	Prediction v2
31	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
32	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
33	POST	/api/artists	create (command)	Mongo legacy create	artists.command.js — still writes Mongo approval flow	—	libs/data.ts → createArtist; artists/add/page.tsx	Create artist (legacy) — prefer Artists module for new master
34	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
24	POST	/promoters/:id/shortlists/:shortlistId/artists	same	EDIT_OFFER	addArtistToShortlist	add-artist-to-shortlist-dialog.tsx
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	Mongo + MusicData
/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
/artists/add	/search/new, POST /api/artists	Spotify + Mongo legacy create
/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 / genres query filters on GET /api/artists	Not fully mapped to Artists upstream list params
POST /api/artists legacy Mongo create	Still writes Mongo; new master should use Artists
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

---

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