# havok9802/claimsync-for-epic-games architecture

> Architecture diagram of the GitHub repository havok9802/claimsync-for-epic-games, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/havok9802/claimsync-for-epic-games
- Repository: https://github.com/havok9802/claimsync-for-epic-games

## Overview

#### Purpose and topology
ClaimSync is a self-hosted Epic Games automation system: a Node.js server detects and claims weekly free games, synchronizes user libraries, and sends push notifications; an Android Kotlin/Compose client configures accounts and displays results. Docker supports deployment. Primary runtime roots are `server/src/core/server.js`, `client/app/src/main/java/com/client/claimsync/ClaimSyncApplication.kt`, and `compose.yml`.

#### Server API and scheduling
The Node server exposes application and diagnostic routes, then coordinates recurring jobs through its scheduler. These are the server control-plane entry points and likely invoke script work per user:
- `server/src/core/server.js`
- `server/src/core/routes.mjs`
- `server/src/core/scheduler.mjs`
- `server/src/core/testRoutes.mjs`

#### Epic automation pipeline
Playwright-oriented scripts are the boundary to Epic Games Store. The pipeline scrapes current offers, authenticates to Epic, claims available titles, retrieves library contents, and fetches imagery/posters. Scripts write operational results to the cloud-backed data model rather than being called directly by the Android client:
- `server/src/scripts/scrape-free-games-this-week.mjs`
- `server/src/scripts/epic-games-login.mjs`
- `server/src/scripts/free-game-claimer.mjs`
- `server/src/scripts/scrape-games-from-library.mjs`

#### Cloud state, identity, notifications, and secrets
Firebase is the shared backend: Firebase Authentication identifies users; Firestore holds common weekly games, per-user Epic state/library, and FCM tokens; FCM delivers notifications. Server cloud and notification adapters centralize these external boundaries. Google Cloud Secret Manager is used for sensitive data, while OpenSSL-based materials can be generated locally:
- `server/src/util/cloud.mjs`
- `server/src/util/notification.mjs`
- `key_and_cert_generation/generate_keys_and_cert.sh`
- `key_and_cert_generation/Dockerfile`

#### Android application shell
The Android app is a multi-module Compose application. `ClaimSyncApplication` initializes app-wide dependencies, `ClaimSyncActivity` hosts UI/navigation, and the app view model coordinates top-level state. Bottom navigation routes users across the feature modules:
- `client/app/src/main/java/com/client/claimsync/ClaimSyncApplication.kt`
- `client/app/src/main/java/com/client/claimsync/ClaimSyncActivity.kt`
- `client/app/src/main/java/com/client/claimsync/navigation/Route.kt`

#### Client domain boundaries
Feature modules use presentation ViewModels/actions/events → use cases → repository interfaces/implementations, separating Compose UI from Firebase/network/storage details. The main user flows are weekly-offer discovery/claiming, synced-library viewing, profile/Epic-key and notification preferences, and MFA choice:
- `client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt`
- `client/feature/gameLibrary/src/main/java/com/client/gamelibrary/presentation/GameLibraryScreenViewModel.kt`
- `client/feature/profileSettings/src/main/java/com/client/profilesettings/presentation/ProfileSettingsViewModel.kt`
- `client/feature/mfaRelay/src/main/java/com/example/mfarelay/data/MfaRelayService.kt`

#### Client infrastructure and sensitive flows
Core modules encapsulate Google/Firebase authentication, authenticated API invocation/connectivity, FCM token lifecycle, local DataStore/Room state, encryption, and MFA relay. MFA supports SMS reception and TOTP/QR-derived secrets; crypto protects secrets before persistence or transmission. The network layer supplies API services and an auth interceptor, creating the Android-to-server boundary:
- `client/core/auth/src/main/java/com/client/auth/data/source/GoogleAuthDataSource.kt`
- `client/core/network/src/main/java/com/client/network/data/service/ApiService.kt`
- `client/core/network/src/main/java/com/client/network/util/AuthInterceptor.kt`
- `client/core/storage/src/main/java/com/client/storage/data/local/room/ClaimSyncDatabase.kt`
- `client/core/crypto/src/main/java/com/example/crypto/ClaimSyncSecretManager.kt`
- `client/core/notification/src/main/java/com/client/notification/service/ClaimSyncNotificationService.kt`

