PREWAVE-BE-101 — Persist Authenticated Theme Preferences Across API Instances #802

Problem context

src/theme.service.ts describes authenticated theme preferences as database-backed, but currently stores them in a process-local Map. Preferences disappear on restart and are not shared across API instances. getThemeStats() also returns hard-coded zero counts. The module and controller are active, so this is an exposed feature whose persistence contract is not fulfilled.

Technical scope

• Persist authenticated users' theme preference through the canonical user-preferences persistence layer (or a reviewed dedicated entity if none exists).
• Keep anonymous preference handling explicitly client-scoped; do not create a shared server-side anonymous preference.
• Ensure reads and writes are owner-scoped and safe under concurrent updates.
• Validate the supported values: light, dark, and system.
• Remove the process-local map as the source of truth and remove unused configuration/storage placeholders.
• Implement getThemeStats() from persisted records only if the API contract requires it; otherwise remove/deprecate the misleading method and update its callers/docs.
• Add a migration and document default behavior for users without a stored preference.

Required tests

• Set/get round-trip across service instances (simulated restart).
• Two users cannot read or overwrite each other's preferences.
• Concurrent updates produce deterministic last-write behavior.
• Invalid theme values are rejected.
• Missing preference resolves to the documented default.
• Statistics reflect persisted records or the obsolete statistics method is absent.

Security and architecture constraints

• Use the authenticated user identity from the server-side guard; never trust a caller-supplied user ID for ownership.
• Do not store preferences only in process memory or expose user identifiers in logs.
• Keep anonymous theme preference client-side.
• Preserve API compatibility or provide a versioned migration.

Acceptance criteria

• Authenticated theme preferences survive process restart and multiple API instances.
• User isolation is enforced in every read/write path.
• Only supported theme values are accepted.
• Hard-coded zero statistics and simulated persistence are removed.
• Migration, tests, and API documentation are included.
• Exact-head CI and independent review pass.

Dependencies

• None declared. Reuse the existing canonical user-preferences persistence boundary where available.

Non-goals

• Redesigning the frontend theme system.
• Adding new themes or user-profile features.
• Changing anonymous browser-local preference behavior.

Complexity and points

• Low — 100 points

Candidate only. Activation remains maintainer-controlled.