@soulcraft/kits 1.0.0

package/src/kits/franchise-ops.ts

@@ -0,0 +1,345 @@
+/**
+ * @module @soulcraft/kits/kits/franchise-ops
+ * @description Multi-location operations with comparative analytics and location-specific settings
+ *
+ * Generated from: kits/franchise-ops/kit.json
+ * Do not edit this file directly — edit the source kit.json and re-run `bun run build:kits`.
+ */
+
+import type { SoulcraftKitConfig } from '@soulcraft/kit-schema';
+
+/**
+ * Franchise Operations kit configuration.
+ *
+ * @description Multi-location operations with comparative analytics and location-specific settings
+ * @see {@link SoulcraftKitConfig}
+ */
+const franchiseOps: SoulcraftKitConfig = {
+	"$schema": "https://soulcraft.com/schemas/kit/v2.json",
+	"id": "franchise-ops",
+	"name": "Franchise Operations",
+	"description": "Multi-location operations with comparative analytics and location-specific settings",
+	"version": "1.0.0",
+	"author": {
+		"name": "Soulcraft Labs",
+		"email": "kits@soulcraft.com",
+		"url": "https://soulcraft.com"
+	},
+	"status": "released",
+	"icon": "🏢",
+	"longDescription": "A composable franchise operations extension that adds multi-location management to any Venue kit. Enables location-to-location revenue comparisons, shared inventory templates, standardised pricing across locations, and franchise owner reporting dashboards. Each location remains independently operated with its own staff and data, while the franchise layer provides the consolidated view that owners and operators need to spot outliers, share best practices, and grow the network.",
+	"tags": [
+		"franchise",
+		"multi-location",
+		"analytics",
+		"operations",
+		"extension",
+		"reporting",
+		"standardisation"
+	],
+	"role": "extension",
+	"requires": [],
+	"type": "soulcraft",
+	"shared": {
+		"industry": "franchise-management",
+		"category": "business",
+		"glossary": {
+			"franchisee": "An operator who runs one or more locations under the franchisor's brand and systems, typically paying a royalty on revenue.",
+			"franchisor": "The brand owner who grants franchisees the right to operate under their systems, standards, and trademark.",
+			"royalty": "A percentage of gross revenue paid by the franchisee to the franchisor in exchange for brand rights, systems, and ongoing support.",
+			"comp store sales": "Comparable store sales — revenue for locations open for more than one year, used to measure organic growth independent of new openings.",
+			"location scorecard": "A standardised performance summary comparing a location's KPIs against network averages and top-quartile benchmarks.",
+			"compliance audit": "A periodic review confirming that a franchisee location meets the brand's operational, safety, and presentation standards."
+		},
+		"aiExpertise": [
+			"multi-location franchise operations",
+			"comparative analytics and benchmarking",
+			"standardisation across locations",
+			"franchise agreement and royalty structures",
+			"location performance diagnostics",
+			"network expansion planning",
+			"operations manual and compliance management"
+		],
+		"dataModelHints": [
+			"franchise_location",
+			"franchise_report",
+			"location_scorecard",
+			"network_benchmark"
+		],
+		"suggestions": [
+			{
+				"label": "Compare locations",
+				"prompt": "Show me a revenue comparison across all franchise locations for the past 30 days."
+			},
+			{
+				"label": "Identify top performer",
+				"prompt": "Which location is performing best this quarter, and what can others learn from it?"
+			},
+			{
+				"label": "Flag underperformers",
+				"prompt": "Flag any locations tracking below the network average on fill rate or revenue per seat."
+			},
+			{
+				"label": "Standardise pricing",
+				"prompt": "Help me review and standardise pricing across all locations for consistency."
+			},
+			{
+				"label": "Generate a franchise report",
+				"prompt": "Generate a monthly franchise network report with revenue, bookings, and key KPIs."
+			},
+			{
+				"label": "Plan a new location",
+				"prompt": "Help me model the revenue potential for a new franchise location based on network performance."
+			}
+		],
+		"dataModel": {
+			"entities": [
+				{
+					"domain": "franchise_location",
+					"type": "Location",
+					"description": "A single franchise location with its own address, franchisee owner, operating hours, and Stripe account. Extends the parent kit's Location entity with franchise-specific metadata.",
+					"products": {
+						"workshop": {
+							"view": "graph",
+							"icon": "📍"
+						},
+						"venue": {
+							"mapsTo": "LocationMeta",
+							"pos": false
+						},
+						"academy": {
+							"mapsTo": "knowledge-unit",
+							"assessable": true
+						}
+					}
+				},
+				{
+					"domain": "franchise_report",
+					"type": "Measurement",
+					"description": "A generated performance report aggregating revenue, bookings, and operational metrics across some or all franchise locations for a specified date range.",
+					"products": {
+						"workshop": {
+							"view": "stats",
+							"icon": "📊"
+						},
+						"academy": {
+							"mapsTo": "learning-artifact",
+							"assessable": true
+						}
+					}
+				},
+				{
+					"domain": "location_scorecard",
+					"type": "Measurement",
+					"description": "A standardised KPI snapshot for a single location — revenue per seat, booking fill rate, average transaction value — benchmarked against the network average.",
+					"products": {
+						"workshop": {
+							"view": "stats",
+							"icon": "🏅"
+						}
+					}
+				},
+				{
+					"domain": "network_benchmark",
+					"type": "Concept",
+					"description": "A computed network-wide average or percentile for a specific KPI, used to contextualise individual location scorecards.",
+					"products": {
+						"workshop": {
+							"view": "stats",
+							"icon": "📈"
+						}
+					}
+				}
+			],
+			"relationships": [
+				{
+					"from": "franchise_location",
+					"to": "booking",
+					"verb": "Contains",
+					"description": "Franchise location is home to all bookings and transactions made at that address."
+				},
+				{
+					"from": "franchise_report",
+					"to": "transaction",
+					"verb": "Aggregates",
+					"description": "Franchise report summarises transaction revenue across the selected locations and date window."
+				},
+				{
+					"from": "location_scorecard",
+					"to": "franchise_location",
+					"verb": "References",
+					"description": "Scorecard is computed for and linked to a specific franchise location."
+				},
+				{
+					"from": "location_scorecard",
+					"to": "network_benchmark",
+					"verb": "References",
+					"description": "Scorecard compares the location's metrics against the applicable network benchmarks."
+				}
+			]
+		}
+	},
+	"venue": {
+		"experienceTypes": [],
+		"features": {
+			"franchise": true
+		},
+		"stations": [
+			{
+				"id": "franchise",
+				"label": "Franchise Dashboard",
+				"route": "/api/manage/franchise",
+				"icon": "🏢",
+				"roles": [
+					"owner"
+				],
+				"scope": "kit",
+				"context": "both"
+			},
+			{
+				"id": "multi-location",
+				"label": "All Locations",
+				"route": "/api/manage/locations",
+				"icon": "📍",
+				"roles": [
+					"owner"
+				],
+				"scope": "kit",
+				"context": "both"
+			}
+		]
+	},
+	"workshop": {
+		"graphGuidance": {
+			"conceptCreation": {
+				"triggers": [
+					"new franchise location opened or onboarded",
+					"franchise report generated or requested",
+					"location scorecard reviewed or benchmarked",
+					"network-wide KPI or benchmark discussed",
+					"franchisee performance issue raised"
+				],
+				"typeMapping": {
+					"franchise location": "location",
+					"location": "location",
+					"franchise report": "measurement",
+					"scorecard": "measurement",
+					"benchmark": "concept",
+					"KPI": "concept"
+				}
+			},
+			"relationshipPatterns": [
+				{
+					"from": "franchise_location",
+					"to": "booking",
+					"verb": "Contains",
+					"description": "Location owns its bookings and revenue"
+				},
+				{
+					"from": "franchise_report",
+					"to": "transaction",
+					"verb": "Aggregates",
+					"description": "Report aggregates transaction data"
+				},
+				{
+					"from": "location_scorecard",
+					"to": "franchise_location",
+					"verb": "References",
+					"description": "Scorecard is for a specific location"
+				}
+			],
+			"rules": [
+				"Every franchise location must have a unique identifier used consistently across all reports",
+				"Franchise reports should always specify the date range they cover",
+				"Network benchmarks are updated after each reporting cycle — never use stale benchmarks",
+				"Location scorecards must link to the benchmarks they compare against"
+			]
+		},
+		"qualityGates": {
+			"projectChecks": [
+				"At least two franchise locations are configured with distinct addresses",
+				"A franchise report is generated covering all locations for a defined date range",
+				"Location scorecards show per-location KPIs benchmarked against the network average",
+				"Revenue comparison across locations is functional",
+				"Standardised pricing or inventory template is applied across locations"
+			]
+		},
+		"publishConfig": {
+			"contentType": "document",
+			"publishable": true
+		},
+		"aiPersona": {
+			"role": "You are a franchise operations consultant helping multi-location business owners understand network performance, standardise operations, and identify growth opportunities. You think in benchmarks, scorecards, and comp store comparisons.",
+			"expertise": [
+				"multi-location franchise operations and management",
+				"comparative performance analytics and benchmarking",
+				"franchise standardisation and compliance",
+				"location scorecard design and KPI selection",
+				"network expansion modelling",
+				"royalty structure and franchise agreement economics"
+			],
+			"tone": "collaborator",
+			"avoidances": [
+				"Don't compare locations in isolation — always benchmark against the network average and top quartile",
+				"Don't recommend operational changes to a location without looking at its scorecard history first",
+				"Don't conflate individual location ownership with network strategy — they require different conversations"
+			]
+		},
+		"remoteWorkspace": {
+			"connectedWorkbenches": [
+				{
+					"name": "Location Comparison",
+					"view": "stats",
+					"entityTypes": [
+						"franchise_location",
+						"location_scorecard"
+					],
+					"description": "Side-by-side KPI comparison across all franchise locations"
+				},
+				{
+					"name": "Cross-Location Revenue",
+					"view": "timeline",
+					"entityTypes": [
+						"franchise_report"
+					],
+					"description": "Revenue trends by location over time with network average overlay"
+				},
+				{
+					"name": "Franchise Health Dashboard",
+					"view": "board",
+					"entityTypes": [
+						"franchise_location",
+						"network_benchmark"
+					],
+					"description": "At-a-glance health status for each location — green, amber, or red"
+				},
+				{
+					"name": "Network Graph",
+					"view": "graph",
+					"entityTypes": [
+						"franchise_location"
+					],
+					"description": "Geographic and relational map of all locations in the network"
+				}
+			]
+		}
+	},
+	"academy": {
+		"skillPath": "franchise-management",
+		"level": "advanced",
+		"learningObjectives": [
+			"Configure and manage a multi-location franchise network with per-location settings and shared brand standards",
+			"Generate and interpret comparative performance reports across franchise locations",
+			"Identify outlier locations — both overperformers and underperformers — and design interventions",
+			"Apply standardised pricing, inventory templates, and operational checklists across the network",
+			"Model network expansion economics using comp store data and location scorecards"
+		],
+		"assessmentTypes": [
+			"portfolio",
+			"peer-review"
+		],
+		"certificationSlug": "franchise-operator"
+	}
+} satisfies SoulcraftKitConfig;
+
+export default franchiseOps;