marketplaces/docs/architecture/foundation/adr/ADR-009-feature-flags-and-capability-guards.md

ADR-009: Feature Flags and Capability Guards

Status: Accepted Date: 2026-07-03

Context

Platform tenants have optional capabilities. Features cannot be assumed always present.

Decision

Introduce capability model backed by bootstrap feature flags:

• FeatureFlagService exposes tenant capabilities.
• Routes, widgets, and actions are guarded by capability checks.
• Missing capability must degrade gracefully with fallback behavior.

Consequences

Positive:

• One runtime supports variable tenant feature sets.
• Reduces tenant branching and dead code.

Negative:

• Requires explicit defaults and fallback UX.

Compliance Requirements

• Components and pages cannot assume optional feature availability.
• Capability checks must be centralized, not scattered conditionals.