Frontend Applications

Related documentation: Frontend Implementation · Frontend Admin · Frontend Venues · Frontend Artist

Purpose

This page is the runtime inventory of frontend applications that actually exist in the Kisum workspace.

It is not a target-only taxonomy.

For each app, the job here is to say:

• what repo exists
• what it currently does
• what is already implemented
• what is still pending or intentionally out of scope

Current application landscape

Kisum is not running as one frontend.

The active workspace currently includes:

Repo	Primary role	Status
Frontend-Kisum	main promoter/base product app	implemented, large legacy-heavy surface
Frontend-Kisum-Admin	platform staff control plane	implemented
Frontend-Kisum-Finance	finance workflow UI + vendor portal	implemented
Frontend-Kisum-Venues	venue-operator CRM	implemented
Frontend-Kisum-Artists	artist / agency operational app	implemented
Frontend-Kisum-Promoters	dedicated promoter persona app	implemented
Frontend-Kisum-Website	marketing site + checkout handoff	implemented
Fullstack-Kisum-Public	public guest forms BFF + UI (token/link flows)	implemented, deploys to Cloudflare Workers
Frontend-Kisum-Investors	investor briefing deck (static)	implemented
Frontend-Nextkt	ticket sales storefront prototype	implemented, frontend-only prototype
System-Kisum-Checkout	payment/signup app at checkout.kisum.io	implemented, but documented under backend systems because it is a fullstack BFF

1. Frontend-Kisum

Purpose

Main product app for the legacy/base promoter surface.

Current reality

• large Next.js App Router codebase
• still carries broad domain assumptions from the older monolithic product
• still owns major promoter-facing business UI
• not replaced by Frontend-Kisum-Promoters yet

Documentation note

This app remains important, but the workspace now also has a separate dedicated promoter app. Docs must not pretend the promoter persona is served by only one frontend.

2. Frontend-Kisum-Admin

Purpose

Platform staff control-plane UI.

Current reality

• React Router 7 + React 19 SPA
• browser talks to Backend-Kisum-Admin, not directly to Auth/Core module internals for control-plane work
• live route families already include dashboard, artists, contacts, admin-users, app-users, venues, settings, and artist-company request review

Detail page

• Frontend Admin

3. Frontend-Kisum-Finance

Purpose

Finance-domain product UI for internal finance teams plus the vendor portal.

Current reality

• separate Next.js app
• internal authenticated route tree for bills, invoices, vendors, users, companies, business units, Xero, errors, docs
• separate vendor route tree for vendor login and vendor bill submission/history
• still carries its own app-local auth/session/company context patterns

Implemented now

• internal finance dashboard and company/business-unit navigation
• bills, invoices, overdue bills, vendors, users, my-team, error review
• Xero callback and company Xero pages
• vendor login, vendor bills list, vendor bill detail, vendor bill create flow

Still not true

• this repo is not a source of backend finance truth
• this repo does not own schema, Prisma, Xero secrets, S3/SES credentials, or AI extraction credentials

4. Frontend-Kisum-Venues

Purpose

Venue-operator operations app at venues.kisum.io.

Current reality

• standalone Next.js 16 app
• live Auth bootstrap and venue module gating
• Phases 1–10 documented as shipped in repo TODO/changelog
• 2026-06-28 operator-side UI/UX normalization pass completed against the Kisum design-system shell/page rules

Implemented now

• venue settings + spaces CRUD
• availability blocks/calendar
• bookings lifecycle
• customer overlays
• deals and contracts
• deposits and finance visibility
• venue provisioning gate
• events
• operations checklists + templates
• reports
• canonical app shell/page chrome across dashboard, calendar, bookings, contracts, deposits, operations, and settings

Detail page

• Frontend Venues

5. Frontend-Kisum-Artists

Purpose

Artist / agency operational app at artists.kisum.io.

Current reality

• standalone Next.js 16 app
• hard no-agency gate is live
• FE-Phase 0–7 plan is closed in the repo TODO

Implemented now

• auth/bootstrap + app shell
• artists / companies / people / roster surfaces
• representation and claims
• availability
• booking requests, offers, bookings
• contract templates + booking-linked contracts
• touring + itinerary
• logistics approvals
• relationships and trust
• dashboard, activity, tasks
• finance visibility
• agency provisioning under Settings -> Agency

