Overview

Hatched gives a product a buddy — a companion that grows as its user does. Everything else on Hatched exists to feed the buddy: events go in, effects come out, a widget shows the result.

The whole picture in one paragraph

A user does something in your product (lesson_completed, checkout_succeeded). You send it as an event. The rule engine turns it into effects — skills level up, coins are earned, a badge might unlock, a streak ticks, the buddy moves closer to its next evolution stage. Users spend coins in the marketplace. Your backend gets webhooks when anything interesting happens.

The primitives

• Buddy & hatch — the avatar, born from an egg, growing through evolution stages.
• Skills — numeric dimensions like Grammar or Stamina that level up over time.
• Coins — the primary currency, earned from events, spent in the marketplace.
• Tokens — secondary currencies (gems, hearts, stars) for more specialised economies.
• Streaks — consistency counters that tick daily and reward habit.
• Badges — one-shot achievements that mark a specific moment.
• Paths — multi-step guided journeys (onboarding, learning modules, certification tracks) with steps and sub-steps that complete via events or manual marks.
• Marketplace — where users spend coins on items that show up in the widget.
• Leaderboard — competitive ranking with scoped visibility.
• Evolution — the long-horizon arc; the buddy changes appearance at milestones.
• Audiences — segmenting one customer into multiple user groups with separate rules.
• Config versions — immutable snapshots of the whole rule set, pinned per buddy.
• Rule engine — the deterministic pipeline that converts events into effects.
• Webhooks — signed HTTP callbacks that let your backend react to anything.

Motivational layer primitives

The Octalysis-scored surfaces that sit on top of the gamification primitives above. The Planner Radar scores how many of these you have active and how they balance across Yu-kai Chou's eight Core Drives.

• Mission Anchor — the 40-character tenant-authored rim that lives on every widget chrome. The CD1 (Epic Meaning) backbone of the workspace.
• Hatch Ceremony — the five-act ceremony every new member experiences once. Tenant-authored copy; the moment the workspace's narrative introduces itself.
• LEAGUES seasons — six-week sprints with cohort-scoped tiers, a Closing Ceremony, a Hall of Fame, and a Returning Champion path.
• Kudos taxonomy — tenant-defined recognition types (the assist metric). The CD5 (Social Influence) backbone.
• Founding Cohort Elitism — the first-N / first-percent identity group with a lifetime status badge.
• Planner Radar / Hat Bar / Brain Bar / Phase Coverage — the four admin diagnostic surfaces that score the workspace's motivational footprint live.

Design principles

• Template-first over free-form. Rule types are a fixed enum; we chose fewer knobs over infinite configurability.
• Publish before live. Config changes land on a draft, then get published as a new immutable version. Existing buddies stay on their pinned version.
• Canonical state in Hatched. Your product can keep a copy for UX, but Hatched owns the truth.
• Async by default. Image generation, webhook delivery and other slow paths run off a queue and expose an operation you can poll.

Where to next

• Getting started — create a buddy, send an event, embed a widget in ten minutes.
• SDK quickstart — the @hatched/sdk-js surface.
• Configure rules — tune the economy in the dashboard.
• Best practices — patterns for an integration that scales.