galaxy-game/notification/PLAN.md

Notification Service Implementation Plan

This plan has been already implemented and stays here for historical reasons.

It should NOT be threated as source of truth for service functionality.

Summary

This plan builds Notification Service as a durable asynchronous orchestration service between domain producers, Gateway, Mail Service, and User Service. The implementation must keep business-audience resolution in the producer, contact enrichment in Notification Service, client push delivery in Gateway, and email execution in Mail Service.

Global Rules

• Keep Notification Service orchestration-only.
• Preserve direct auth-code email flow from Auth / Session Service to Mail Service.
• Use one dedicated Redis Stream for normalized notification intents.
• Keep route retries independent per channel.
• Do not make notification delivery a correctness dependency for gameplay or geo review state.
• Keep user-facing push payloads lightweight.

Stage 01. Freeze Vocabulary And Cross-Service Ownership

Status: implemented.

Note:

• Later-stage artifacts may already exist in the repository as draft or pre-staged documentation.
• Their presence does not mark the corresponding later stages as implemented.

Goal:

• remove ambiguity before runtime work starts

Tasks:

• Freeze notification:intents as the dedicated ingress stream.
• Freeze that producers publish concrete recipient_user_id values for user-targeted intents.
• Freeze that Notification Service resolves user email and locale from User Service.
• Freeze that admin-only notifications use type-specific configured email lists.
• Freeze that template_id == notification_type.
• Freeze that private-game invites in v1 are user-bound by internal user_id.

Exit criteria:

• ARCHITECTURE.md, TESTING.md, and service READMEs no longer contradict the agreed notification model

Stage 02. Define The Intent Contract

Status: implemented.

Goal:

• publish one stable producer-to-notification contract

Tasks:

• Add notification/api/intents-asyncapi.yaml.
• Freeze envelope fields:
  • notification_type
  • producer
  • audience_kind
  • recipient_user_ids_json
  • idempotency_key
  • occurred_at_ms
  • request_id
  • trace_id
  • payload_json
• Freeze duplicate and conflict rules on (producer, idempotency_key).
• Freeze audience_kind=user|admin_email.

Exit criteria:

• every producer can publish normalized intents without service-specific side agreements

Stage 03. Freeze The Notification Catalog

Status: implemented.

Goal:

• turn product decisions into one exact type catalog

Tasks:

• Freeze v1 types and channel matrix.
• Freeze which types are user-targeted versus admin-only.
• Freeze that lobby.application.submitted is user-targeted for private games and admin-email-only for public games.
• Freeze that lobby.invite.revoked produces no notification.
• Freeze payload requirements per type.

Exit criteria:

• no notification type remains partially specified

Stage 04. Define Push Payload Schemas

Status: implemented.

Goal:

• freeze lightweight client-facing payloads

Tasks:

• Add pkg/schema/fbs/notification.fbs.
• Define one table per user-facing push type.
• Generate Go bindings under pkg/schema/fbs/notification.
• Document the mapping from notification_type to FlatBuffers table.

Exit criteria:

• Gateway and future client code have one stable schema file for user-facing notification payloads

Stage 05. Freeze Mail Template Contracts

Status: implemented.

Goal:

• make email handoff deterministic

Tasks:

• Freeze payload_mode=template for notification-generated email.
• Add initial en templates for all supported email types in mail/templates/<template_id>/en.
• Update mail documentation so notification template IDs align with notification_type.
• Keep Auth / Session Service auth-code mail unchanged.

Exit criteria:

• every supported email notification type has a documented template directory

Stage 06. Define Redis State And Retry Model

Status: implemented.

Goal:

• freeze durable service-local storage before runtime code

Tasks:

• Define notification_record, notification_route, notification_idempotency_record, notification_dead_letter_entry, and malformed-intent storage.
• Freeze Redis keys and schedule structures.
• Freeze route status vocabulary:
  • pending
  • published
  • failed
  • dead_letter
  • skipped
• Freeze retry budgets:
  • push=3
  • email=7

Exit criteria:

• the runtime can restart without losing accepted-or-retryable work

Stage 07. Build The Runnable Service Skeleton

Status: implemented.

Goal:

• create the initial process shape

Tasks:

