Backend Core Packages

Related documentation: Commercial Model · Permissions Blueprint · Backend Core Modules · Backend Core Addons

Package Design Specification

Audience: product, commercial, admin, backend, frontend, operations
Status: design specification
Scope: this page defines what a package is, how packages must be created, how future packages should be added, and how packages relate to modules, add-ons, permissions, and delegation.

Important rule for this page

This page is intentionally design-only.

it is based on the commercial and capability model provided in the platform-module document
it does not describe what is already implemented
it does not depend on current backend limitations
it defines the catalog logic that the system must follow over time

1. What a package is

A package is the top-level commercial bundle a company buys.

A package answers:

What does this company own by default?

A package is not:

a user role
a permission set
a module by itself
an add-on by itself
a pricing-only label with no entitlement meaning

A package is a commercial wrapper that enables one or more modules and defines the base product tier for a company.

2. Commercial model from the platform definition

Based on the attached platform-module definition, the platform currently has:

2.1 One base package

basic_promoter

2.2 Add-ons attached to a base module

Finance Module
AI Module
Touring Module
Venue Marketplace Module

2.3 Base module examples

Promoter base module
Artist base module
Vendor base module
Venue base module

This creates a core commercial rule:

Some products are package-first.
Some products are module-first.

That rule must remain explicit in the catalog and never be left to interpretation in UI code.

3. The Basic package

The Basic package includes access to the core operational platform features.

3.1 Business meaning

Basic is the main operational entry package for the core product experience.

It is the bundle that gives a company access to the main planning, market, artist, event, workspace, and operational intelligence capabilities of the platform.

3.2 Included capabilities

The Basic package currently includes:

Artist data
Artist data analysis
Charts
Industry contacts
Availability tracking
Booking system direct with agency
Events list and calendar
Event creation tools
AI market study on similar ticket prices
AI market value estimation of an event
Estimated cost / P&L
Financial report on estimated values, and actual values when combined with the required commercial features
Workspace and task management
News and updates
Market data
Festival ranking
Upcoming shows in a city and estimated market value
Top promoters by country, region, and worldwide

3.3 Design rule

The Basic package should be treated as:

one commercial package
backed by one or more underlying modules
with its own permission families and feature groups
capable of evolving internally without changing the meaning of the package itself

This means the Basic package is a commercial product, even if the platform later separates some of its features into more precise module boundaries.

4. What every package must define

Every package must define:

a stable package key
a human-readable name
a commercial description
whether it is active
which modules are included by default
whether it can be bought standalone or only in combination
upgrade and downgrade rules
compatibility with add-ons
whether it is visible to sales/admin
lifecycle status

4.1 Required conceptual fields

Every package should conceptually have:

Field	Purpose
`key`	Stable technical identifier
`name`	Commercial display name
`description`	Human-readable package description
`isActive`	Whether the package is sellable/assignable
`includedModules`	Module keys enabled by the package
`allowedAddons`	Add-ons that may be attached
`requiresBasePackage`	Whether the package can exist alone or only under a broader model
`commercialType`	Base package, premium package, vertical package, internal-only package, etc.
`lifecycleStatus`	Draft, active, inactive, deprecated, archived
`upgradeTargets`	Packages this package may move to
`downgradeTargets`	Packages this package may move to
`visibility`	Public, admin-only, migration-only, internal-only

4.2 Package key rules

Package keys must:

be stable over time
be lowercase
use hyphenated or simple slug format
never include prices, campaigns, or region-specific temporary labels

Good examples:

basic
premium-market
artist-enterprise

Bad examples:

basic-99usd
promo-july
sg-premium-special-v2

5. Package taxonomy

Not all packages are the same kind of product. Future catalog design should use consistent package categories.

5.1 Base package

The main starting bundle for a company.

Current example:

basic

5.2 Vertical package

A package aimed at a specific business profile or use case.

Future examples:

promoter package
agency package
venue operator package

5.3 Premium package

A package that expands a base tier with additional included modules.

Future example:

basic + market + ai

5.4 Internal or migration package

A non-public package used only for data migration, legacy compatibility, or special rollout conditions.

These must never be used as normal public product definitions.

6. How to create a package

When creating a new package, the process must start from commercial meaning, not implementation convenience.

6.1 Step 1: define the product intent

First answer:

Who is this package for?
What business problem does it solve?
Is it a base product, a premium tier, or a specialized bundle?
Should it replace another package or coexist with it?
Is it long-term catalog material or a temporary migration/product experiment?

