havok9802/claimsync-for-epic-games

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