PRD: Plans & feature flags

Module	Licensing	PRD ID	PRD-PLN-001
Status	Ready to dev	FEAT	PLN
Epic	—	Plane	BANA-1508
Date	2026-06-05	Version	v1.0
Packages	@nx/licensing	URD	PLN
Surface	Backend
Owner	Phát Nguyễn

What plans & feature flags are

BANA is sold as plans that bundle different feature sets and device seat limits. The product needs one place that defines what each plan carries, before any license is ever issued from it. Without it, every module ends up defining its own plans and features, leaving the plan catalog inconsistent and impossible to reuse across sign-up and upgrade surfaces.

This PRD establishes the plan template: reusable plans - trial, subscription, perpetual - carrying a duration, a grace period, a device seat limit, and a bag of typed feature flags whose codes are unique within each plan.

License issuance lives in another PRD

This PRD only defines the plan template - it does not issue licenses, drive a lifecycle, or activate devices. Issuing licenses from these plans, renewing, suspending, reinstating, revoking, device activation, and runtime validation are specified in PRD-ACT-001.

One plan, from creation to archival

What happens	Plan state
Operator creates the plan, sets a 365-day duration, a 15-day grace period, a device seat limit	Being authored
Attaches typed feature flags, each code unique within the plan	Being authored
Sets a bilingual name, description, and display order	Being authored
Activates the plan	Active - appears in the public catalog in the right order
Plan no longer sold	Archived - disappears from the catalog, its data stays intact

A public plan catalog lists active plans in display order, for sign-up and upgrade surfaces to read.

Where it's easy to get wrong

Archiving is not deleting

A plan no longer in use is soft-deleted (archived) - never hard-deleted from the app. The plan disappears from the public catalog, but its data and any licenses issued from it stay intact. A feature flag's code must be unique within each plan, and that constraint is enforced at the storage layer, not only in application code.

1. Goals & Exclusions

Goals

• Operators define reusable plans (trial / subscription / perpetual) with a duration, a grace period, and a device seat limit.
• Attach typed feature flags (boolean / number / text / json) to a plan, with a flag code unique within each plan.
• Plans carry a bilingual display name and description plus a display order.
• Expose a public plan catalog listing active plans with their active features, in display order.
• Soft-delete (archive) a plan no longer in use, never hard-delete it.

Exclusions

• Issuing a license and driving its lifecycle (renew / suspend / reinstate / revoke) - specified in PRD-ACT-001.
• Device activation and seat-limit enforcement - specified in PRD-ACT-001.
• Runtime validation and the signed certificate - specified in PRD-ACT-001.
• Billing, invoicing, dunning, or payment-charge integration.
• A plan-management UI (frontend concern).

2. Success Metrics

Metric	Target / signal
Catalog correctness	The public catalog shows only active plans, in the configured display order
Feature-flag uniqueness	No two feature flags share the same code within the same plan
No hard deletes	100% of deactivated plans go through soft delete (archive); no plan is ever hard-deleted from the app

3. Personas & Use Cases

Persona	Goal in this feature
Platform Operator	Define plans & feature flags; set bilingual name/description and display order; archive plans no longer in use
Merchant owner / sign-up surface	Browse the public plan catalog to choose or upgrade

Core scenario: an operator creates a plan with a duration, grace period, and device seat limit, attaches typed feature flags with unique codes, sets a bilingual name/description and a display order, then activates the plan - it appears in the public catalog in the right order. When a plan is no longer in use, the operator archives it; the plan disappears from the catalog but its data stays intact.

4. User Stories

#	As a	I want	So that
01	platform operator	I define reusable plans with a duration, grace period, and device seat limit	I can package what each tier of merchant may run
02	platform operator	I attach typed feature flags to a plan with a unique code	each feature is switched on/off or capped without any ambiguity
03	platform operator	I set a bilingual name, description, and display order for a plan	the public catalog reads correctly in both languages
04	merchant owner	I browse a public catalog of active plans	I can choose or upgrade my plan
05	platform operator	I archive a plan that's no longer sold	it disappears from the catalog without losing data or affecting licenses already issued from it

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Create a plan with a type, a duration, and a grace period. • Type: trial / subscription / perpetual. • Duration: a set value, or null for a perpetual plan. • Grace period: optional.	✅	URD-PLN-001..002
FR-002	A plan can cap the number of devices with a seat limit. • Setting a device seat limit (optional): caps the number of devices allowed on the plan. • Seat limit set to null: unlimited devices.	✅	URD-PLN-003
FR-003	Attach typed feature flags to a plan, with clear behavior once deactivated. • Flag type: boolean / number / text / json. • A deactivated flag: resolves to its type's empty/off default.	✅	URD-PLN-004..005
FR-004	Expose a public plan catalog. • Lists only active plans, in the configured display order. • Each plan is shown with its active features.	✅	URD-PLN-008
FR-005	A feature flag's code is unique within each plan.	✅	URD-PLN-006
FR-006	A plan carries display information for the public catalog. • Display name and description: bilingual (English / Vietnamese). • Display order: a value used to sort the plan within the catalog.	✅	URD-PLN-007
FR-007	A plan is soft-deleted, never hard-deleted. • A plan is soft-deleted (archived) when no longer in use. • A plan is never hard-deleted from the app.	✅	URD-PLN-009

