Capability Modules & Entitlements

Overview

Feature modules bundle related resident experiences and admin controls so that paid entitlements can be managed as a single unit. A module becomes available to an institution only when a superadmin grants it (for example, the ai_scribe bundle). Once granted, resident-facing experiences auto-activate while admin-only controls remain opt-in until the right capability holders switch them on.

Each module entry carries:

• slug (e.g., ai_scribe, scheduling)
• Persona tag to hint at the owning team (Education, Operations, etc.)
• Lists of resident experiences and admin controls referencing canonical features
• Activation metadata per sub-feature:
  • activation_mode = auto | admin_opt_in
  • default_state for opt-in controls when the module is first enabled

Lifecycle

1. Superadmin grant/revoke
   POST /admin/superadmin/institutions/{id}/feature-modules toggles entitlement. We audit every change with GRANT_FEATURE_MODULE / REVOKE_FEATURE_MODULE. Auto-on experiences are immediately available; opt-in controls read their defaults but can be overridden.

2. Capability assignment & delegation
   Opt-in controls are governed by capability groups. Superadmins grant group access via /admin/superadmin/institutions/{id}/admins/{admin_id}/capabilities; the payload accepts grant_groups, revoke_groups, plus optional fine-grained enable_features overrides when a whole group is active. Senior admins can only delegate groups that a superadmin has enabled for them through /admin/institution/admins/{id}/capabilities. Overrides are still stored in institution_feature_module_overrides, but institution-level module toggles now respond with 403.

3. Senior-admin invite workflow
   Senior admins invite additional admins through /admin/institution/admins. The UI auto-selects the delegatable capability groups the inviter controls, shows the invite link immediately, and lists pending invitations alongside the admin roster.

4. Resident & tooling impact
   GET /admin/superadmin/feature-modules (superadmin) and /admin/institution/feature-modules (institution) continue to expose module status so downstream UIs stay consistent.

Data Model Summary

• feature_modules – defines the bundle.
• feature_module_features – links features to modules with role + activation metadata.
• institution_feature_modules – institution-level entitlements (premium billing gate).
• institution_feature_module_overrides – records opt-in toggles for admin controls.

The demo seed enables ai_scribe, knowledge_hub, and analytics by default so the sample institution exercises the entire stack.

Operational Notes

• Module grants should align with billing events; opt-in controls are governed by capabilities so senior admins can safely manage access inside the paid surface.
• When a module is revoked we drop overrides/capability grants and mark features as disabled, guaranteeing residents lose access immediately.
• Senior-admin invites now surface copyable links; keep FRONTEND_URL accurate per environment.
• Future modules can be seeded via scripts/seed_features.py; set activation_mode/default_state per sub-feature.

Capability Group Rules

• Every admin-facing feature is associated with exactly one capability group; the Alembic migration 24c363a90e3d_migrate_capability_delegations_to_groups enforces the mapping and backfills existing delegations.
• Group toggles cascade to all child features. You can still disable individual features inside an active group, but turning the group off immediately revokes every child.
• Invitation payloads persist requested group slugs (requested_capability_groups) so newly accepted admins inherit the same bundles the inviter chose.

Last updated: 2025-03-18.