Feature Registry

The Feature Registry is a core architectural feature of the Stock SaaS Application that formalizes how application features are registered, structured, and surfaced across the system. It serves as the canonical source of truth for what features exist in the application, how they are implemented in code and data, and how they are accessed and personalized for different users through the Rich Role system.

This registry addresses a common and growing problem in complex SaaS applications: as functionality expands across dashboards, analytics tools, admin panels, and workflows, the ability to manage and trace features becomes increasingly difficult. This leads to fragmented permissions, duplicated work, inconsistent onboarding, and opaque system behavior.

The Feature Registry introduces a structured metadata layer that provides:

• Unique feature identifiers and human-readable names
• Canonical file paths for source code organization
• References to relevant database tables
• Role-based exposure metadata
• Gating flags for subscription tiers, rollout status, and experimentation

Developers interact with the Feature Registry through a simple, structured JSON or TypeScript file (featureRegistry.ts), which defines each feature and links it to source directories (e.g., src/features/orgGraph), database schemas, and configuration flags (e.g., Firebase Remote Config keys).

From a product perspective, this enables:

• Modular application design with one feature per folder
• Consistent access management across roles and subscriptions
• Easy discovery of functionality per user
• Role-specific onboarding and help content
• Streamlined LLM prompt design for feature-specific assistants

Developer Inspiration

This pattern is inspired by modular monorepo systems like Nx, feature flagging tools like LaunchDarkly, and metadata-driven CMS platforms. It draws architectural ideas from frameworks like Django’s apps.py, which organizes modular features with clear domain boundaries.

🔐 Role Access

System Administrator

System Administrators are the owners of the Feature Registry. They can view and manage all registered features, update configuration for gating/rollout, and ensure that each feature aligns with standardized source code paths and access rules.

User Stories:

• I want to view all registered features so I can audit the application structure.
• I want to create a new feature registry entry when we define a new business capability.
• I want to update the role exposure for a feature so we can change who can see it.
• I want to mark a feature as experimental so we can limit exposure to beta users.
• I want to add feature flags so that we can toggle access per tenant.
  • Note: Historically we thought about doing this via Firebase Remote Config but implementing directly in the app seems like a more controlled approach to it
• I want to assign source code and schema paths to each feature so that developers are aligned.
• I want to export the full registry for reporting or analysis.

Customer Success

Customer Success may need to inspect feature definitions when supporting a customer or diagnosing role-based access issues. While they can’t define new features, they need read-only access to understand what each feature does and which users should see it.

User Stories:

• I want to look up what a feature does and understand who can see it so I can answer a support ticket.
• I want to confirm whether a customer should have access to a feature based on their plan.
• I want to verify which roles can access a feature so I can explain its availability to a user.
• I want to read the feature flags that control a capability so I can escalate gating issues.

Customer Administrator

Customer Administrators don’t directly interact with the registry, but may benefit from simplified read-only views that explain what features are enabled for their organization. This supports transparency and delegated access control.

User Stories:

• I want to view a list of features available to our account so I can train our users.
• I want to see which roles are granted access to a feature so I can assign roles properly.

Manager / Standard User

These users don’t interact with the Feature Registry directly. However, their experience is dynamically personalized based on it. The features they see, the content they access, and the actions they can take are governed by registry rules.

No direct UI or user stories apply.

📄 Pages and Screens

1. Feature Registry Overview Page

Displays a list of all registered features with metadata columns. Allows creation, editing, and deletion (restricted by role). Supports search and filtering by role access, feature type (core/experimental), and flag status.

Screen Content:

• Feature Key
• Display Name
• Code Path
• DB Tables
• Enabled Roles
• Gating Flags (license tier, rollout)
• Action: Edit / View / Delete (role-dependent)

2. Feature Registry Detail Page

View/edit page for an individual feature. Used by System Admins to define a feature or by support staff to understand its composition.

Screen Content:

• Name: text field
• Key: slug, required, unique
• Description: multi-line
• Code Path: folder path input
• DB Tables: tag input (multi-field)
• Enabled Roles: checkbox group (from Rich Role list)
• Feature Flags: JSON or form-based view for
  • Enabled by default
  • Subscription requirement
  • Experimental / rollout toggle

3. Role-to-Feature Matrix View

Table view showing which Rich Roles have access to which features. Provides matrix-style layout for visibility and export. Filters for subscription tier, customer, or role.

Screen Content:

• Rows: Feature keys
• Columns: Rich Role names
• Cells: Checkbox or tag for access (editable by System Admins only)

🧱 Data Model

Name	Description	Constraints	Notes

Name	Description	Constraints	Notes
key	Unique feature identifier	Required, unique, lowercase slug	Used in code, configs
name	Human-friendly display name	Required, max 128 chars	Appears in UI
description	Feature summary	Optional, max 512 chars
code_path	Path to feature source code	Required	e.g. src/features/orgGraph
db_tables	List of related DB tables	Optional, multi-string	For traceability
available_roles	Array of Rich Role keys	Optional	Used to drive personalization
flags.enabled_by_default	Whether the feature is active by default	Boolean	Default: true
flags.subscription_required	Tier required (e.g., free, pro, enterprise)	Enum	Optional gating model
flags.experimental	Feature is in beta rollout	Boolean	Default: false

🤖 LLM Query

LLMs can be used to:

• Generate default feature descriptions from the feature key or name"You are a technical writer. Given the key 'feature_organization_graph', write a one-sentence description of what this feature does."
• Propose role exposure based on similar features"Suggest which Rich Roles should have access to a reporting feature based on existing registry entries."
• Summarize differences between features for admins"Compare 'feature_custom_reports' and 'feature_organization_graph' in terms of roles, code location, and gating."
• Validate naming conventions or recommend improvements"Does the feature key 'feature-useractivity' meet standard naming rules? If not, suggest a better one."

LLMs can be embedded as a helper within the Feature Registry Detail screen to auto-fill draft metadata or perform QA checks on incomplete records.