5.1 Acceptance Criteria

• An operator creates a subscription plan with a 365-day duration and a 15-day grace period - the plan saves and is ready to be picked when issuing licenses from it.
• An operator creates a perpetual plan with no duration set - the plan saves with a null duration.
• An operator sets a plan's seat limit to null - the plan allows unlimited devices once licenses are issued from it.
• An operator attaches a boolean feature flag to a plan, then deactivates it - resolving the plan's features returns the off default instead of the previously configured value.
• An operator tries to attach two feature flags with the same code to a plan - the second attempt is rejected because that code already exists on the plan.
• An operator sets a bilingual name and description (English / Vietnamese) plus a display order for a plan - both languages render correctly in the catalog, in the configured order.
• Open the public plan catalog - only active plans show, in the configured display order, each with its active features attached.
• An operator archives a plan - the plan disappears from the public catalog while its data stays intact in the system, never hard-deleted.

6. Non-Functional Requirements

Area	Requirement
Data integrity	A feature-flag code is unique within each plan; the constraint is enforced at the storage layer, not only in application code
Immutability	An archived (soft-deleted) plan is never hard-deleted; references to it, such as licenses issued from it, stay intact
Tenancy & authz	Plan and feature-flag management is gated by licensing-scoped permissions
i18n	Plan display name and description are bilingual (English / Vietnamese)

7. UX & Flows

Backend-only surface covering plans and feature flags. There is no plan-management UI in this increment; sign-up and upgrade surfaces read the public plan catalog. Issuing licenses from these plans, device activation, and runtime validation are specified in PRD-ACT-001.

8. Data & Domain

Concept	Role
Plan	The reusable template - type, duration, grace period, seat limit, bilingual display name/description, display order
Plan feature flag	A typed feature flag on a plan (boolean / number / text / json), unique code per plan

Conceptual only - full schema and invariants in the licensing domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	Depends on what
01	Permissions (Permissions)	plan and feature-flag management is gated by licensing-scoped permissions.

Assumptions

#	Assumption	What breaks if wrong
01	Licenses are issued from these plans per the process specified in PRD-ACT-001; this PRD only defines the plan template.	If license issuance doesn't follow the plan template defined here, plans and licenses drift out of sync, and the public plan catalog stops reflecting what a merchant actually receives.
02	Archiving a plan does not affect licenses already issued from it.	If archiving lost or altered already-issued licenses, a merchant on that plan would lose features abruptly without changing anything themselves.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P1 - foundation of the licensing module, see URD feature catalog
Rollout	Foundation of the licensing module; no feature flag
Migration	None (foundational concepts)
Launch criteria	Create plan → attach feature flags → activate → shows correctly in the public catalog; duplicate flag codes are rejected; archiving a plan never hard-deletes its data
Monitoring	Count of active plans, rejection rate on duplicate feature-flag codes, public catalog view count

References

• URD: Licensing - Plans & Feature Flags
• License lifecycle, device activation, and runtime validation are specified in PRD-ACT-001.
• Module: Licensing - URD
• Developer: @nx/licensing · domain model

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Archiving a plan that active licenses still reference	Archiving only hides the plan from the public catalog; it does not affect licenses already issued from it
02	No dedicated plan-management UI yet	Plan creation/editing happens via the API today; open question whether a dedicated admin screen is needed

FAQ

#	Question	Answer
01	Does this handle license issuance or lifecycle?	No - this PRD only defines plans and feature flags. License issuance, renewal, suspension, reinstatement, and revocation are specified in PRD-ACT-001.
02	Does this handle device activation or runtime validation?	No - both are also specified in PRD-ACT-001, built on the plans defined here.
03	Can two feature flags share the same code within one plan?	No - a feature-flag code is unique within each plan; attempting to create a duplicate code is rejected.
04	What happens when a feature flag is deactivated?	It resolves to its type's empty/off default instead of the configured value, without needing to delete the flag.
05	Does archiving a plan remove it from the system?	No - archiving is a soft delete. The plan disappears from the public catalog, but its data stays intact and is never hard-deleted.