Main entry points: [`server/src/core/server.js`](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/server.js) (Server bootstrap), [`server/src/scripts/free-game-claimer.mjs`](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/free-game-claimer.mjs) (Epic automation pipeline), [`client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt`](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt) (Feature view models), [`server/src/core/scheduler.mjs`](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/scheduler.mjs) (Recurring job scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Node.js automation server"]
  node_server["Server bootstrap<br/>Node runtime<br/>[server.js]"]
  node_routes["App routes<br/>HTTP routes<br/>[routes.mjs]"]
  node_diagnostics["Diagnostic routes<br/>HTTP routes<br/>[testRoutes.mjs]"]
  node_scheduler["Recurring job scheduler<br/>[scheduler.mjs]"]
  node_epic_pipeline["Epic automation pipeline<br/>Playwright scripts"]
  node_offers["Weekly offer scraper<br/>Epic scraper"]
  node_epic_login["Epic login<br/>Epic auth automation"]
  node_library_sync["Library scraper<br/>Epic scraper"]
  node_cloud_adapter["Firebase data adapter<br/>Cloud adapter<br/>[cloud.mjs]"]
  node_notification_adapter["Notification adapter<br/>FCM adapter<br/>[notification.mjs]"]
end

subgraph group_cloud["Cloud services"]
  node_firebase[("Firebase<br/>Auth, Firestore, FCM")]
  node_secrets[("Google Secret Manager<br/>Secret store")]
end

subgraph group_android["Android Compose client"]
  node_android_app["Application bootstrap<br/>Android application"]
  node_android_ui["Activity and navigation<br/>Compose shell"]
  node_routes_client["Bottom-nav routes<br/>Navigation model<br/>[Route.kt]"]
  node_features["Feature view models<br/>Presentation layer"]
  node_client_auth["Google auth source<br/>Firebase auth"]
  node_api["Authenticated API client<br/>Network boundary<br/>[ApiService.kt]"]
  node_storage_crypto[("Local secure state<br/>Room and crypto")]
  node_push["Push notification service<br/>FCM client"]
  node_mfa["MFA relay<br/>MFA service<br/>[MfaRelayService.kt]"]
end

node_compose{{"Docker deployment<br/>Compose deployment<br/>[compose.yml]"}}
node_keygen["Key and cert generator<br/>OpenSSL container"]

node_compose -->|"runs"| node_server
node_server -->|"serves"| node_routes
node_server -->|"serves"| node_diagnostics
node_server -->|"starts"| node_scheduler
node_scheduler -->|"triggers"| node_epic_pipeline
node_epic_pipeline -->|"scrapes"| node_offers
node_epic_pipeline -->|"authenticates"| node_epic_login
node_epic_pipeline -->|"syncs"| node_library_sync
node_epic_pipeline -->|"writes results"| node_cloud_adapter
node_cloud_adapter -->|"uses"| node_firebase
node_scheduler -->|"notifies"| node_notification_adapter
node_notification_adapter -->|"sends via FCM"| node_firebase
node_server -->|"reads secrets"| node_secrets
node_keygen -.->|"generates materials for"| node_secrets
node_android_app -->|"initializes"| node_android_ui
node_android_ui -->|"navigates"| node_routes_client
node_routes_client -->|"hosts flows"| node_features
node_features -->|"invokes"| node_api
node_api -->|"authenticated requests"| node_routes
node_client_auth -->|"signs in"| node_firebase
node_features -->|"reads and protects state"| node_storage_crypto
node_features -->|"uses"| node_mfa
node_push -->|"registers token"| node_firebase

click node_compose "https://github.com/havok9802/claimsync-for-epic-games/blob/master/compose.yml"
click node_server "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/server.js"
click node_routes "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/routes.mjs"
click node_diagnostics "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/testRoutes.mjs"
click node_scheduler "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/scheduler.mjs"
click node_epic_pipeline "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/free-game-claimer.mjs"
click node_offers "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/scrape-free-games-this-week.mjs"
click node_epic_login "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/epic-games-login.mjs"
click node_library_sync "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/scrape-games-from-library.mjs"
click node_cloud_adapter "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/util/cloud.mjs"
click node_notification_adapter "https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/util/notification.mjs"
click node_keygen "https://github.com/havok9802/claimsync-for-epic-games/blob/master/key_and_cert_generation/Dockerfile"
click node_android_app "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/ClaimSyncApplication.kt"
click node_android_ui "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/ClaimSyncActivity.kt"
click node_routes_client "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/navigation/Route.kt"
click node_features "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt"
click node_client_auth "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/auth/src/main/java/com/client/auth/data/source/GoogleAuthDataSource.kt"
click node_api "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/network/src/main/java/com/client/network/data/service/ApiService.kt"
click node_storage_crypto "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/storage/src/main/java/com/client/storage/data/local/room/ClaimSyncDatabase.kt"
click node_push "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/notification/src/main/java/com/client/notification/service/ClaimSyncNotificationService.kt"
click node_mfa "https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/feature/mfaRelay/src/main/java/com/example/mfarelay/data/MfaRelayService.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_routes,node_diagnostics,node_scheduler,node_epic_pipeline,node_offers,node_epic_login,node_library_sync,node_cloud_adapter,node_notification_adapter toneBlue
class node_firebase,node_secrets toneAmber
class node_android_app,node_android_ui,node_routes_client,node_features,node_client_auth,node_api,node_storage_crypto,node_push,node_mfa toneMint
class node_compose,node_keygen toneNeutral
```

## Components

### Node.js automation server

- [Server bootstrap](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/server.js): Node runtime · `server/src/core/server.js`
- [App routes](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/routes.mjs): HTTP routes · `server/src/core/routes.mjs`
- [Diagnostic routes](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/testRoutes.mjs): HTTP routes · `server/src/core/testRoutes.mjs`
- [Recurring job scheduler](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/core/scheduler.mjs): Scheduler · `server/src/core/scheduler.mjs`
- [Epic automation pipeline](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/free-game-claimer.mjs): Playwright scripts · Scrapes offers, signs in, claims games, and syncs libraries. · `server/src/scripts/free-game-claimer.mjs`
- [Weekly offer scraper](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/scrape-free-games-this-week.mjs): Epic scraper · `server/src/scripts/scrape-free-games-this-week.mjs`
- [Epic login](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/epic-games-login.mjs): Epic auth automation · `server/src/scripts/epic-games-login.mjs`
- [Library scraper](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/scripts/scrape-games-from-library.mjs): Epic scraper · `server/src/scripts/scrape-games-from-library.mjs`
- [Firebase data adapter](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/util/cloud.mjs): Cloud adapter · Persists shared offers and per-user Epic state. · `server/src/util/cloud.mjs`
- [Notification adapter](https://github.com/havok9802/claimsync-for-epic-games/blob/master/server/src/util/notification.mjs): FCM adapter · `server/src/util/notification.mjs`

### Cloud services

- **Firebase**: Auth, Firestore, FCM · Shared identity, state, device tokens, and push delivery.
- **Google Secret Manager**: Secret store

### Android Compose client

- [Application bootstrap](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/ClaimSyncApplication.kt): Android application · `client/app/src/main/java/com/client/claimsync/ClaimSyncApplication.kt`
- [Activity and navigation](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/ClaimSyncActivity.kt): Compose shell · `client/app/src/main/java/com/client/claimsync/ClaimSyncActivity.kt`
- [Bottom-nav routes](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/app/src/main/java/com/client/claimsync/navigation/Route.kt): Navigation model · `client/app/src/main/java/com/client/claimsync/navigation/Route.kt`
- [Feature view models](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt): Presentation layer · Coordinates weekly offers, library, profile, and MFA flows. · `client/feature/weeklyfreegames/src/main/java/com/client/weeklyfreegames/presentation/WeeklyFreeGamesViewModel.kt`
- [Google auth source](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/auth/src/main/java/com/client/auth/data/source/GoogleAuthDataSource.kt): Firebase auth · `client/core/auth/src/main/java/com/client/auth/data/source/GoogleAuthDataSource.kt`
- [Authenticated API client](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/network/src/main/java/com/client/network/data/service/ApiService.kt): Network boundary · `client/core/network/src/main/java/com/client/network/data/service/ApiService.kt`
- [Local secure state](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/storage/src/main/java/com/client/storage/data/local/room/ClaimSyncDatabase.kt): Room and crypto · Stores local state and protects sensitive values. · `client/core/storage/src/main/java/com/client/storage/data/local/room/ClaimSyncDatabase.kt`
- [Push notification service](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/core/notification/src/main/java/com/client/notification/service/ClaimSyncNotificationService.kt): FCM client · `client/core/notification/src/main/java/com/client/notification/service/ClaimSyncNotificationService.kt`
- [MFA relay](https://github.com/havok9802/claimsync-for-epic-games/blob/master/client/feature/mfaRelay/src/main/java/com/example/mfarelay/data/MfaRelayService.kt): MFA service · Handles SMS and TOTP/QR-derived secrets. · `client/feature/mfaRelay/src/main/java/com/example/mfarelay/data/MfaRelayService.kt`

### Other components

- [Docker deployment](https://github.com/havok9802/claimsync-for-epic-games/blob/master/compose.yml): Compose deployment · `compose.yml`
- [Key and cert generator](https://github.com/havok9802/claimsync-for-epic-games/blob/master/key_and_cert_generation/Dockerfile): OpenSSL container · `key_and_cert_generation/Dockerfile`

## Connections

- Docker deployment → Server bootstrap: runs
- Server bootstrap → App routes: serves
- Server bootstrap → Diagnostic routes: serves
- Server bootstrap → Recurring job scheduler: starts
- Recurring job scheduler → Epic automation pipeline: triggers
- Epic automation pipeline → Weekly offer scraper: scrapes
- Epic automation pipeline → Epic login: authenticates
- Epic automation pipeline → Library scraper: syncs
- Epic automation pipeline → Firebase data adapter: writes results
- Firebase data adapter → Firebase: uses
- Recurring job scheduler → Notification adapter: notifies
- Notification adapter → Firebase: sends via FCM
- Server bootstrap → Google Secret Manager: reads secrets
- Key and cert generator → Google Secret Manager: generates materials for
- Application bootstrap → Activity and navigation: initializes
- Activity and navigation → Bottom-nav routes: navigates
- Bottom-nav routes → Feature view models: hosts flows
- Feature view models → Authenticated API client: invokes
- Authenticated API client → App routes: authenticated requests
- Google auth source → Firebase: signs in
- Feature view models → Local secure state: reads and protects state
- Feature view models → MFA relay: uses
- Push notification service → Firebase: registers token