@soulcraft/kits 1.0.0

package/kits/loyalty-program/kit.json

@@ -0,0 +1,323 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "loyalty-program",
+  "type": "soulcraft",
+  "role": "extension",
+  "status": "released",
+  "name": "Loyalty Program",
+  "description": "Points-based loyalty program with tiers, rewards, and redemption tracking",
+  "longDescription": "A composable loyalty program extension for any Venue kit. Adds points earning on purchases, configurable tier thresholds (Bronze, Silver, Gold, Platinum), a reward catalog, and complete redemption tracking. Fully integrates with the POS and booking flows of the parent kit — every transaction becomes a loyalty event. Brainy tracks the loyalty graph so you can see which rewards are driving repeat visits and which tiers are most valuable to your business.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "⭐",
+  "tags": [
+    "loyalty",
+    "rewards",
+    "points",
+    "retention",
+    "extension",
+    "tiers",
+    "repeat customers"
+  ],
+  "requires": [],
+  "shared": {
+    "industry": "retail-hospitality",
+    "category": "business",
+    "glossary": {
+      "points": "The currency of the loyalty program — earned on purchases and redeemed against rewards. Always stored as integers.",
+      "tier": "A loyalty level (Bronze, Silver, Gold, Platinum) that a member achieves by accumulating a threshold number of points, unlocking enhanced earn rates or exclusive rewards.",
+      "earning rule": "A configuration that defines how many points a customer earns per dollar spent, per visit, or per specific action.",
+      "redemption": "The act of exchanging accumulated points for a reward — a discount, free item, or experience upgrade.",
+      "point expiry": "A policy that voids points that have not been used within a defined time window, creating urgency for repeat visits.",
+      "lifetime value uplift": "The measurable increase in average spend or visit frequency attributable to loyalty program membership."
+    },
+    "aiExpertise": [
+      "loyalty program design and tier mechanics",
+      "customer retention strategy and repeat visit drivers",
+      "earning rule configuration and point economics",
+      "reward catalog design and redemption psychology",
+      "point expiry policies and their retention effects",
+      "loyalty program analytics and LTV measurement"
+    ],
+    "dataModelHints": [
+      "loyalty_account",
+      "loyalty_transaction",
+      "reward",
+      "tier"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "loyalty_account",
+          "type": "Person",
+          "description": "A customer loyalty account storing current point balance, lifetime points earned, current tier, and tier expiry date. Extends the parent kit's customer entity.",
+          "products": {
+            "workshop": {
+              "view": "stats",
+              "icon": "⭐"
+            },
+            "venue": {
+              "mapsTo": "LoyaltyAccountMeta",
+              "pos": false
+            },
+            "academy": {
+              "mapsTo": "learner",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "loyalty_transaction",
+          "type": "Measurement",
+          "description": "A single loyalty points event — earn, redeem, adjust, or expire. Always linked to both the loyalty account and the triggering booking or purchase transaction.",
+          "products": {
+            "workshop": {
+              "view": "timeline",
+              "icon": "📊"
+            },
+            "venue": {
+              "mapsTo": "LoyaltyTransactionMeta",
+              "pos": false
+            },
+            "academy": {
+              "mapsTo": "practice-session",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "reward",
+          "type": "Thing",
+          "description": "A redeemable reward in the catalog — a free item, discount, experience upgrade, or exclusive access — with a points cost and eligibility tier.",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🎁"
+            },
+            "academy": {
+              "mapsTo": "skill-unit",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "tier",
+          "type": "Concept",
+          "description": "A loyalty tier definition — name, minimum lifetime points threshold, earn rate multiplier, and the exclusive rewards unlocked at this level.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "🏆"
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "customer",
+          "to": "loyalty_transaction",
+          "verb": "Creates",
+          "description": "Customer earns or redeems points via a loyalty transaction triggered by a purchase or eligible action."
+        },
+        {
+          "from": "loyalty_transaction",
+          "to": "loyalty_account",
+          "verb": "Credits",
+          "description": "Loyalty transaction updates the point balance and lifetime total on the linked account."
+        },
+        {
+          "from": "loyalty_account",
+          "to": "reward",
+          "verb": "Redeems",
+          "description": "Customer uses accumulated points to claim a reward from the catalog."
+        },
+        {
+          "from": "loyalty_account",
+          "to": "tier",
+          "verb": "References",
+          "description": "Account is currently assigned to a tier based on lifetime points earned."
+        },
+        {
+          "from": "reward",
+          "to": "tier",
+          "verb": "References",
+          "description": "Reward specifies the minimum tier required to redeem it."
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Configure tiers",
+        "prompt": "Help me set up Bronze, Silver, Gold, and Platinum tiers with thresholds and earn rate multipliers."
+      },
+      {
+        "label": "Design a reward catalog",
+        "prompt": "Help me build a reward catalog with items at different points costs across tier levels."
+      },
+      {
+        "label": "Set earning rules",
+        "prompt": "Configure how many points customers earn per dollar spent and per visit."
+      },
+      {
+        "label": "Analyse retention impact",
+        "prompt": "Show me loyalty member retention versus non-member repeat visit rates."
+      },
+      {
+        "label": "Review redemption patterns",
+        "prompt": "Which rewards are being redeemed most often, and are they driving the repeat visits we want?"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "customer-retention",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Design a loyalty tier structure with thresholds and earn rate multipliers that incentivise progression",
+      "Configure earning rules that balance customer value with program sustainability",
+      "Build a reward catalog with items at varied redemption costs that motivate continued engagement",
+      "Analyse loyalty transaction data to measure program ROI and repeat visit uplift",
+      "Apply point expiry and re-engagement strategies to reduce dormant member churn"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "loyalty-designer"
+  },
+  "workshop": {
+    "aiPersona": {
+      "role": "You are a customer retention specialist helping businesses design loyalty programs that make members feel genuinely valued and keep them coming back. You balance the psychology of rewards with the economics of program sustainability.",
+      "expertise": [
+        "loyalty program design and tier mechanics",
+        "earning rule configuration and point economics",
+        "reward catalog design and redemption psychology",
+        "customer retention strategy and LTV measurement",
+        "point expiry policies and re-engagement tactics",
+        "loyalty analytics and cohort analysis"
+      ],
+      "tone": "collaborator",
+      "avoidances": [
+        "Don't design a program where the average customer can never realistically earn a reward — that breeds disengagement",
+        "Don't set earn rates so high that the program is loss-making — model the economics before launching",
+        "Don't make redemption complicated — every extra step between points and reward reduces follow-through"
+      ]
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "customer earns points on a purchase",
+          "loyalty tier threshold mentioned",
+          "reward or redemption event recorded",
+          "point expiry or adjustment applied",
+          "earning rule defined or changed"
+        ],
+        "typeMapping": {
+          "loyalty account": "person",
+          "points balance": "measurement",
+          "loyalty transaction": "measurement",
+          "reward": "thing",
+          "tier": "concept",
+          "earning rule": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "customer",
+          "to": "loyalty_transaction",
+          "verb": "Creates",
+          "description": "Customer action triggers a points event"
+        },
+        {
+          "from": "loyalty_transaction",
+          "to": "loyalty_account",
+          "verb": "Credits",
+          "description": "Points event updates account balance"
+        },
+        {
+          "from": "loyalty_account",
+          "to": "reward",
+          "verb": "Redeems",
+          "description": "Member claims a reward from the catalog"
+        }
+      ],
+      "rules": [
+        "Every loyalty transaction must link to both the account and the triggering purchase",
+        "Points are always stored as integers — never use floats",
+        "Tier assignments are computed from lifetime points, not current balance",
+        "Reward redemptions must check tier eligibility before applying"
+      ]
+    },
+    "qualityGates": {
+      "projectChecks": [
+        "At least two tiers are configured with distinct thresholds and earn rates",
+        "Earning rules are defined for purchase events",
+        "At least three rewards exist in the catalog at different points costs",
+        "A loyalty transaction correctly updates the account balance",
+        "Tier upgrade is triggered when lifetime points cross a threshold"
+      ]
+    },
+    "publishConfig": {
+      "contentType": "document",
+      "publishable": true
+    },
+    "remoteWorkspace": {
+      "connectedWorkbenches": [
+        {
+          "name": "Member Accounts",
+          "view": "stats",
+          "entityTypes": [
+            "loyalty_account"
+          ],
+          "description": "Points balances, tier distribution, and member status across the program"
+        },
+        {
+          "name": "Reward Catalog",
+          "view": "gallery",
+          "entityTypes": [
+            "reward"
+          ],
+          "description": "Browse and manage redeemable rewards with points costs and tier requirements"
+        },
+        {
+          "name": "Transaction Log",
+          "view": "timeline",
+          "entityTypes": [
+            "loyalty_transaction"
+          ],
+          "description": "Full timeline of earn, redeem, adjust, and expire events"
+        },
+        {
+          "name": "Tier Configuration",
+          "view": "board",
+          "entityTypes": [
+            "tier"
+          ],
+          "description": "Configure tier thresholds, earn multipliers, and exclusive rewards"
+        }
+      ]
+    }
+  },
+  "venue": {
+    "features": {
+      "loyalty": true
+    },
+    "stations": [
+      {
+        "id": "loyalty",
+        "label": "Loyalty Program",
+        "route": "/api/manage/loyalty",
+        "icon": "⭐",
+        "roles": [
+          "manager",
+          "owner"
+        ],
+        "scope": "kit",
+        "context": "both"
+      }
+    ]
+  }
+}