Detail page

• Frontend Artist

6. Frontend-Kisum-Promoters

Purpose

Dedicated promoter persona app that consumes Backend-Kisum-Promoters plus the Artists/Venues network BFFs.

Current reality

• Next.js app with active route groups under @main, public, and api
• repo README is stale and must not be treated as the runtime contract
• repo TODO is the accurate implementation tracker

Implemented now

• booking IA split (/booking/*) replacing the legacy /market/* write flows
• billing page under /profile/billing
• booking marketplace, requests, offers, confirmed bookings, relationships
• dedicated /booking/agencies
• venue marketplace and venue bookings outbox
• dashboard booking KPIs
• public event pages
• legacy promoter CRM surfaces like dashboard, vendors, workspace, events, AI/research, market analysis

Still pending / partial

• some Phase B/C follow-ups in the repo TODO, such as deeper venue-booking detail and marketplace artist tab
• legacy README refresh

7. Frontend-Kisum-Website

Purpose

Public marketing site.

Current reality

• Vite + React SPA
• direct browser-safe calls for pricing/geo/checkout handoff flows
• module landing pages, pricing, and account-creation step 1

Implemented now

• homepage and module marketing pages
• pricing page
• /create account/company form
• checkout bridge toward System-Kisum-Checkout
• waitlist modal

Important rule

This app is not the payment processor UI and not the identity backend. It hands off to Checkout for card/payment flow.

8. Fullstack-Kisum-Public

Purpose

Public guest experiences — token/link-based forms and reports without Kisum login.

Current reality

• Next.js 16 App Router fullstack app (pages + /api/* BFF route handlers)
• primary surface: guest offer enquiry at /form/offer/{token}
• server proxies to Backend-Kisum-Artists (public offer + geo) and Backend-Kisum-Venues (token-gated venue search)
• no Kisum Auth bootstrap; browser calls same-origin /api/* only
• CORS (2026-07-11): CORS_ORIGIN CSV allow-list applied by Edge middleware on /api/form/* and /api/geo/* (for cross-origin callers such as Website / persona apps). Same-origin guest pages do not need CORS. Keep middleware.ts (not proxy.ts) for Cloudflare OpenNext.

Deploy target (2026-06-30)

• Cloudflare Workers via @opennextjs/cloudflare + Wrangler
• Worker name: kisum-public (wrangler.jsonc)
• Build: npm run cf:build (or opennextjs-cloudflare build)
• Local Workers preview: npm run preview (requires .dev.vars from .dev.vars.example)
• Local Next.js dev: make dev / npm run dev uses .env only — not .dev.vars
• Deploy: npm run deploy (requires wrangler login + secrets)
• Secrets (never in repo): ARTISTS_INTERNAL_API_KEY, VENUE_INTERNAL_API_KEY via wrangler secret put
• Persona operator desks (Promoters, Artists): NEXT_KISUM_PUBLIC_URL in .env for guest share links back to this app
• Build-time + runtime env on this app: NEXT_PUBLIC_PUBLIC_APP_URL and upstream base URLs (Workers Builds / dashboard)

Important rule

• This is the canonical host for guest share links (NEXT_PUBLIC_PUBLIC_APP_URL on this app; persona desks set NEXT_KISUM_PUBLIC_URL pointing here), not persona apps.
• Do not expose internal API keys to the browser bundle.

Related platform doc

• Guest offer flow: Middle-agent workspace

9. Frontend-Kisum-Investors

Purpose

Investor briefing deck — single-page static presentation.

Current reality

• Next.js 14 App Router with static export (out/)
• Cloudflare Pages via wrangler.jsonc (kisum-investors)
• no backend integration

Implemented now

• full scroll deck (Hero → Contact)
• Framer Motion reveals, Recharts visuals
• copy centralized in src/content/deck.ts

Important rule

Static Pages only — no Auth, no x-org, no API routes. Do not deploy with OpenNext unless SSR/API is added later.

10. Frontend-Nextkt

Purpose

Ticket sales storefront prototype for event discovery and event-detail purchase UI.

Current reality

• standalone Next.js App Router app
• public front page at /
• static event detail pages at /events/[slug]
• no backend ticketing contract, checkout session contract, auth dependency, or persistence layer yet

Implemented now

• future events carousel
• featured events section
• event box grid
• compact event cards
• standing-only ticket detail design for GA-style events
• mapped venue detail design for GA, VIP, and table inventory

Still not true

• it is not the ticketing backend
• it does not own payment execution
• it does not define event inventory source of truth
• it does not integrate with Auth/Core/Promoters/Venues yet

Detail page

• Frontend Nextkt

Documentation rule

Frontend docs must now separate three states explicitly:

• implemented now
• not implemented yet
• target architecture

If a page only describes the target while a repo already ships real routes, that page is stale.

Local development — ports and env vars

Local persona frontends share local.kisum.io (add 127.0.0.1 local.kisum.io to /etc/hosts). Backends listen on 380x; browser apps on 300x.

App	Dev port	Public URL env	Server env (bind)	Backend API env
Frontend-Kisum-Admin	3003	VITE_PUBLIC_APP_URL	VITE_SERVER_HOST, VITE_SERVER_PORT	VITE_API_URL → http://local.kisum.io:3803/api/v1
Frontend-Kisum-Artists	3004	NEXT_PUBLIC_APP_URL	NEXT_SERVER_HOST, NEXT_SERVER_PORT	NEXT_PUBLIC_ARTISTS_API_BASE_URL → :3804
Frontend-Kisum-Finance	3005	NEXT_PUBLIC_APP_URL	NEXT_SERVER_HOST, NEXT_SERVER_PORT	NEXT_PUBLIC_API_BASE_URL → :3805/api
Frontend-Kisum-Promoters	3006	NEXT_PUBLIC_APP_URL	NEXT_SERVER_HOST, NEXT_SERVER_PORT	NEXT_PUBLIC_API_URL_NEW → :3806
Frontend-Kisum-Venues	3007	NEXT_PUBLIC_APP_URL	NEXT_SERVER_HOST, NEXT_SERVER_PORT	NEXT_PUBLIC_VENUE_API_BASE_URL → :3807

All apps use Auth at http://local.kisum.io:3801 (VITE_AUTH_URL or NEXT_PUBLIC_AUTH_BASE_URL).

Next.js apps run pnpm dev via scripts/next-dev.mjs, which reads NEXT_SERVER_* from .env. Admin runs pnpm dev:local; Vite reads VITE_SERVER_* from .env via vite.config.ts.

Local development — backend server-to-server (380x)

Machine routes use X-Internal-API-Key (or Bearer + JWKS for Auth browser validation). Local active values → 380x; production/staging commented on the line below.

Caller	Env var	Local target	Typical production (commented in .env)
Any persona backend	AUTH_BASE_URL	:3801	https://auth.kisum.io
Auth, Admin, persona BEs	CORE_INTERNAL_BASE_URL	:3802	https://api-v2-core.kisum.dev
Admin	ARTISTS_INTERNAL_BASE_URL	:3804	https://api-v2-artists.kisum.dev
Admin, Promoters	VENUE_INTERNAL_BASE_URL	:3807	https://api-v2-venues.kisum.dev
Finance, Promoters, Venues, Artists	FINANCE_INTERNAL_BASE_URL (+ FINANCE_INTERNAL_API_KEY Bearer on callers)	:3805	https://api-v2-finance.kisum.dev
Artists (profile BFF proxy)	PROMOTERS_BFF_BASE_URL	:3806	https://api-v2.kisum.dev
Promoters	MUSICDATA_BASE_URL	:3808	https://api.kisum.io/data
Promoters BFF GET /api/news upstream	MUSICDATA_INTERNAL_API_KEY + PUBLIC_FUNCTION_URL_NEWS	BFF env (not Frontend)	Lambda → api.kisum.io/data/news
Finance (legacy base integration)	KISUM_BASE_URL	:3806	https://api-v2.kisum.dev

Promoters news (browser): getNews() → customFetch('/api/news') → Promoters BFF (NEXT_PUBLIC_API_URL_NEW, e.g. :3806). BFF validates JWT/x-org, then calls PUBLIC_FUNCTION_URL_NEWS with MUSICDATA_INTERNAL_API_KEY. There is no separate Next /api/news route on the frontend.