15 KiB
Scenes and Client/Server Data Plan (Draft 1)
This file defines scene scope and network data flow for the first client/server planning pass.
1) Scene/Page/UI Map (Client-First Draft)
1.1 Boot + Session Scenes
ClientLaunchHubConnectionPatchAndVersionCheckAuthGateway
1.2 Auth Scenes
LoginRegisterOAuthStartOAuthCallback
1.3 Primary App Scenes
MainMenuBazaarLeaderboardSettingsAccountManagementCollectionHubRankedPlayCustomPlayDeckEditorCardViewerCosmetics
1.4 Global Persistent UI (All Scenes)
Settingsbutton is present in every scene.Report Bugbutton is present in every scene.- Placement and interaction pattern must remain consistent across scenes.
1.5 Per-Scene UI Blocks (Draft)
ClientLaunch
- Splash/logo
- Build/version text
- Background init indicator
HubConnection
- Connection status indicator (connecting/retrying/failed)
- Retry button + diagnostics link (optional)
PatchAndVersionCheck
- Version comparison summary
- Patch progress bar
- Release notes panel (optional)
- Continue button when ready
AuthGateway
- Account/session check spinner
- Auth route chooser (Login/Register/OAuth)
- Service status banner
Login
- Username/email field
- Password field
- Remember device toggle
- Submit + Forgot Password actions
Register
- Email/username/password inputs
- Terms/privacy acceptance controls
- Submit action + validation messages
OAuthStart
- Provider buttons
- OAuth status text
OAuthCallback
- Verifying auth state message
- Success/failure redirect panel
MainMenu (Primary Interactive Hub)
- Navigation nodes/buttons to:
BazaarLeaderboardSettingsAccountManagementCollectionHubRankedPlayCustomPlay
- Profile summary widget
- Notifications widget
- Settings/logout actions
- Input support:
- mouse + touch (multi-touch required)
- use standard camera gestures for movement
- selection input: left click and middle mouse click on option nodes
- input behavior baseline is global and must remain consistent across all scenes
- Interactive background system:
- dark aura visual treatment
- rotatable 3D grid layer
- grid topology state can shift between square and hex
AccountManagement
- Identity panel:
- username
- profile image
- Password change action:
Change Passwordbutton opens popup/modal- fields:
new password,confirm password - actions:
SubmitandCancel
- Linked accounts panel:
Link Accountaction for available OAuth providers- show currently linked OAuth providers/status
- Stats panel:
- Origin points
- Win
- Loss
- Forfeit
- Draw
- Cards owned
- Cards played
- Spending panel:
Total Spentvalue censored by default- toggle to uncensor and reveal:
- money spent
- origin points spent
Download Reportaction for full spending profile/metrics export
- Legal links panel:
- Terms of Service (TOS)
- EULA
- other required legal documents
CollectionHub
- Tab nav (DeckEditor/CardViewer/Cosmetics)
- Collection summary strip
DeckEditor
- Deck list panel
- Card search/filter panel
- Deck composition panel
- Validation/errors panel
- Save/duplicate/delete actions
CardViewer
- Search input
- Filter/sort controls
- Card grid/list
- Card detail drawer/modal
Cosmetics
- Cosmetic category selector (back/trim/art/model)
- Preview pane
- Owned/locked state indicators
- Equip/apply controls
2) Shared Transport Notes
- Connection model:
- Persistent real-time session to relay/hub for presence + notifications.
- HTTPS API calls for auth/account/content operations.
- Auth model:
- Short-lived access token + refresh token.
- Device/session id tracked by server.
- Data model:
- Every payload includes
requestIdandserverTimeUtc. - Every list endpoint supports paging (
page,pageSize) and sorting.
- Every payload includes
3) Scene Details
3.1 ClientLaunch
Client
- Boot local config, device fingerprint, cached token state.
- Initialize telemetry/session id.
- Transition to
HubConnection.
Server
- None yet (local-only scene).
Data Exchange
Client -> Server:
- none
Server -> Client:
- none
3.2 HubConnection
Client
- Open relay/hub socket.
- Send initial hello with client build + platform metadata.
- Wait for connection acceptance and service availability.
Server
- Validate protocol version compatibility.
- Return environment capabilities and endpoint map.
- Return maintenance/degraded status if active.
Data Exchange
Client -> Server (HubHello):
requestIdclientVersioncontentVersion(installed asset/content hash)platform(windows,linux, etc.)localedeviceIdsessionId
Server -> Client (HubWelcome):
requestIdconnectionIdminSupportedClientVersionlatestClientVersionlatestContentVersionserviceStatus(ok,degraded,maintenance)apiBaseUrlcdnBaseUrlauthProvidersEnabled(google,steam,apple,microsoft)motd(optional)
3.3 PatchAndVersionCheck
Client
- Compare installed version/content against server-required values.
- If update needed: show patch status UI, download/apply, then reconnect.
- If up-to-date: continue to
AuthGateway.
Server
- Provide update manifest and rollout policy.
- Enforce hard-block if client below minimum supported version.
Data Exchange
Client -> Server (VersionStatusRequest):
requestIdclientVersioncontentVersionplatform
Server -> Client (VersionStatusResponse):
requestIdisClientSupportedrequiresClientUpdaterequiresContentUpdateminimumAllowedVersiontargetClientVersiontargetContentVersionupdateManifestUrlupdateNotes(optional)blockReason(if unsupported)
3.4 AuthGateway
Client
- Decide entry path:
- Existing session refresh.
- Username/password login.
- Register new account.
- OAuth provider login.
- Render enabled options based on server capabilities.
Server
- Validate refresh tokens and return session state.
- Provide auth policy (password rules, age gates, region restrictions if needed).
Data Exchange
Client -> Server (SessionProbe):
requestIdrefreshToken(optional)deviceId
Server -> Client (SessionProbeResult):
requestIdisAuthenticatedaccountId(if authenticated)displayName(if authenticated)authMethodsAvailablepasswordPolicy
3.5 Login / Register
Client
- Login:
- Submit account identifier + password.
- Register:
- Submit account fields and required agreements.
- On success transition to
MainMenu.
Server
- Login:
- Validate credentials, enforce lockout and MFA if enabled.
- Register:
- Create account, validate uniqueness, persist agreements.
- Return auth tokens + account summary.
Data Exchange
Client -> Server (LoginRequest):
requestIdemailOrUsernamepassworddeviceId
Server -> Client (LoginResponse):
requestIdsuccessaccessTokenrefreshTokenexpiresAtUtcaccountSummaryerrorCode(if failed)
Client -> Server (RegisterRequest):
requestIdemailusernamepasswordcountryCodedob(if required by policy)acceptedPolicies(policy ids + timestamps)
Server -> Client (RegisterResponse):
requestIdsuccessaccessToken(optional; if auto-login enabled)refreshToken(optional)accountSummary(optional)requiresEmailVerificationerrorCode(if failed)
3.6 OAuthStart / OAuthCallback
Client
- Start OAuth flow with selected provider.
- Open provider auth URL.
- Receive callback code/state and exchange with backend.
- On success transition to
MainMenu.
Server
- Generate signed OAuth start URL and anti-forgery state.
- Exchange auth code with provider and bind/create game account.
- Return tokens and account summary.
Data Exchange
Client -> Server (OAuthStartRequest):
requestIdprovider(google,steam,apple,microsoft)returnUrideviceId
Server -> Client (OAuthStartResponse):
requestIdauthorizationUrlstatecodeVerifier(if PKCE client-managed)
Client -> Server (OAuthExchangeRequest):
requestIdproviderauthorizationCodestatecodeVerifier(if PKCE)
Server -> Client (OAuthExchangeResponse):
requestIdsuccessaccessTokenrefreshTokenexpiresAtUtcaccountSummaryerrorCode(if failed)
3.7 MainMenu
Client
- Display entry points:
- Ranked Play
- Custom Play
- Collection
- Bazaar
- Account Management
- Settings
- Leaderboard
- Log Out
- Admin (only if authorized)
- Show account profile and key notifications.
Server
- Return entitlement/role-based menu permissions.
- Return badge counts (rewards, inbox, moderation flags, etc.).
- Return feature flags for visible modules.
Data Exchange
Client -> Server (MainMenuBootstrapRequest):
requestIdaccountIdclientVersion
Server -> Client (MainMenuBootstrapResponse):
requestIdprofileSummaryroles(player,admin, etc.)featureFlagsmenuPermissionsnotificationCountsrankedSummary(current rank, season id)
3.8 AccountManagement
Client
- Display identity/profile details and account-linked providers.
- Support password update via modal workflow.
- Display account stats and spending summary with default-censored totals.
- Allow uncensor toggle for spending values.
- Provide export action for full spending profile report.
- Show legal document links (TOS, EULA, related policies).
Server
- Return account profile, linked OAuth providers, and player/account stats.
- Process password change requests.
- Return spending summary fields and detailed spending report export.
- Return legal document metadata and URLs.
Data Exchange
Client -> Server (AccountOverviewRequest):
requestIdaccountId
Server -> Client (AccountOverviewResponse):
requestIdusernameemailprofileImageUrllinkedProvidersstats:originPointswinslossesforfeitsdrawscardsOwnedcardsPlayed
spendingSummary:moneySpentoriginPointsSpentcensoredByDefault(true)
legalDocuments(name + url)
Client -> Server (ChangePasswordRequest):
requestIdcurrentPassword(if policy requires)newPasswordconfirmPassword
Server -> Client (ChangePasswordResponse):
requestIdsuccesserrorCode(if failed)
Client -> Server (LinkOAuthRequest):
requestIdprovider
Server -> Client (LinkOAuthResponse):
requestIdsuccesslinkedProviderserrorCode(if failed)
Client -> Server (SpendingReportRequest):
requestIdformat(csv,json,pdf)
Server -> Client (SpendingReportResponse):
requestIdsuccessdownloadUrlexpiresAtUtcerrorCode(if failed)
3.9 Collection (Hub Scene)
Client
- Load owned cards, deck list, cosmetics.
- Provide tabs/sub-scenes:
DeckEditorCardViewerCosmetics
Server
- Return collection inventory + ownership states.
- Return deck metadata and validation rules.
- Return unlocked/purchasable card backs, trims, and art/model variants.
Data Exchange
Client -> Server (CollectionBootstrapRequest):
requestIdaccountIdincludeInventoryincludeDecksincludeCosmetics
Server -> Client (CollectionBootstrapResponse):
requestIdcardInventory(card definition id + ownership/quantity + variants owned)deckSummariescosmeticInventorycollectionStatsrulesVersion
3.10 DeckEditor
Client
- Build/edit decks with full filtering and sorting.
- Validate deck locally with server rule mirror.
- Save, duplicate, rename, delete deck.
Server
- Validate deck against current legal format/rules.
- Persist deck revisions and return canonical saved state.
Data Exchange
Client -> Server (DeckValidateRequest):
requestIddeckDraftformatId
Server -> Client (DeckValidateResponse):
requestIdisValiderrorswarnings
Client -> Server (DeckSaveRequest):
requestIddeckId(optional for new deck)deckNamedeckCards(card instance ids or definition ids + quantity model)formatId
Server -> Client (DeckSaveResponse):
requestIdsuccessdeckIddeckRevisionisValiderrors(if invalid/rejected)
3.11 CardViewer
Client
- Browse card library and owned-only views.
- Apply filters/sorts:
- Type, affinity, cost, rarity, owned/unowned, set, text search.
- View alternate art/model versions.
Server
- Return searchable card metadata and ownership projection.
- Return art/model variant manifests.
Data Exchange
Client -> Server (CardSearchRequest):
requestIdqueryfilterssortpagepageSize
Server -> Client (CardSearchResponse):
requestIdresultstotalCountfacets
3.12 Cosmetics (Card Back / Trim / Variant Selection)
Client
- Display available card back/trim options and card-specific art/model variants.
- Preview and equip selections.
Server
- Verify ownership and compatibility for selected cosmetic.
- Persist equipped defaults and per-card overrides.
Data Exchange
Client -> Server (CosmeticEquipRequest):
requestIdscope(globalDeckDefault,cardDefinition,cardInstance)targetIdcardBackId(optional)trimId(optional)artVariantId(optional)modelVariantId(optional)
Server -> Client (CosmeticEquipResponse):
requestIdsuccessequippedStateerrorCode(if failed)
3.13 Global Input Consistency Rules
- Multi-touch support is required for touch-capable devices.
- Core camera gestures and selection semantics are shared across all scenes.
- Scene-specific controls may add actions, but must not override baseline navigation behavior.
- Input remapping and accessibility options should apply globally, not per-scene.
4) Security and Validation Baseline
- Server authoritative for:
- Account identity/session state
- Collection ownership
- Deck legality
- Cosmetic entitlement
- Client authoritative for:
- Local scene rendering
- Non-authoritative UI filtering/sorting state
- Every mutating request requires:
- valid access token
- account ownership check
- anti-replay safeguards (
requestId, timestamp window)
5) Next Draft Targets
- Ranked Play scene breakdown and matchmaking payload contracts.
- Custom Play lobby + room state contracts.
- Bazaar transaction flow and inventory mutation rules.
- Settings scene-level data model and interactions.
- Admin scene contracts and role-gated operations.