feat: edge gateway service

README.md

@@ -13,7 +13,27 @@ It is the starting point for implementing the external edge layer, authenticatio
 - Internal business services are **not reachable directly from outside**.
 - Any external command, except public auth commands, must be authenticated before it is routed further.
 - Gateway handles only edge concerns. Business validation and domain rules remain inside business services.
-- Push / long-polling delivery is also handled by the gateway.
+- Gateway owns external delivery channels; the v1 implementation uses
+  authenticated gRPC server-streaming push, while long-polling remains out of
+  scope.
+
+```mermaid
+flowchart LR
+    Client["Clients\n(native and browser)"]
+    Gateway["Edge Gateway\npublic REST + authenticated gRPC"]
+    Auth["Auth / Session Service"]
+    Business["Business Services"]
+    Redis["Redis\nsession cache + replay keys + event streams"]
+    Telemetry["Telemetry Backends\nPrometheus / OTLP"]
+
+    Client --> Gateway
+    Gateway --> Auth
+    Gateway --> Business
+    Gateway --> Redis
+    Gateway --> Telemetry
+    Auth --> Redis
+    Business --> Redis
+```
 
 ## Main Components
 
@@ -33,7 +53,7 @@ Responsibilities:
 - rate limiting and abuse protection
 - command routing
 - basic policy enforcement
-- long-polling / push connection handling
+- authenticated gRPC server-streaming push connection handling
 - delivery of client-facing events from pub/sub
 
 The gateway must not implement domain-specific business logic.
@@ -158,21 +178,26 @@ Flow:
 7. gateway verifies anti-replay constraints
 8. gateway applies rate limits and basic policy checks
 9. gateway extracts authenticated context, including `user_id`
-10. gateway routes the request to the target business service based on `command_type`
+10. gateway routes the request to the target business service based on `message_type`
 
 No business service should receive an unauthenticated external request.
 
-### Push / Long-Polling Flow
+### Push Flow
 
-The gateway owns external push / long-polling connections.
+The gateway owns external delivery connections.
+The v1 gateway uses authenticated gRPC server-streaming push.
+Long-polling remains out of scope for the implemented gateway.
 
 Flow:
 
-1. client opens authenticated push / long-polling connection through gateway
+1. client opens authenticated push connection through gateway
 2. gateway binds connection to `user_id` and `device_session_id`
-3. gateway may send current server time for clock offset calculation
-4. internal services publish client-facing events to pub/sub
-5. gateway consumes those events and delivers them to the proper client connections
+3. gateway starts the channel with a signed service event that includes the
+   current server time for clock offset calculation
+4. internal services publish client-facing events to pub/sub targeted by
+   `user_id` and optionally by `device_session_id`
+5. gateway consumes those events and delivers them to the proper client
+   connections
 
 Gateway is a delivery layer, not the source of business events.
 
@@ -184,7 +209,7 @@ Typical internal authenticated context:
 
 - `user_id`
 - `device_session_id`
-- `command_type`
+- `message_type`
 - verified payload bytes
 - transport `request_id`
 - optional command id / trace id
@@ -218,7 +243,7 @@ When a device session is revoked:
 - auth/session service publishes revoke/invalidation event
 - gateway updates or invalidates session cache
 - gateway rejects further requests for that session
-- gateway closes active push / long-polling connections bound to that session, if applicable
+- gateway closes active authenticated push streams bound to that session, if applicable
 
 ## Non-Goals