MobileApp-KisumAI (Kisum mobile app)
Related documentation: Kisum System · LoadBalancer KisumAI Worker · Chat-Kisum-MCP-Node · Frontend Promoters
Canonical implementation detail: repository MobileApp-KisumAI — start with APP_DESIGN.md (approved v1 design), then README.md and TODO.md (phase checklist).
Purpose
Section titled “Purpose”Passkeys and local app lock (2026-07-12). Mobile can register/manage a server passkey and use it for passwordless re-login when the refresh session is dead. Separately, an optional cold-start lock protects an existing local session using biometrics plus device-passcode fallback. Passkeys issue new Auth tokens; local biometrics do not. Both flags default off and disabled features do not render controls or lock the app. Enablement requires a new native build, verified kisum.io Apple/Android associations, all Android signing origins in Auth, and real-device QA.
The app includes the iOS Face ID usage permission and Expo local-authentication plugin. Passkey and app-lock failures distinguish cancellation, offline, unsupported hardware, revoked credentials, rate limits, and temporary Auth outages. Passkey management and app-lock controls live in Account → User profile, beside Change password; they are not a separate Account-menu destination or part of the general Settings screen. The association generator writes to the marketing site’s public/.well-known directory and prints the Android origins required by Auth; it must be run with confirmed production identifiers.
Android development-client compatibility. Native libraries are compiled into the development client and cannot be added by Metro. ./run-emulator-android.sh compares the current Expo Android native fingerprint with the last installed local build. A missing or changed fingerprint triggers expo run:android --no-bundler, records the successful build, and then starts Metro; a matching client uses Metro directly. This prevents stale clients from crashing on ReactNativePasskeys or ExpoLocalAuthentication after native security dependencies change.
iOS development-client compatibility. ./run-emulator-ios.sh applies the same protection per simulator UDID. It compares the current Expo iOS native fingerprint and the installed app-binary signature with the last successful build. A missing app or changed value triggers a Pod install plus expo run:ios --no-bundler; a matching client starts Metro directly. This prevents an older iPhone or iPad client from loading JavaScript that requires native passkey or local-authentication modules it does not contain.
Confirmed production identity is Apple Team 4MUC263F65, bundle/package app.kisum, Android SHA-256 19:A1:A2:BB:07:35:90:15:B0:1F:9C:7F:F7:38:4F:B2:F5:D8:DE:AB:16:F8:B4:CB:EE:38:15:F6:86:9F:E0:75, and Android WebAuthn origin android:apk-key-hash:GaGiuwc1kBWwH5x_9zhPsvXY3qsW-LTL7jgV9oaf4HU. Production HTTPS origins are www, app, auth, artists, and venues under kisum.io. Staging origins, live hosting, new native builds, and real-device/browser QA remain open.
Kisum is the paid AI chat mobile app for Android and iOS (React Native + Expo, TypeScript; package/bundle ID app.kisum). Main feature: AI chat against the Kisum AI gateway. Since v2 (2026-07-03) it is also the promoter workspace on the go: full artist profiles + analytics, Booking (marketplace, offers, requests, shortlists, confirmed, agencies), Venues (directory, marketplace + booking inquiries), read-only Events, Market Analysis charts, and KisumAI Research — alongside the v1 Festivals and News sections.
Access model: free download, Kisum account gate — only accounts whose org has access can use the chat (server-side decision; 401/403 shows a “no access” screen). No in-app billing in v1.
Billing screen (App Store compliance, 2026-07-12). profile/billing is platform-split: on iOS it is read-only (plan name + status only — no price, no manage link) to satisfy App Store Guideline 3.1.1 (no non-IAP purchase path). On Android it shows price + a “Manage billing on web” button that uses SSO handoff: the app mints a one-time code (Auth POST /auth/handoff/create) and opens app.kisum.io/api/auth/handoff?code=…, landing on web billing already-logged-in (code in URL, not the JWT). Falls back to the plain web URL if handoff is unavailable. See the Auth SSO-handoff note in Backend-Kisum-Auth.
APIs consumed
Section titled “APIs consumed”| API | Endpoint(s) | Headers |
|---|---|---|
| AI chat gateway | POST https://api.kisum.io/ai/chat {sessionId, message}; history GET/DELETE https://api.kisum.io/ai/sessions | x-auth: Bearer <jwt>, x-org |
| KisumAI Research copilot | POST {COPILOT_URL}/api/copilot {query, session_id} (prod https://dev-api-chat.kisum.dev) | x-auth: Bearer <jwt>, x-org |
| Backend-Kisum-Auth | POST /auth/login, POST /auth/refresh, GET /auth/me, PATCH /auth/me, PUT /auth/me/password, POST /auth/logout | Authorization: Bearer |
| Backend-Kisum-Promoters — catalog & content | GET /api/artists[/:id] (+ card-stats, stats, top-tracks, historical, demographics, top-countries, discography, bandsintown/events, trend, POST market-analysis), GET /api/festivals[/:id], GET /api/festivals/edition/:id, GET /api/news, GET /api/events[/:id] (+ overview, lineup), GET /api/rankings/* (Kworb/Billboard charts), GET /api/countries/all, dashboard routes | Authorization: Bearer, x-org |
| Backend-Kisum-Promoters — Artists network (booking) | GET /api/artists-network/marketplace/artist-availabilities, GET/POST /api/artists-network/booking-requests (+ /:id/withdraw), GET /api/artists-network/booking-offers (+ `/:id/accept | counter |
| Backend-Kisum-Promoters — Venues network | GET /api/venues (directory; filters: q, country, type, capacityMin, capacityMax, sort/sortType), GET /api/venues/type, GET /api/venues/marketplace/venues[/:id], GET /api/venues/spaces, GET /api/venues/booking-slots, GET /api/venues/availability, GET/POST /api/venues/bookings | Authorization: Bearer, x-org |
| Backend-Kisum-Finance (addon) | GET/POST /api/bills, PATCH /api/bills/:id, GET/POST /api/income, PATCH /api/income/:id, POST /api/upload, POST /api/files/ai, POST /api/upload/payment-slip, admin picker routes (/api/admin/business-units/by-company, vendor/customer search, tax/ledger/currencies, Xero bank accounts) | Authorization: Bearer, x-org via gateway https://api.kisum.io/finance |
Note: the app uses Promoters’ own /artists/* catalog routes for the artist directory (same as the web frontend); /artists-network/* is used for booking flows and the Team tab only (team/roster degrade gracefully to “no data” when a catalog artist is missing from the network). Every route mirrors one Frontend-Kisum-Promoters already calls — the app never gets its own backend routes. Finance mirrors Frontend-Kisum-Finance / Finance API contracts; no new Finance endpoints were added for mobile.
Festivals detail shape: GET /api/festivals/:id returns { festival, festivalEditions } under data (not a flat festival row). Mobile fetchFestival must read data.festival. Path :id accepts Mongo ObjectId, public uuid, or slug.
Profile write: Mobile PUT /api/users/profile and PUT /api/users/update-password go to Promoters BFF, which proxies Auth PATCH /auth/me and PUT /auth/me/password. Phone is split: phonePrefix (dial +XX from GET /api/countries/all → phone_prefix) + phoneNumber (national digits). Do not call Auth profile writes from the app directly. Do not hardcode dial codes.
Security rules: no internal API keys ship in the app — user tokens only (SecureStore); tokens are never logged; single-flight refresh with retry-once-on-401.
Data ownership
Section titled “Data ownership”- Chat history: synced from
GET /ai/sessionson the public gateway into device SQLite (Postgres onai-agent-chatis source of truth whenPOSTGRES_URIis set). Local SQLite is a cache; reinstall re-syncs from remote when logged in. - The app owns no platform data — Artists/Festivals/News are read-only views over Promoters-owned data.
- Edit & resend semantics (v1): editing a message truncates everything after it locally and continues under a fresh backend
sessionId— the backend AI memory starts clean after an edit (accepted limitation; a true edit would need gateway support).
App structure
Section titled “App structure”- Bottom tabs (unchanged): AI Chat · Artists · Dashboard (default landing tab) · Rankings (festivals) · News; Account opens from the profile icon and chat History remains modal-style.
- Account security: User profile groups password, passkey, and app-lock controls. The Account menu has no separate Security row.
- Side menu (v2) adds the workspace sections: Booking (marketplace + make offer/enquire, offers inbox with accept/counter/decline/cancel, requests with withdraw, shortlists, confirmed, agencies with roster/staff), Finance (Bills AP + Income AR when the org has the
financeaddon and the user has a finance role — seeMobileApp-KisumAI/docs/FINANCE-MOBILE.md), Venues (directory with the same Filter sheet as Promoters web — country, venue type, capacity min/max, name A–Z/Z–A; marketplace with spaces/slots/packages, an availability month calendar per space, and a booking-inquiry flow, my bookings), Events (read-only list + detail with ticket metrics and lineup; financials/taxes stay on the web app), Market Analysis (Kworb/Billboard ranked charts incl. Spotify/iTunes country charts), KisumAI Research (artist + country → copilot market research, with device-local history). - Artist detail has all six tabs: Overview, Team, Bio, Analytics (AI market analysis, platform reach, per-platform demographics, top countries, Google trends, streaming velocity, conversion funnel), Shows (Bandsintown), Discography. Overview Top Songs open Spotify via track
link/spotifyId(same as Promoters web). - Auth flow: native login screen → org auto-select (or picker when the user belongs to several companies) → chat.
- Active company (
x-org): stored in SecureStore; sidemenu Switch company updates it. On change, the app clears React Query cache (tenant-scoped Promoters data), resets the in-memory chat target, closes the sidemenu, and navigates to Dashboard — same contract as Promoters integration (x-orgis the only active-company input for tenant routes). Profile → Companies is for viewing org details, not switching session. - Offline: banner + send disabled; reading local history still works.
- Base URLs configured in
app.json→expo.extra(never hardcoded in code).
Visual design
Section titled “Visual design”The UI implements the “Analyst-Confident Precision” design system (in-repo design/DESIGN-light.md + design/DESIGN-dark.md; product register in PRODUCT.md): light #F9F9FF canvas, white 1px-bordered cards, purple brand (#8466AC), Manrope + Inter typography, chat with avatared bubbles and prompt suggestions, Festivals presented as a “Festival Leaderboard” (tab labeled Rankings).
Release (beta APK)
Section titled “Release (beta APK)”Betas ship as a signed .apk installed directly on devices (no Play Store). Built with EAS (preview profile, local build); the signing keystore lives on Expo’s servers (EAS project kisum-ai) and is reused for every build so updates install over old versions. The complete step-by-step recipe — including the known build errors and their fixes — is in the repo README.md → Release.
Status
Section titled “Status”- 2026-07-14: iOS simulator launcher now rebuilds stale clients per device; fresh iPad build verified with passkeys and local authentication linked and the app loading normally.
- 2026-07-13: Passkey and app-lock controls moved into Account → User profile beside Change password; duplicate/general Settings placement removed and Android emulator verified.
- 2026-07-13: Android development launcher now rebuilds stale native clients automatically; emulator build verified with passkeys and local authentication linked and the dashboard loading normally.
- 2026-07-10: Venue directory filters — Filter sheet matches Promoters web (country, type, capacity, name sort); Marketplace stays country-only.
- 2026-07-03 (b): v2.1 — venue availability calendar, KisumAI Research device-local history (
research_sessionsSQLite table), Spotify/iTunes country charts. - 2026-07-03: v2 built — webapp-parity sections (full artist tabs + analytics, Booking with write actions, Venues with booking inquiries, Events read-only, Market Analysis charts, KisumAI Research).
tscclean, 29 unit tests green. Pending device QA; follow-ups in the repoTODO.md(v2 section). - 2026-07-02: first beta APK built locally via EAS; build recipe documented in the repo README.
- 2026-07-02: v1 implemented (all phases; unit tests green; Android bundle exports) + full UI redesign to the analyst light theme. Pending: on-device manual QA, real-endpoint contract verification for the chat gateway (backend 500 under investigation).