Skip to main content

System Architecture

System Components​

ComponentResponsibility
identity-serviceAuthentication, JWT issuance, distributor provisioning, customer identity, and role/account claims
customer-serviceDistributor invites, customer assignment, and entitlement checks
game-serviceAuthoritative two-player WHOT gameplay
chat-serviceModerated encrypted messaging, receipts, retention, legal hold, and audit trails
whot-iosNative SwiftUI client for onboarding, gameplay, and entitled chat
staff-consoleInternal moderation interface
gatewayNGINX routing layer for local service access

Architecture Principles​

  • Each service owns one domain and its own persistence boundary.
  • REST handles commands and queries; WebSockets handle live gameplay and live chat events.
  • Authorization is explicit through JWT claims and trusted service-to-service credentials.
  • Production hardening must preserve the documented service boundaries rather than collapsing them into shared state.

Principal Flows​

Registration and onboarding​

  1. A distributor is provisioned through the identity service.
  2. The customer service issues a single-use invite.
  3. Invite redemption creates a customer identity and relationship link.
  4. Downstream services use the relationship state and JWT claims to authorize access.

Gameplay​

  1. A player creates a game invite.
  2. The recipient accepts or declines.
  3. The game service becomes the single source of truth for turn resolution and scorekeeping.
  4. WebSocket sessions stream live game events and reconnect support.

Chat​

  1. Chat conversations are created only for entitled distributor-customer pairs.
  2. Messages are encrypted and stored with delivery/read state.
  3. Participant-facing copies disappear after both parties read them.
  4. Retained archives remain available for approved moderation workflows until expiry or legal-hold release.

Boundaries​

  • identity-service does not own gameplay or chat content.
  • customer-service does not authenticate users.
  • game-service does not manage relationships or chat.
  • chat-service does not decide who may be related; it consumes entitlement decisions.