Skip to main content

​
Summary

Designed the event backbone for a modular onboarding assistant that works across every product in the ecosystem — 20 GitHub organisations, 11 active stack repositories. The assistant is not just a walkthrough tool; it is a data-driven marketing engine controlled by two tunable parameters that an AI system optimizes autonomously.

​
Business impact

​
One onboarding system, every product

Instead of building separate onboarding flows for each application (choco-hq, sparki-tools mobile apps, smo1-io URL shortener, v01t-io server, etc.), a single event-driven assistant adapts to whichever product a user is entering. The same underlying system handles web, mobile, API, and CLI onboarding. Reduces development cost per product from weeks to configuration.

​
Two dials that control everything

push_oompa_clicks — Controls how aggressively the assistant presents paid opportunities. At low values, onboarding is purely helpful. At high values, every touchpoint includes a conversion prompt. The AI experiment engine (Kiln) discovers the right pressure level per audience segment automatically. drive_choco_brand — Controls how much Wonka/Chocomel factory mythology appears in the onboarding experience. At low values, messaging is functional. At high values, the factory narrative wraps every interaction — “The Nut-Sorting Room evaluated your repository”, scarcity counters for Golden Tickets, personalised Wonka Letters. These parameters combine into campaign phases (cold_open, warm_up, convert, retain) that the system A/B tests continuously. The result: marketing optimization at a level and speed that manual campaign management cannot achieve.

​
Monetization is explicit, not afterthought

The architecture models the full membership lifecycle: free trial, short-term membership, long-term membership, cross-product bundles, and Golden Ticket qualification. Discount application, tier enforcement, and Polar payment integration are all event-driven — when someone converts, every downstream system (billing, analytics, CRM, social announcements) reacts automatically.

​
Golden Ticket integration

The onboarding assistant is aware of the Golden Ticket protocol (SRS-002). When a user qualifies through the choco verify mechanic, the assistant can present the ticket with configurable ceremony — from a simple notification (low drive_choco_brand) to a full factory-mythology experience (high drive_choco_brand). Ticket issuance events propagate to social campaign machinery for automated POSTIE announcements.

​
Operational takeaways

  1. XML event catalogue ready for implementation in choco-hq/architecture/events/ — defines 38 events across 7 domains with full stream specs, handoff contracts, and observability requirements
  2. 11 cross-repo handoff contracts need implementing — each specifies source, target, trigger event, payload schema, SLA, and rollback strategy
  3. NextStep (enszrlu/NextStep) is the tour engine — needs binding to the event system so tour steps emit onboarding lifecycle events
  4. Polar SDK integration required for tier conversion events — the Go SDK (polar.sh/docs/integrate/sdk/golang) handles payment webhooks that feed back into the onboarding assistant state
  5. Kiln experiment bridge treats each onboarding configuration as a bandit arm — no manual A/B test setup needed, the system discovers optimal flows autonomously

​
What this means long term

The configurable parameter system means every campaign, product launch, or seasonal promotion is a matter of adjusting two floats and letting the experiment engine converge. The humans set the creative direction and brand guardrails. The machine finds the optimal execution path at a granularity no manual process can match. See also: Technical architecture detail