Promoters Module Backend

Related documentation: Backend Modules · Promoters Architecture · Promoters API · Promoters Integration · Data ownership · Redis GET response cache

Promoters can call Artists, Venues, and MusicData with Auth-issued X-Service-Token credentials behind S2S_TOKENS_ENABLED; static keys remain the rollout fallback. See service-to-service authentication.

Ops note — /health request logging

GET /health is public liveness ({"status":"ok"}). Console request timing (same pattern as Finance) runs before that route so load-balancer and Docker probes appear in container logs as GET /health - Nms.

Geo reference data (countries / regions) — Artists SoT

Since 2026-08-06, Promoters /api/countries* and /api/regions* are BFF adapters to Backend-Kisum-Artists Postgres geo (/api/v1/countries, nested states/cities, regions/subregions). They do not query Mongo countries / regions / cities. Requires ARTISTS_INTERNAL_BASE_URL + ARTISTS_INTERNAL_API_KEY. Path shapes stay the same for existing frontends. Responses keep the legacy nested flag: { code, unicode, name, emoji } shape (from Artists flagEmoji etc.) so Promoters UI that reads country.flag.emoji does not crash. Booking also uses /api/artists-network/geo/* (unchanged).

Overview

Data ownership changed on 2026-07-30. The events domain runs on PostgreSQL (promoters_db), not MongoDB. events, event_groups, event_incomes, event_expenses, event_expense_logs, event_taxes, event_terms, event_payments, event_offers, expense_categories, vendor_events and transactions are Postgres tables reached through Prisma; zero Mongoose event models remain. companies, vendors, users, tasks, approvals, artists_v2 and the chat collections are still MongoDB.

int32 id is the only event identifier — browser, internal APIs and the promoter_event_id that Venues and Artists persist. A UUID or a legacy Mongo ObjectId resolves to 404. publicEventId and promoterEventId remain in responses as aliases of id, and are numbers.

Ticket sales were rebuilt (Phase 8): 13 tables covering inventory, immutable sale facts, refunds as first-class adjustments, snapshot→delta normalisation, evidence authority and a provisional daily feed to Finance. Settlement belongs exclusively to the Finance module. See Backend-Kisum-Promoters/docs/TICKET_SALES_ARCHITECTURE.md.

Local Prisma migrations (Makefile)

Same command names as Auth/Core/Finance; Promoters uses Prisma (not Go sqlmigrate):

Target	Behavior
make migrate-status	prisma migrate status
make migrate-up	prisma migrate deploy (additive, non-destructive)
make migrate-down	Refuses — Prisma has no automatic rollback; undo with a new forward migration + migrate-up.

Never use prisma migrate reset / force-reset for routine local work. DDL needs DATABASE_URL_DIRECT (not the PgBouncer pool URL).

This page documents the backend currently known in code/repo terms as Backend-Kisum, but presented in the platform module taxonomy as the Promoters module backend.

Important distinction:

• the repo/service still contains broader legacy/shared business behavior
• in the current product/module taxonomy, this backend is represented as the Promoters module

That is why the docs now place it under Modules - Backend and use 2-3-* numbering instead of the older 2-4-* Base numbering.

What this backend currently is

Implemented now:

• a large shared business backend
• still a live runtime, not a deprecated placeholder
• still carrying many promoter-facing business flows and shared domain workflows
• integrated with Auth/Core-era access patterns, though still containing migration-era legacy behavior

In product terms, it is the backend most closely aligned with the Promoters-facing module/application surface.

What this page set covers

Use the pages in this order:

1. this overview page
2. Promoters Architecture
3. Promoters API
4. Promoters Integration

Why the naming changed

Historically, these docs were written under Base Backend.

That is no longer the right platform-facing label because:

• Base is now treated as a module-facing product area
• the current module taxonomy uses Promoters
• this doc set belongs under the module section with the other business modules

The old repo/runtime naming still appears in code and older prose, but the docs navigation should reflect the current module identity.

Summary

Treat this backend doc set as:

• runtime truth for the existing Backend-Kisum business backend
• platform-facing documentation for the Promoters module backend

Where older pages still use the word Base, read that as historical/runtime naming rather than the preferred current module label.

Promoters directory feed (2026-07-15)

This service aggregates a read-only promoters directory feed (GET /internal/directory/promoters*) so Backend-Kisum-Artists can browse Kisum promoter tenants from the Artists app — the platform’s first cross-tenant data disclosure. See Promoters API §6a and Data ownership.

Offer event names + show times (2026-07-16)

The marketplace offer orchestrator (booking/event-link-orchestrator.js) guarantees every offersheet show carries an eventName before the offer reaches Artists: create-on-submit events use the typed name (fallback proposedEventTitle → eventTitle → derived), and linked existing events have their Mongo title written back onto the show row. Created events honor the new per-show time (HH:MM; default 20:00, end = start + 3h). Shows are single-day platform-wide — the wizard no longer has an end date.