feat: mail service

ARCHITECTURE.md

@@ -271,13 +271,13 @@ Architectural rules fixed for this service:
 * `User Service` stores only the current effective `declared_country`; review
   workflow and history belong to `Geo Profile Service`.
 * During the current auth-registration rollout, `Auth / Session Service`
-  passes temporary `preferred_language="en"` plus the confirmed `time_zone`
-  into `User Service`. Gateway-side geoip language derivation is a later
-  rollout step and is not part of the current source-of-truth contract.
+  passes a preferred-language candidate derived from public
+  `Accept-Language`, falling back to `en` when no supported value is
+  available, plus the confirmed `time_zone` into `User Service`.
 
 Future billing does not become a direct dependency of other services. `Billing Service` will feed entitlement/payment outcomes into `User Service`, and the rest of the platform will continue to use `User Service` as the source of truth for current entitlements.
 
-## 4. Mail Service
+## 4. [Mail Service](mail/README.md)
 
 `Mail Service` is the internal email delivery service.
 
@@ -286,7 +286,23 @@ Split of responsibility:
 * auth code emails: `Auth / Session Service -> Mail Service` directly;
 * all other user/admin notification emails: `Notification Service -> Mail Service`.
 
-Mail delivery may be internally queued inside the mail service, but to its callers it is still a synchronous internal command where the caller needs a deterministic send-or-fail result.
+Transport rules:
+
+* `Auth / Session Service -> Mail Service` uses the dedicated synchronous
+  trusted internal REST contract `POST /api/v1/internal/login-code-deliveries`;
+* `Notification Service -> Mail Service` is an asynchronous internal command
+  flow carried through the event bus or an equivalent queue-backed handoff.
+
+`Mail Service` may internally queue both flows.
+Its trusted operator read and resend APIs are part of the v1 service surface,
+not a later add-on.
+For auth callers, a successful result means the request was durably accepted
+into the mail-delivery pipeline or intentionally suppressed; it does not
+require that the external SMTP exchange already completed before the response
+is returned.
+Stable service-local delivery rules, retry semantics, and Redis-backed
+processing details belong in [`mail/README.md`](mail/README.md), not in the
+root architecture document.
 
 ## 5. [Geo Profile Service](geoprofile/README.md)
 
@@ -297,7 +313,7 @@ It integrates with:
 * gateway as asynchronous ingest producer;
 * `User Service` for current effective `declared_country`;
 * `Auth / Session Service` for suspicious session blocking;
-* `Mail Service` only for optional admin notifications.
+* `Notification Service` for optional admin notifications.
 
 It owns:
 
@@ -309,6 +325,8 @@ It owns:
 
 It does not block the request that triggered suspicion.
 It can only request block of suspicious sessions for subsequent requests.
+It does not call `Mail Service` directly; optional admin mail must flow
+through `Notification Service`.
 
 In this document, references to `Edge Service` in older geo documentation should be understood as `Edge Gateway`.
 
@@ -519,7 +537,7 @@ It has a deliberately minimal role:
 * decide whether a given event should result in push, email, or both;
 * render and route notification payloads;
 * send push-targeted events toward gateway;
-* send email-targeted commands toward `Mail Service`.
+* send email-targeted asynchronous commands toward `Mail Service`.
 
 It is not a source of truth for user preferences in v1 unless a later feature requires it.