01 — Product Overview (Settings Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases (derived)
• 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 Settings module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, and wire contracts are derived directly from src/modules/settings/**, src/modules/organizations/**, src/modules/feature-flags/**, src/modules/rbac/permissions.constants.ts, studylyon-blueprint/04-Modules/Organizations.md and 03-Database/COLLECTIONS.md. No feature is invented; gaps are flagged in the Assumptions & Open Questions section.

1. Purpose

Settings is the tenant-scoped key/value configuration store of StudyLyon. It gives each organization a flat, arbitrarily-typed setting registry — key → value — grouped into six fixed buckets, read/written through a thin CRUD API.

The module is deliberately thin. It is a generic store: there is no per-key schema, no setting registry, no validation of values, and no history. The "rich" org-level configuration lives in a second, separate surface: the settings object embedded in the organizations document (organization.schema.ts:96-112) with its own endpoints (GET/PATCH /organizations/:id/settings). The blueprint separates them deliberately — "Settings separated from organizations to avoid hot-document writes" (Organizations.md:60), and defines a dedicated organization_settings collection (COLLECTIONS.md:767-783). Today only the standalone settings collection is implemented in code; the organization_settings collection is a blueprint concept not yet in code.

2. Business goals

3. User goals

• Org admin: browse every org setting in one screen, edit any value with the right input type, save one or many, remove stale keys.
• Setting editor (staff/admin with settings.* perms): find a key quickly (group filter
  • client search — the API has no search param), edit JSON/numbers/booleans without breaking values.
• Platform admin: cross-tenant visibility for support (platform admin bypasses the tenant scope, base.repository.ts:21-23).
• Consumers (other modules / future UI): read settings programmatically via GET /settings/:key or GET /settings?group=.

4. Stakeholders

Org admins, delegated setting editors, platform support, module developers (each module reads its own settings at runtime), QA/design/engineering. Note: today no backend consumer reads settings — nothing in src/ imports SettingsService outside the settings module (no cross-module call, per AGENTS.md module-boundary rule); consumption is via API or future events.

5. Why this exists

Schools differ in grading, attendance rules, notification preferences, and theming. A generic per-tenant store lets the platform ship one codebase with per-org behavior without schema migration per feature, and keeps high-frequency config writes off the hot organizations document (COLLECTIONS.md:781).

6. Dependencies

7. Success metrics

• List load < 300 ms (settings volume per tenant is small — tens to low hundreds of keys).
• Save round-trip < 500 ms p95; upsert idempotent — re-tap safe.
• Zero cross-tenant leaks (unique index + scopedFilter; QA-perm).
• Bulk save of N keys: all-or-nothing perception on UI despite sequential server loop (failure surfaced per item; see OQ-4).

8. Edge cases (derived)

• GET /settings/:key missing key → 404 RESOURCE_NOT_FOUND "Setting "key" not found." (settings.service.ts:20).
• PUT /settings missing key or value → class-validator has no decorators on them (update-setting.dto.ts:5-10) → Mongoose required validation error → 500 (OQ-3).
• DELETE /settings/:key → soft delete; the unique index {tenantId, key} (setting.schema.ts:38) still holds the soft-deleted doc → re-creating the same key after delete hits a duplicate-key error → 500 (OQ-5).
• label/description are accepted by the DTO (update-setting.dto.ts:17-25) but the service never persists them — only key/value/group reach the repo (settings.service.ts:25; setting.repository.ts:37).
• isEncrypted exists on the schema (setting.schema.ts:33-34) but nothing sets it and no encryption path exists (OQ-6).
• Bulk update runs a sequential loop, not a transaction (settings.service.ts:28-34) — a mid-batch failure leaves earlier keys saved.
• Platform admin GET /settings lists settings of all tenants (scope bypass, base.repository.ts:21-23).
• Values are untyped: value: unknown (update-setting.dto.ts:10) and @Prop({type: Object}) (setting.schema.ts:21-22) → the client must infer the editor type from the runtime value.

9. Assumptions (module)

• Mobile client is forward-looking: backend is complete; this package is the UI-side spec.
• The settings list is NOT paginated: findAll returns a bare array (settings.service.ts:10-12) and the envelope interceptor only adds meta for {data, meta} payloads (response-envelope.interceptor.ts:25-32,55-59) — the settings list is a single fetch with meta omitted.
• Group set is fixed to the enum: academic, attendance, grading, notification, theme, general (setting.schema.ts:7-14). A COACHING group is (planned) — IMPLEMENTATION_PLAN.md:773.
• No setting definitions exist: the UI is data-driven (render whatever keys exist); it cannot show a canonical "every setting" catalog, defaults, or per-key docs.
• Settings written via API are immediately consistent for subsequent reads (single Mongo doc, no cache layer in the settings path).

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

11. Glossary (this module)