If those questions are not answered first, the package should not be created.

6.2 Step 2: define included modules

A package must specify which modules it enables.

Example:

Basic = basic
Premium Market Bundle = basic + market + ai

Packages must never be created as arbitrary UI labels with no module relationship.

6.3 Step 3: define add-on compatibility

A package must define:

which add-ons can be purchased with it
which add-ons are forbidden with it
whether add-ons are optional or required for specific advanced outcomes
whether any add-on becomes redundant because the package already includes the capability

Example:

Basic may allow:
- vendor-directory
- venue-directory
- live-ticket-sales
- ai-sales-report

6.4 Step 4: define permission families

A package does not directly assign user permissions, but it must define the permission families that become commercially possible.

Example:

If package includes finance module:
company may become eligible for finance.*
permissions

The actual user still needs a user-level grant, but the package decides whether the module is commercially available at all.

6.5 Step 5: define upgrade path

A package must explicitly document:

what package it can upgrade from
what package it can upgrade to
what package it can downgrade to
whether upgrade preserves add-ons
whether downgrade invalidates add-ons
whether downgrade requires access review

6.6 Step 6: define lifecycle rules

A package must state whether it is:

draft
active
inactive
deprecated
archived
hidden/internal-only

Deprecated packages may remain assigned to existing companies but should no longer be sellable to new ones.

6.7 Step 7: define operational ownership

Before a package becomes valid in the platform, the product definition must answer:

who owns the package commercially
who can assign it
who can retire it
who approves future changes to included modules

This is required so the package catalog does not become an uncontrolled list of one-off sales variants.

7. How to add more packages in the future

Future package creation must follow strict rules so the catalog does not become inconsistent.

7.1 A new package must not exist only because sales wants a new price point

If the only difference is pricing, consider whether pricing should be handled in billing rather than in a new package.

Create a new package only when:

included modules differ
allowed add-ons differ
market positioning differs meaningfully
onboarding and entitlement behavior differs
the package represents a real product tier

7.2 New packages must reuse existing module keys

A package should normally reuse the established module catalog.

Bad pattern:

Create a new package and invent module-like behavior inside it.

Good pattern:

Create a new package by combining:
- existing modules
- explicit add-on compatibility
- explicit lifecycle rules

7.3 Future package checklist

Before approving a new package, confirm:

the target customer type is clear
the package is not just a pricing duplicate
the module set is explicit
add-on compatibility is explicit
permission-family impact is understood
upgrade/downgrade behavior is documented
lifecycle state is defined
package key is stable and clean

8. Package change management

Package creation is only one part of the design problem. Package evolution is equally important.

8.1 Changing a package is risky

If a package is already assigned to companies, changing its included modules may change company entitlements.

Therefore, package changes must always distinguish between:

change for future assignments only
change for all existing subscribers

8.2 Safe package changes

Safer changes include:

description updates
naming improvements
visibility changes
administrative lifecycle changes

8.3 High-impact package changes

High-impact changes include:

adding a new module to a live package
removing a module from a live package
making previously allowed add-ons invalid
changing upgrade or downgrade paths

These changes must be treated as commercial and access-impacting changes.

9. Package relationship to permissions and delegation

9.1 Package does not equal permission

A package does not say:

This user can do X

A package says:

This company is commercially eligible for X

9.2 Package enables permission families indirectly

The permission model should always resolve in this order:

Package
-> included modules
-> eligible permission families
-> user grants
-> scope restrictions
-> delegation restrictions

9.3 Delegation is downstream from package eligibility

If a package does not commercially enable a module, delegation cannot validly grant permissions inside that module.

Example:

Company has Basic only
-> no finance entitlement
-> no finance permissions should be granted
-> no user should be allowed to delegate finance permissions

10. Examples

10.1 Current package example

Package

basic

Included modules

basic

Allowed add-ons

vendor-directory
venue-directory
live-ticket-sales
ai-sales-report

Permission-family impact

enables eligibility for basic.*
may also enable related add-on permission families when add-ons are purchased

10.2 Future package example

Package

basic_artist

Included modules

artist
ai

Allowed add-ons

vendor-directory
venue-directory
ai-sales-report

Commercial meaning

premium market intelligence bundle
not a replacement for Finance
not just a price variation of Basic

11. Summary

Packages are commercial bundles.

They must be created from product meaning, not implementation shortcuts.

They must:

enable modules
control add-on compatibility
define commercial tiers clearly
remain stable over time
never replace the permission or delegation model

The package catalog must stay small, intentional, and commercially meaningful.