01 — Product Overview (Feature Flags Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases (client-relevant)
• 9. Assumptions (module)
• 10. Open questions (module-level; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Feature Flags module client (Flutter, forward-looking spec) against the implemented NestJS backend. Every endpoint, DTO field, schema, permission, and wire contract below is derived directly from src/modules/feature-flags/**, src/modules/organizations/**, src/modules/rbac/permissions.constants.ts, src/database/base.repository.ts, src/infrastructure/bullmq/queue.constants.ts, and the studylyon-blueprint handbook. No feature is invented; gaps are flagged in Assumptions & Open Questions and marked (planned) / (forward-looking) / (proposed) per global rules.

1. Purpose

Feature Flags let a tenant (institution) turn optional platform capabilities on and off — biometric attendance, SMS, WhatsApp channels, AI reports, payroll, inventory, and similar channel/integration toggles (blueprint 03-Database/COLLECTIONS.md:785-801). It is the configuration surface for "gradual rollout" and capability gating: downstream services are supposed to read a flag before offering a feature (PLAN.md:29 — scenario 2.6 "Configure feature flags (biometric, SMS, etc.) … Feature-toggle read in downstream services").

There are two distinct flag surfaces in the backend, and they are not connected in code:

1. Flag store — the feature_flags collection (feature-flag.schema.ts:7): a per-tenant catalog of toggles with metadata. Served by /api/v1/feature-flags*.
2. Org lifecycle overlay — organizations.metadata.featureFlags: Record<string, boolean> (organization.schema.ts:129-130), served by GET/PATCH /api/v1/organizations/:id/feature-flags. PATCH full-replaces the map (organizations.service.ts:149-151).

FeatureFlagsService.isEnabled() reads only the flag store (feature-flags.service.ts:22-25). The blueprint assigns "Feature flag evaluation" to the Organizations module (blueprint 04-Modules/Organizations.md:17) — this integration does not exist yet (OQ-2).

2. Business goals

3. User goals

• Org admin: browse all toggles for my school, see what's on/off per module, flip a channel (biometric, SMS, WhatsApp) and trust it applies.
• Feature configurator (admin delegate): edit labels/descriptions, batch-enable a rollout (bulk update), fix a mistake (rollback a flag).
• Platform admin: read flags across tenants during support; platform-level toggles.
• End users (teacher/staff/parent/student): never see a disabled feature — UI hides or explains it; no crashes when a flag flips mid-session.

4. Stakeholders

Platform operator (SaaS vendor — tenant tiers/plan gating (proposed)), institution admins, downstream module owners (biometric, notifications, payments — all forward-looking), support staff (misconfigured channels), QA + design + engineering consuming these docs.

5. Why this exists

One codebase serves thousands of institutions with different capabilities (school vs coaching (planned) matrix, IMPLEMENTATION_PLAN.md:310-336) and different channel entitlements (WhatsApp BSP approval, biometric hardware availability — FEATURE_ROADMAP.md:54-57). Flags decouple code presence from feature availability without per-tenant branches. The blueprint lists "Feature toggles / Gradual rollout / A/B testing" as the module's responsibilities (MODULE_ARCHITECTURE.md:304-312); only the toggle CRUD exists in code — gradual rollout and A/B testing are (planned) (OQ-6). The roadmap slots the framework in Phase 3 (FEATURE_ROADMAP.md:42).

6. Dependencies

7. Success metrics

• Flag list/filter/read latency < 200 ms p95 (direct Mongo, no cache today — CACHE_ARCHITECTURE.md:48 proposes 30 s cache).
• Toggle write p95 < 1 s; bulk of ≤ 20 flags applies in < 3 s (sequential loop, OQ-3).
• Zero cross-tenant flag leakage (scopedFilter enforced).
• isEnabled() is consumed by ≥ 1 downstream module (biometric / notifications) — target; no consumer today (OQ-1).
• No 5xx storm from the delete→re-create E11000 edge (OQ-4).
• Flag-change propagation to client ≤ 30 s (poll TTL) once cache lands.

8. Edge cases (client-relevant)

• Upsert drops description and module: DTO accepts them (update-feature-flag.dto.ts:13-26) but FeatureFlagRepository.upsert only $sets enabled and label (feature-flag.repository.ts:40). Editing a flag's description/module silently persists nothing.
• PUT /feature-flags with a new key = create (upsert); enabled is required → you cannot create a "disabled-by-default" flag without sending enabled:false.
• Bulk update is sequential, no transaction (feature-flags.service.ts:40-44): a failing item mid-list leaves earlier writes applied.
• Delete is soft: flag vanishes from every list (base.repository.ts:20-30), but the unique {tenantId,key} index slot persists — re-creating the same key after delete can hit E11000 → 500 (OQ-4).
• Org-level PATCH full-replaces: flags omitted from the body are lost (organizations.service.ts:149-151).
• Missing key → 404 RESOURCE_NOT_FOUND ("Feature flag "" not found." — feature-flags.service.ts:29).
• Platform admin: reads bypass tenant scope (base.repository.ts:21-23), but upsert calls requireTenantId() directly (feature-flag.repository.ts:37) — a platform-admin write without a tenant context fails (OQ-5).

9. Assumptions (module)

• The client (Flutter) is forward-looking; the backend surface is complete and is the contract source.
• feature-flags.read/update/delete are the canonical permission names (permissions.constants.ts:78-80); the UI is designed so the server can start enforcing them without UI redesign (OQ-5).
• The feature_flags collection has no seed data in code — tenants start with an empty catalog; the UI must render a useful empty state and the client ships no hardcoded keys. Default per-institution matrices are (planned) (IMPLEMENTATION_PLAN.md:310-336).
• Flag evaluation cache (30 s poll, sl:global:featureflag:{name}) is documented in the blueprint, not implemented (CACHE_ARCHITECTURE.md:33,48); the client must therefore treat server responses as immediately authoritative and re-fetch per its own TTL.
• "Gradual rollout" and "A/B testing" are blueprint responsibilities (MODULE_ARCHITECTURE.md:310-312) with no API support — no percentage/audience fields exist on the schema (feature-flag.schema.ts:9-22).

10. Open questions (module-level; global ledger in 00-shared/12)

11. Glossary (this module)