bOSS quickstart — bRRAIn Docs

Design your first closed-loop growth track in 10 minutes — KPI → Reward → Badge, referrals propagate into new cohorts, rewards auto-fire when thresholds cross.

bOSS quickstart

bOSS (bRRAIn Organic Sales Systems) is the admin workspace at admin.brrain.io/boss where you design closed-loop sales + growth systems on top of your bRRAIn instance. It's gated behind admin sign-in + TOTP step-up — non-admin users don't see it. This guide takes you from empty workspace to autonomous reward fulfillment in four steps.

Prerequisites

  • An admin account signed in at admin.brrain.io with TOTP enrolled
  • A Stripe Connect account (only required if you plan to pay cash rewards — onboard here)
  • A metric you want to reward — any countable event (purchases, referrals, lessons completed, etc.)

1. Create a system and a track

Open admin.brrain.io/boss and click Create new bOSS track. A track belongs to a system (the namespace); create one the first time.

Every track is a sequence of segments, and each segment is three cards: KPI → Reward → Badge.

┌──────────┐   ┌──────────┐   ┌──────────┐
│   KPI    │   │  Reward  │   │  Badge   │
│ Referrals│ → │ $50 cash │ → │ Founding │
│   ≥ 3    │   │          │   │ referrer │
└──────────┘   └──────────┘   └──────────┘

The bOSS UI walks you through picking a KPI from the Metric Registry (or creating one inline), choosing the reward type (cash via Stripe Connect Transfer, discount code, or custom webhook), and picking a badge.

2. Push events into the metric

Once your track is active, push events from your backend so bOSS can see KPI progress. One event per real-world action:

curl -X POST https://admin.brrain.io/boss/events \
  -H "Authorization: Bearer <your session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_id": 42,
    "recipient_user_id": 123,
    "cohort_id": 1,
    "numeric_value": 1,
    "dedupe_key": "order-98765"
  }'

The evaluator folds events into boss_metric_values every 60 seconds. The dedupe_key guarantees replays from your backend (common during retries) never double-count.

3. Close the loop with Claude

Before activating a track, click Review loop with Claude in the workspace header. bOSS sends the segment layout to Claude Sonnet 4.6 and returns one of:

  • closed — the final segment's reward includes a referral that feeds the first segment. Ready to activate.
  • open_with_suggestion — Claude proposes an edit that would close the loop. Accept or ignore.
  • broken — no path from the final segment back to entry. Activation is blocked until you add a closing referral.

4. Reward fires automatically

When a (segment, recipient, cohort) triple's metric value crosses the segment's threshold_value, the reward engine fires automatically:

  • cash → Stripe Transfer from the platform balance to the recipient's Connect account
  • discount → a single-use BOSS-XXXXX-XXXXX code is generated and persisted
  • custom → your configured webhook URL receives the reward payload, retried 3× with exponential backoff

All fulfillment is idempotent on (segment_id, recipient_user_id, cohort_id) — double-fires are safe.

5. Loop propagation

When the final segment's referral reward fires for a cohort, call:

curl -X POST https://admin.brrain.io/boss/tracks/{track_id}/propagate-loop \
  -H "Content-Type: application/json" \
  -d '{
    "referred_user_id": 456,
    "participant_user_id": 123
  }'

bOSS closes loop N, opens loop N+1 with a fresh cohort (containing the referred user), and snapshots the track definition so future edits don't rewrite prior entitlements.

What's next