From brief to platform

The vendor brief (June 2026) and the executive deck describe the full Guest Activation Platform across two horizons. The architecture settles the hard parts early: one identity, safe handoffs to partners, and a trustworthy points ledger. This page sets out what the brief asks for and what is still to decide.

Two horizons

timeline
  title Delivery horizons (from the brief)
  section Horizon 1 · Beach Club · H2 2026
    Identity : Member sign-in everywhere : Booking engine member login
    Engagement : Mobile app : Self check-in at the gate : Loyalty earn and redeem : Push via Insider CDP
    Money : FINNS credit top-up : Credit spend at all POS : Wristband pilot
  section Horizon 2 · Resort · H1 2027
    Stay : Digital key : Pre-arrival check-in : In-room ordering and requests
    Unify : Cross-venue loyalty : Resort-wide credit : Journey analytics

Scope

Capability (brief)	Notes
Guest registration and member profile	Keycloak accounts, synced into core
Single sign-on into the booking engine	Handoff codes from the app, SSO from the web, fresh sign-in to pay
Self check-in at the Beach Club gate	One-time QR, online gate, points on check-in
Points earning and redemption	Double-entry ledger; earn on check-in, bookings, partner mechanics, staff adjustments
Partner customer engagement inside the app	Widget protocol v1, Points API, sign-out propagation
Staff console	Member lookup, points adjustments, staff access
Tier structure, progression, downgrade	Tiers need a model in core, or in the engagement partner
Personalised rewards (birthday, milestones)	Partner-side mechanics; needs CDP data
Closed-loop FINNS credit (top-up, spend)	Needs a credit ledger, a payment gateway and POS tender
QR payment at POS	Pattern proven by the check-in QR
NFC wristband	Hardware, readers, pairing flow
Push notifications, Insider CDP	Replaces the app’s balance polling
Website member portal	The app’s web build covers part of it
Daylight PMS, NetSuite	Horizon 2 and finance
PDP Law / GDPR consent flows	Must precede any CDP data flow

Target landscape

flowchart TB
  classDef ours fill:#13686C,stroke:#0B4A4D,color:#ffffff
  classDef ext fill:#F3ECDF,stroke:#B9A88B,color:#12191B

  subgraph channels["Channels"]
    direction LR
    app["Guest app"]:::ours
    web["Website member portal"]:::ext
    be["Booking engine"]:::ext
    wifi["WiFi captive portal"]:::ext
  end

  subgraph backend["One backend"]
    direction LR
    id["Identity<br/>Keycloak"]:::ext
    prof["Member profile<br/>core"]:::ours
    loyalty["Loyalty engine<br/>points ledger · tiers"]:::ours
    credit["Credit engine<br/>closed-loop wallet"]:::ext
  end

  subgraph venue["Venue"]
    direction LR
    gate["Gates · NFC"]:::ext
    pos["Shiji POS"]:::ext
  end

  subgraph enterprise["Enterprise systems"]
    direction LR
    opera["Daylight PMS<br/>golden record"]:::ext
    cdp["Insider CDP<br/>email · push · WhatsApp"]:::ext
    ns["NetSuite<br/>breakage accounting"]:::ext
    pg["Payment gateway<br/>Airwallex"]:::ext
  end

  sota["Sota<br/>rewards, games"]:::ext

  channels --> backend
  venue --> backend
  sota --> loyalty
  credit --> pg
  backend <--> opera
  backend --> cdp
  credit --> ns

FINNS platform built and run by FINNS
Vendor or third party built or bought outside FINNS, to our contract

Open design decisions

Decision	Options and trade-offs
Stack alignment	The brief’s preference is NestJS, React Native and React; the current services use Quarkus (Java), Flutter and SvelteKit. The contracts (OIDC, REST, codes, ledger) are stack-independent, so this is a team and hiring decision more than an architectural one.
Credit ledger	Extend core with a second, money-grade ledger, or a separate wallet service. Either way it stays apart from points (different regulation, accounting and refund rules).
Tiers	Computed in core from the ledger and check-ins (rolling window), or owned by the engagement partner. Core owning “who” suggests core.
Booking cancellations	Claw points back on cancellation, or credit only after the visit. Needs a new booking API call either way.
Venues and multi-property	Core has no venue model; Horizon 2 (Resort, cross-venue loyalty) needs one.
Gate production model	Per-device credentials, enrolment, zone rules, offline signed passes (`FINNS2:`), turnstile and NFC hardware.
Partner credentials	Static bearer tokens at first; per-partner OAuth client credentials or mTLS for production, with rotation.
Push channel	Insider SDK, or FCM/APNs directly, to replace the app’s balance polling.
Scale	~150,000 app users in year one: size Postgres, run Keycloak as a cluster, add metrics and tracing.
Environments	Only test exists. Production needs its own hosts, secrets, Keycloak realm or instance, and partner credentials.

Internal and confidential. Share partner sections only as partner builds (pnpm build:partner).