FLUX.
DEVELOPER PLATFORMPRIVATE BETA
FLUX ENGINEERING GUIDE · V0.1

Build the rewards layer for real nights out.

This is the technical source of truth for developing FLUX, connecting a ticketing partner, processing verified activity, and preparing the private beta for production.

SYSTEM STATUS
Member accountsIMPLEMENTED
Private event plansIMPLEMENTED
Rewards simulatorDEMO ONLY
Partner webhooksTO BUILD
Live redemptionTO BUILD
Last reviewed · September 23, 2026
Know the boundary.

The current rewards experience is a deterministic browser simulator with synthetic data. Production ticket activity, ledger writes, inventory, and redemption must run in trusted server-side transactions before launch.

01 / QUICKSTART

Run FLUX locally.

The application uses Node 22.13 or newer, pnpm, React 19, Vinext, and Supabase. Dependencies are locked for repeatable installs.

TERMINALFLUX / DEV
git clone <private-repository-url> flux
cd flux
git switch naomi-flux-design-1
pnpm install
pnpm dev
LOCAL REQUIREMENTS
  • Node.js ≥ 22.13
  • pnpm 11
  • Access to the private repository
  • Hosted Supabase access for schema work

Open http://localhost:3000. The landing page and simulator run locally; account flows use the configured hosted Supabase project.

02 / ARCHITECTURE

Keep trust on the server.

Ticketing remains with the partner. FLUX receives signed lifecycle activity, converts it into a standard event, and applies reward rules through an auditable transaction.

PartnerCheckout + scanner
IngressVerify + persist
AdapterNormalize activity
ProcessorApply rules once
LedgerOrders + points
MemberWallet + passport

Signed at ingress

Verify the raw body, timestamp, partner identity, and HMAC before acknowledging a webhook.

Durable before processing

Persist every accepted notification before background processing so retries cannot lose activity.

Idempotent by design

Enforce unique partner event and order keys in PostgreSQL, inside the same transaction as ledger writes.

03 / REPOSITORY

Find the source of truth.

Keep domain logic independent from interface code. UI should explain state; it should never invent ticket, attendance, point, or redemption state.

app/

Routes, global styling, legal and developer pages

components/account/

Landing, authentication, and member experience

components/demo-app.tsx

Synthetic rewards product walkthrough

lib/rewards/engine.ts

Deterministic reward and ledger rules

lib/rewards/types.ts

Domain contracts for the simulator

lib/supabase/

Browser client and private account queries

supabase/migrations/

Versioned PostgreSQL schema changes

supabase/templates/

Branded authentication email HTML

tests/engine.test.cjs

Acceptance-focused reward tests

04 / DATA PLATFORM

Supabase setup and safety.

Supabase currently supplies authentication, PostgreSQL, row-level security, and private member storage. Apply schema changes through reviewed migrations rather than dashboard-only edits.

CURRENT MEMBER TABLES
afterglow_profiles

Private member profile, onboarding, and versioned consent

afterglow_member_plans

Self-entered plans; never tickets or verified attendance

afterglow_attendance

Read-only member view of trusted attendance

afterglow_point_entries

Read-only member view of point movements

Database rules

  • Enable RLS on every member or partner table.
  • Grant the narrowest column and operation access.
  • Use auth.uid() for ownership policies.
  • Keep service-role credentials server-only.
  • Use server-generated timestamps for consent and audit records.
  • Make financial and reward mutations transactional.

Applying a schema change

  1. 01

    Create a migration with supabase migration new descriptive_name.

  2. 02

    Add constraints, indexes, RLS policies, grants, and safe backfills.

  3. 03

    Review the diff and test against a disposable or local database.

  4. 04

    Apply through the authorized Flux Supabase project and verify the resulting schema.

05 / IDENTITY

Authentication and consent.

Email/password uses PKCE sessions. Google and Apple buttons are present, but each provider must be configured in the hosted Supabase project before it becomes available.

EMAIL

Email and password

Keep confirmation enabled, install the branded email template, configure production SMTP, and test confirmation plus recovery end to end.

GOOGLE

Google OAuth

Create the provider credentials, add Supabase’s callback URL, enable Google under Authentication Providers, and validate new and returning users.

