galaxy-game/backend/internal/diplomail/README.md

diplomail

diplomail owns the diplomatic-mail subsystem of the Galaxy backend service. Messages live in the lobby-side domain (their storage and lifecycle are tied to a game), but they are surfaced inside the game UI — the lobby exposes only an unread-count badge per game.

Stages

The package ships in four staged increments. Stage A is the surface described below; the remaining stages add admin / system mail, lifecycle hooks, paid-tier broadcast, multi-game broadcast, bulk purge, and the language-detection / translation cache.

Stage	Scope	Status
A	Schema, personal single-recipient send / read / delete, unread badge, push event with body-language und	shipped
B	Owner / admin sends + lifecycle hooks (paused, cancelled, kick); strict soft-access for kicked players	shipped
C	Paid-tier personal broadcast + admin multi-game broadcast + bulk purge	planned
D	Body-language detection (whatlanggo) + translation cache + async worker	planned

Tables

Three Postgres tables in the backend schema:

• diplomail_messages — one row per send (personal, admin, or system). Captures game_name and IP at insert time so audit rendering survives renames and purges.
• diplomail_recipients — one row per (message, recipient). Holds per-user read_at, deleted_at, delivered_at, notified_at state. Snapshot fields (recipient_user_name, recipient_race_name) are captured at insert time and survive membership revocation.
• diplomail_translations — cached per (message, target_lang) rendering. One translation is reused across every recipient that asks for that language.

Permissions

Action	Caller	Pre-conditions
Send personal	user	active membership in game; recipient is active member
Send admin (single user)	game owner OR site admin	recipient is any-status member of the game
Send admin (broadcast)	game owner OR site admin	recipient scope ∈ active / active_and_removed / all_members; sender excluded
Read message	the recipient	row exists in diplomail_recipients(message_id, user_id); non-active members see admin-kind only
Mark read	the recipient	row exists; idempotent if already marked
Soft delete	the recipient	read_at IS NOT NULL (open-then-delete, item 10)

Stage C will add the paid-tier player broadcast and the bulk-purge admin endpoint.

System mail is produced internally by lobby lifecycle hooks: Service.transition() emits game.paused / game.cancelled system mail to every active member; Service.changeMembershipStatus / Service.AdminBanMember emit membership.removed / membership.blocked system mail addressed to the affected user.

Content rules

• Body is plain UTF-8 text. The server does not parse, sanitise, or escape HTML — the UI renders messages via textContent.
• Body length is capped by BACKEND_DIPLOMAIL_MAX_BODY_BYTES (default 4096). Subject length is capped by BACKEND_DIPLOMAIL_MAX_SUBJECT_BYTES (default 256). Both limits live in the service layer so they can be tuned without a schema migration.
• body_lang is stored as the BCP 47 und (undetermined) sentinel until Stage D wires the auto-detector.

Push integration

Every successful send emits a diplomail.message.received push intent through the existing notification pipeline. The catalog entry limits delivery to the push channel — email is intentionally absent; the inbox endpoint is the durable fallback for offline users. The payload includes the recipient's freshly recomputed unread count for the lobby badge and for the in-game header.

Lifecycle hooks (Stage B)

The lobby module is the producer of system mail. Stage B will add a DiplomailPublisher collaborator on lobby.Service and call it on paused / cancelled transitions and on BlockMembership / AdminBanMember. The publisher constructs a kind='admin', sender_kind='system' message with a templated body; the recipient receives the durable copy in their inbox even after the membership is revoked.

If a future stage adds inactivity-based player removal at the lobby sweeper, that path must call the same publisher so the kicked player has the explanation in their inbox.

Wiring

cmd/backend/main.go constructs *diplomail.Service with three collaborators:

• *Store over the shared Postgres pool;
• MembershipLookup adapter that walks the lobby cache for the active (game_id, user_id) row and stitches in the immutable accounts.user_name;
• NotificationPublisher adapter that translates each DiplomailNotification into a notification.Intent and routes it through *notification.Service.Submit.