• Add cmd/notification.
• Add internal/app, internal/config, internal/api, internal/service, and internal/adapters packages.
• Wire Redis startup checks, graceful shutdown, logger setup, and telemetry.
• Do not add an operator REST API in v1.

Exit criteria:

• the process boots with Redis and configuration validation only

Stage 08. Implement Intent Acceptance And Idempotency

Status: implemented.

Goal:

• durably accept valid intents and reject invalid or conflicting duplicates

Tasks:

• Consume notification:intents.
• Validate the envelope and normalized payload.
• Persist idempotency records and accepted notification records.
• Record malformed intents separately.
• Materialize channel routes according to the type catalog and audience_kind.

Exit criteria:

• valid intents are durable and replay-safe before downstream publication begins

Stage 09. Implement User Enrichment And Locale Resolution

Status: implemented.

Goal:

• make user-targeted routes self-sufficient for later publication

Tasks:

• Read users by user_id from User Service.
• Extract email and preferred_language.
• Apply en fallback when locale is missing or unsupported.
• Keep admin-email routes independent from User Service.

Exit criteria:

• every user-targeted route can be published without additional producer input

Stage 10. Implement Push Publication

Status: implemented.

Goal:

• hand off user-facing notification events to Gateway

Tasks:

• Encode the correct FlatBuffers table per notification_type.
• Publish client events into the configured Gateway stream with user_id targeting only.
• Apply independent push retry policy and route-level dead-letter handling.

Exit criteria:

• user-targeted push notifications survive temporary Gateway stream failures

Stage 11. Implement Mail Publication

Status: implemented.

Goal:

• hand off non-auth email notifications to Mail Service

Tasks:

• Build template-mode generic mail commands.
• Set template_id == notification_type.
• Pass through normalized template variables from payload_json.
• Apply independent email retry policy and route-level dead-letter handling.

Exit criteria:

• user and admin email notifications are durably handed off to Mail Service

Stage 12. Integrate Producers

Status: implemented.

Note:

• Implemented as the shared Go producer contract module galaxy/notificationintent because Game Lobby and Geo Profile Service code modules are not present in this repository yet.

Goal:

• move upstream services onto the new notification contract

Tasks:

• Game Master publishes:
  • game.turn.ready
  • game.finished
  • game.generation_failed
• Game Lobby publishes:
  • lobby.runtime_paused_after_start
  • lobby.application.submitted
  • lobby.membership.approved
  • lobby.membership.rejected
  • lobby.invite.created
  • lobby.invite.redeemed
  • lobby.invite.expired
• Geo Profile Service publishes:
  • geo.review_recommended
• Update Game Lobby architecture and later implementation plan to use user-bound private invites by user_id.

Exit criteria:

• producers no longer rely on ad hoc notification-side audience inference

Stage 13. Add Observability And Recovery Coverage

Status: implemented.

Goal:

• make the async runtime supportable in operations

Tasks:

• Add metrics for intake, duplicates, enrichment, publish attempts, retries, dead letters, and lag.
• Add structured logging fields shared across intake and route publishers.
• Document manual recovery steps for dead-letter inspection and replay.

Exit criteria:

• the runtime exposes enough signals to detect stuck, noisy, or broken delivery

Stage 14. Complete Test Coverage And Documentation Alignment

Status: implemented.

Goal:

• close the loop across service tests, boundary tests, and docs

Tasks:

• Add service tests for malformed intents, duplicates, locale fallback, retry budgets, and route isolation.
• Add inter-service tests with Gateway, Mail Service, Game Master, Game Lobby, and Geo Profile Service.
• Update TESTING.md.
• Update ARCHITECTURE.md, mail/README.md, geoprofile/README.md, and gateway examples.
• Verify docs still state that auth-code mail bypasses Notification Service.

Exit criteria:

• the implementation and the cross-service documentation describe the same contracts

Final Acceptance Criteria

The implementation is complete only when all of the following hold:

• valid intents are consumed from notification:intents
• duplicates are idempotent and conflicting duplicates are rejected
• user enrichment resolves email and locale from User Service
• push and email routes are persisted and retried independently
• route dead letters are isolated per channel and per recipient
• Gateway fan-out remains user-wide, not session-specific
• Mail Service receives template-mode commands whose template IDs match notification types
• admin notifications remain email-only
• auth-code email still bypasses Notification Service