APPLE

Sign in with Apple

Configure the Apple Service ID, key, team ID, redirect domain, and Supabase provider settings. Plan for Apple’s private relay addresses.

06 / PARTNER API

Implement real ticketing activity.

The partner owns checkout, tickets, transfers, admission, and refunds. FLUX owns verified member attribution, status, points, rewards, redemption, and reconciliation.

Standard activity vocabulary

Every adapter converts partner-specific payloads into these canonical events.

purchase.completedticket.assignedticket.transferredattendance.checked_inorder.partially_refundedorder.refundedevent.canceled
PROPOSED ENDPOINTPOST /v1/partner-activity

Returns 202 Accepted after signature validation and durable inbox persistence. Processing happens after acknowledgement.

CANONICAL PAYLOADFLUX / DEV
{
  "id": "evt_01J...",
  "type": "attendance.checked_in",
  "occurred_at": "2026-09-22T03:42:10Z",
  "partner_id": "partner_boredmood",
  "order_id": "ord_8472",
  "event_id": "show_hou_0918",
  "ticket_id": "tkt_3190",
  "member_ref": "opaque_partner_member_ref"
}
REQUIRED HEADERSFLUX / DEV
X-Flux-Partner: partner_boredmood
X-Flux-Timestamp: 1789962130
X-Flux-Signature: v1=<HMAC_SHA256>
Idempotency-Key: evt_01J...
01

Verify

Validate signature and reject stale timestamps.

02

Persist

Store the exact payload in an append-only inbox.

03

Normalize

Map partner fields through a versioned adapter.

04

Resolve

Match event, order, ticket, and consented member.

05

Process

Lock affected records and apply one transaction.

06

Reconcile

Compare partner totals, exceptions, and ledger output.

07 / REWARD SYSTEM

Preserve the ledger, always.

The simulator documents intended behavior. Port these invariants to PostgreSQL transactions and server-side workers rather than calling the browser engine from production.

Integer economics

Store money in integer cents and points as integers. Define rounding explicitly.

Rate snapshots

Lock the applicable earning rate and campaign onto the order at purchase time.

Pending → available

Purchase points remain pending until the required verification event.

Compensating entries

Refunds and corrections append offsets; they do not rewrite history.

Atomic redemption

Reserve points and inventory in one transaction with a unique request key.

Member attribution

Purchaser receives spend; assigned attendee receives attendance and passport credit.

Negative balances

Show valid negative balances after post-spend refunds and block new redemption.

Replay safety

Partner notification, order, membership, and redemption keys must be unique.

08 / QUALITY

Prove behavior before shipping.

A production change is complete when its domain rules, data policy, build, and visible browser behavior all pass at the appropriate level.

VALIDATION COMMANDSFLUX / DEV
pnpm typecheck
pnpm exec oxlint app components lib
pnpm test
pnpm build
git diff --check

Domain Replay, refunds, assignments, caps, concurrency, and inventory.

Database Migrations, constraints, RLS, grants, transactions, and rollback.

Application Type checking, lint, build, routes, empty states, and errors.

Partner acceptance Signed fixtures, retry storms, out-of-order activity, and reconciliation.

09 / PRODUCTION

Launch when the system is ready.

Use this checklist for a pilot readiness review. Every item should have an owner, evidence, and rollback plan.

01

Identity

Email confirmation and recovery tested; Google and Apple validated; redirect allowlist reviewed.

02

Data

All migrations applied; RLS and grants tested with separate member and partner roles; backups restored in a drill.

03

Ticketing

Partner contract signed; webhook signatures, replay protection, retry behavior, and reconciliation accepted.

04

Rewards

Economics approved; ledger and redemption transactions load-tested; inventory and refund exceptions rehearsed.

05

Operations

Monitoring, alerting, dead-letter replay, support tools, incident ownership, and audit retention active.

06

Legal and privacy

Terms and privacy reviewed; consent evidence retained; deletion/export and marketing unsubscribe operational.

07

Security

Secrets rotated; dependency and application review complete; abuse limits and least privilege verified.

08

Release

Staging acceptance passed; production environment verified; rollback tested; pilot cohort and support window confirmed.