# claabs/epicgames-freegames-node architecture

> Architecture diagram of the GitHub repository claabs/epicgames-freegames-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/claabs/epicgames-freegames-node
- Repository: https://github.com/claabs/epicgames-freegames-node

## Overview

Epic Games Store Weekly Free Games automates account login, discovers free offers, checks whether they can be claimed, and provides a prepopulated checkout link for the user to finish checkout. Scheduled runs can request device-code login through a web redirect, retain account sessions, handle EULA acceptance, and send notifications through configurable channels. The graph preserves these stages and the documented server/localtunnel and notifier capabilities. Unsampled modules are included where the README or source index establishes their role; edges are limited to documented workflow or visible calls.

Main entry points: [`src/index.ts`](https://github.com/claabs/epicgames-freegames-node/blob/master/src/index.ts) (Application workflow), [`src/device-login.ts`](https://github.com/claabs/epicgames-freegames-node/blob/master/src/device-login.ts) (Device login), [`src/puppet/free-games.ts`](https://github.com/claabs/epicgames-freegames-node/blob/master/src/puppet/free-games.ts) (Free-game discovery), [`src/notify.ts`](https://github.com/claabs/epicgames-freegames-node/blob/master/src/notify.ts) (Notification dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_app["Application workflow<br/>[index.ts]"]
  node_config["Configuration<br/>[setup.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
end

subgraph group_accounts["Accounts and access"]
  node_device_login["Device login<br/>[device-login.ts]"]
  node_auth_store[("Device auth storage<br/>[device-auths.ts]")]
  node_epic_auth["Epic authentication"]
end

subgraph group_offers["Offer discovery"]
  node_puppet_base["Store browser base<br/>[base.ts]"]
  node_free_games["Free-game discovery<br/>[free-games.ts]"]
  node_store_models["Store response models<br/>[product-info.ts]"]
  node_epic_store["Epic Store APIs"]
end

subgraph group_checkout["Checkout readiness"]
  node_eula["EULA management<br/>[eula-manager.ts]"]
  node_purchase["Checkout link<br/>[purchase.ts]"]
end

subgraph group_delivery["Web and notifications"]
  node_web_server["Login redirect server<br/>[server.ts]"]
  node_tunnel["Localtunnel access<br/>[localtunnel.ts]"]
  node_notifications["Notification dispatch<br/>[notify.ts]"]
  node_notifier_adapters["Notifier adapters<br/>[index.ts]"]
  node_notifier_service["Notifier contract"]
  node_notification_services["Notification services"]
end

node_user(("User"))
node_runner(("Scheduled runner"))

node_runner -->|"starts runs"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"orchestrates login"| node_device_login
node_app -->|"orchestrates search"| node_free_games
node_app -->|"orchestrates EULAs"| node_eula
node_app -->|"orchestrates notices"| node_notifications
node_device_login -->|"registers redirects"| node_web_server
node_device_login -->|"gets tunnel URL"| node_tunnel
node_device_login -->|"sends login notices"| node_notifications
node_device_login -->|"reads and saves tokens"| node_auth_store
node_device_login -->|"requests device auth"| node_epic_auth
node_user -->|"follows login redirect"| node_web_server
node_user -->|"completes login"| node_epic_auth
node_puppet_base -.->|"requests store data"| node_epic_store
node_free_games -->|"uses browser base"| node_puppet_base
node_free_games -->|"uses response types"| node_store_models
node_free_games -->|"queries free offers"| node_epic_store
node_eula -->|"generates login link"| node_purchase
node_eula -->|"sends EULA notice"| node_notifications
node_user -->|"finishes checkout"| node_purchase
node_notifications -->|"selects adapters"| node_notifier_adapters
node_notifier_adapters -->|"implements contract"| node_notifier_service
node_notifier_adapters -.->|"delivers notices"| node_notification_services

click node_app "https://github.com/claabs/epicgames-freegames-node/blob/master/src/index.ts"
click node_config "https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/config/setup.ts"
click node_logger "https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/logger.ts"
click node_device_login "https://github.com/claabs/epicgames-freegames-node/blob/master/src/device-login.ts"
click node_auth_store "https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/device-auths.ts"
click node_web_server "https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/server.ts"
click node_tunnel "https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/localtunnel.ts"
click node_puppet_base "https://github.com/claabs/epicgames-freegames-node/blob/master/src/puppet/base.ts"
click node_free_games "https://github.com/claabs/epicgames-freegames-node/blob/master/src/puppet/free-games.ts"
click node_store_models "https://github.com/claabs/epicgames-freegames-node/blob/master/src/interfaces/product-info.ts"
click node_eula "https://github.com/claabs/epicgames-freegames-node/blob/master/src/eula-manager.ts"
click node_purchase "https://github.com/claabs/epicgames-freegames-node/blob/master/src/purchase.ts"
click node_notifications "https://github.com/claabs/epicgames-freegames-node/blob/master/src/notify.ts"
click node_notifier_adapters "https://github.com/claabs/epicgames-freegames-node/blob/master/src/notifiers/index.ts"
click node_notifier_service "https://github.com/claabs/epicgames-freegames-node/blob/master/src/notifiers/notifier-service.ts"

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_app,node_config,node_logger,node_user toneBlue
class node_device_login,node_auth_store,node_epic_auth toneAmber
class node_puppet_base,node_free_games,node_store_models,node_epic_store toneMint
class node_eula,node_purchase toneRose
class node_web_server,node_tunnel,node_notifications,node_notifier_adapters,node_notifier_service,node_notification_services,node_runner toneIndigo
```

## Components

### Run orchestration

- [Application workflow](https://github.com/claabs/epicgames-freegames-node/blob/master/src/index.ts): `src/index.ts`
- [Configuration](https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/config/setup.ts): `src/common/config/setup.ts`
- [Logging](https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/logger.ts): `src/common/logger.ts`

### Accounts and access

- [Device login](https://github.com/claabs/epicgames-freegames-node/blob/master/src/device-login.ts): `src/device-login.ts`
- [Device auth storage](https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/device-auths.ts): `src/common/device-auths.ts`
- **Epic authentication**

### Offer discovery

- [Store browser base](https://github.com/claabs/epicgames-freegames-node/blob/master/src/puppet/base.ts): `src/puppet/base.ts`
- [Free-game discovery](https://github.com/claabs/epicgames-freegames-node/blob/master/src/puppet/free-games.ts): `src/puppet/free-games.ts`
- [Store response models](https://github.com/claabs/epicgames-freegames-node/blob/master/src/interfaces/product-info.ts): `src/interfaces/product-info.ts`
- **Epic Store APIs**

### Checkout readiness

- [EULA management](https://github.com/claabs/epicgames-freegames-node/blob/master/src/eula-manager.ts): `src/eula-manager.ts`
- [Checkout link](https://github.com/claabs/epicgames-freegames-node/blob/master/src/purchase.ts): `src/purchase.ts`

### Web and notifications

- [Login redirect server](https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/server.ts): `src/common/server.ts`
- [Localtunnel access](https://github.com/claabs/epicgames-freegames-node/blob/master/src/common/localtunnel.ts): `src/common/localtunnel.ts`
- [Notification dispatch](https://github.com/claabs/epicgames-freegames-node/blob/master/src/notify.ts): `src/notify.ts`
- [Notifier adapters](https://github.com/claabs/epicgames-freegames-node/blob/master/src/notifiers/index.ts): `src/notifiers/index.ts`
- [Notifier contract](https://github.com/claabs/epicgames-freegames-node/blob/master/src/notifiers/notifier-service.ts): `src/notifiers/notifier-service.ts`
- **Notification services**

### Other components

- **User**
- **Scheduled runner**

## Connections

- Scheduled runner → Application workflow: starts runs
- Application workflow → Configuration: loads settings (evidence: `src/index.ts`)
- Application workflow → Device login: orchestrates login (evidence: `src/index.ts`)
- Application workflow → Free-game discovery: orchestrates search (evidence: `src/index.ts`)
- Application workflow → EULA management: orchestrates EULAs (evidence: `src/index.ts`)
- Application workflow → Notification dispatch: orchestrates notices (evidence: `src/index.ts`)
- Device login → Login redirect server: registers redirects (evidence: `src/device-login.ts`)
- Device login → Localtunnel access: gets tunnel URL (evidence: `src/device-login.ts`)
- Device login → Notification dispatch: sends login notices (evidence: `src/device-login.ts`)
- Device login → Device auth storage: reads and saves tokens (evidence: `src/device-login.ts`)
- Device login → Epic authentication: requests device auth (evidence: `src/device-login.ts`)
- User → Login redirect server: follows login redirect
- User → Epic authentication: completes login
- Store browser base → Epic Store APIs: requests store data
- Free-game discovery → Store browser base: uses browser base (evidence: `src/puppet/free-games.ts`)
- Free-game discovery → Store response models: uses response types (evidence: `src/puppet/free-games.ts`)
- Free-game discovery → Epic Store APIs: queries free offers (evidence: `src/puppet/free-games.ts`)
- EULA management → Checkout link: generates login link (evidence: `src/eula-manager.ts`)
- EULA management → Notification dispatch: sends EULA notice (evidence: `src/eula-manager.ts`)
- User → Checkout link: finishes checkout
- Notification dispatch → Notifier adapters: selects adapters (evidence: `src/notify.ts`)
- Notifier adapters → Notifier contract: implements contract (evidence: `src/notifiers/index.ts`)
- Notifier adapters → Notification services: delivers notices