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.