0004 - Store Server Notification Copy as Snapshots

Status: Accepted Date: 2026-04-04 Author: Codex

Context

Feel Pro Club is introducing server-originated notifications that appear in the Home feed.

The product needs a clear ownership model for notification copy and localization:

• The app already owns chrome copy such as loading states, empty states, static labels, and navigation text through its locale files
• Notification cards delivered by the API need stable, display-ready copy that can be shown consistently across clients
• Existing notifications should not silently change when app copy files, translations, or rendering logic change later
• The system also needs a narrow foundation that can support future notification kinds without pushing semantic rendering logic into the client

Without an explicit decision, copy ownership would drift between fpc-app locale files and fpc-api business logic, and clients would need to understand notification semantics in order to render user-facing text.

Decision

Feel Pro Club will treat server-originated notification copy as API-owned rendered snapshots.

1. fpc-api owns notification card copy for server-originated notifications, including title, message, CTA label, and CTA route.
2. Notifications are rendered at creation time through an API-side notification registry and stored in the database as snapshots together with notification metadata.
3. Home clients consume notifications as display-ready payloads. They do not reconstruct notification text from kind-specific semantic metadata.
4. fpc-app locale files remain responsible for app chrome only, not for server-originated notification body copy.
5. Notification locale is selected at creation time from the current request context. For the current implementation, Accept-Language is preferred over JWT metadata, with fallback to Spanish.
6. Changing the user's language later affects newly created notifications only. Previously stored notifications remain unchanged unless a future migration or explicit regeneration flow is introduced.

Consequences

Positive

• Notification rendering stays centralized in one backend registry instead of being duplicated across clients
• Stored notifications remain stable even if app translations or rendering logic change later
• Clients can stay simple and treat notifications as opaque UI content
• Future notification kinds can add payload schemas and registry entries without forcing frontend re-rendering logic

Negative

• Existing notifications do not automatically change when a user changes language later
• Copy fixes require new notifications or an explicit regeneration strategy; updating app locale files is not enough
• The API becomes responsible for localization and snapshot rendering concerns for server notifications

Mitigations

• Use request-time locale signals so newly created notifications reflect the user's active app language as accurately as possible
• Keep notification payload schemas narrow and versioned through shared contracts as new notification kinds are introduced
• If product requirements later demand re-localizing historical notifications, introduce a new ADR for regeneration or template-versioning rather than changing this behavior implicitly