# arcomage/arcomage-hd architecture

> Architecture diagram of the GitHub repository arcomage/arcomage-hd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arcomage/arcomage-hd
- Repository: https://github.com/arcomage/arcomage-hd

## Overview

##### Project type and purpose
- This is a front-end-only, browser-based full-stack "application" (no custom backend) implementing a Progressive Web App (PWA) card game.
- Its purpose is to render a real-time, turn-based card game (ArcoMage HD), support AI opponents, and enable peer-to-peer multiplayer via WebRTC.

##### File structure
- Top-level “src” contains application code, split into:
- components (UI/React)
- reducers (Redux state slices)
- epics (redux-observable side-effects with RxJS)
- ai (CPU decision logic)
- webrtc (PeerJS wrapper and STUN config)
- i18n (internationalization contexts and locale data)
- utils (hooks, helpers)
- “store.tsx” wires Redux store + middleware (epics).
- “index.tsx” bootstraps React app and registers the PWA service worker (Workbox).
- “assets” and “public” (index.html) feed into the Vite/Bun build.
- “tools/” contains dev scripts for data processing, i18n extraction, asset generation (not run in production).
- Configuration files (tsconfig.json, vite.config.ts, bunfig.toml) set up transpilation/bundling.

##### README for additional insights
- Tech stack: TypeScript, React, Redux, redux-observable, RxJS, WebRTC (PeerJS), Workbox PWA.
- Multiplayer Mode: P2P via STUN servers + PeerJS signaling, no custom server after handshake.
- Offline support: Service Worker caches assets, data, settings for offline play.
- AI Mode: Local synchronous computation (ai module).

a. Main components to include:
- Browser & User Device
- React UI layer (components)
- Redux Store (state) & Reducers
- Epics (redux-observable/RxJS side-effects)
- AI Engine (ai module)
- Networking Layer (PeerJS client, STUN servers, signaling server)
- PWA Service Worker (Workbox cache) & Cache Storage
- Assets (images, audio, localization)
b. Relationships & interactions:
- User inputs → React events → dispatch Redux actions
- Actions → Reducers update Store → UI re-renders
- Selected actions → Epics intercept → async flows:
– AI Epic: reads state, runs ai.getMaxScore, dispatches move actions
– Multiplayer Epics: send/receive over WebRTC → dispatch remote actions
- On load: Service Worker intercepts fetch requests, serves from Cache or Network
- PeerJS: initial handshake via signaling server → STUN servers → direct P2P channel
c. Architectural patterns & principles:
- Flux pattern (unidirectional data flow)
- Reactive programming (RxJS Observables in Epics)
- Modular separation: UI / State / Side-Effects / Domain logic (AI/Multiplayer)
- PWA pattern: offline first, caching strategies
d. Key technologies & libraries:
- React + CSS Modules / SCSS / Tailwind for UI
- Redux for state management
- redux-observable & RxJS for orchestrating async and side-effects
- PeerJS + WebRTC (STUN + signaling) for P2P networking
- Workbox for service worker and caching
- Vite + Bun for bundling and dev server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser & PWA Layer
    subgraph "Browser & PWA"
        SW["Service Worker"]:::cache
        CS["Cache Storage"]:::cache
        SW --> CS
        SW -->|Intercepts Requests| Net["Network"]:::network
    end

    %% UI Layer
    subgraph "UI Layer"
        UI["React Components"]:::ui
        I18nCtx["I18n Context & Provider"]:::i18n
    end

    %% State Layer
    subgraph "State Layer"
        Store["Redux Store"]:::state
        Reducers["Reducers (State Slices)"]:::state
    end

    %% Side-Effects Layer
    subgraph "Epics (redux-observable)" 
        EpicIndex["Epic Entry Point"]:::side
        CardsEpics["Cards Epics"]:::side
        GameEpics["Game General Epics"]:::side
        MultiplayerEpics["Multiplayer Epics"]:::side
        ScreenEpics["Screen Epics"]:::side
        SettingsEpics["Settings/Lang Epics"]:::side
        StatusEpics["Status Epics"]:::side
    end

    %% AI Engine
    subgraph "AI Engine"
        AIMain["Main AI Flow"]:::ai
        AIGetMax["Core Scoring (getMaxScore)"]:::ai
        AICheck["checkCardUseDiscard"]:::ai
        AICoefs["coefs"]:::ai
    end

    %% Networking Layer
    subgraph "Networking"
        PeerClient["PeerJS Client"]:::network
        STUN["STUN/ICE List"]:::network
        Signaling["Signaling Server"]:::network
    end

    %% Assets & i18n & Utils & Build
    subgraph "Assets"
        CardImg["Card Images"]:::asset
        SFX["Sound Effects"]:::asset
        Fonts["Fonts"]:::asset
    end

    subgraph "Internationalization"
        CardLocales["Card Text Locales"]:::i18n
        UIText["UI Text Locales"]:::i18n
    end

    subgraph "Utilities"
        UtilsGen["General Utils"]:::util
        Hooks["Game Controls Hooks"]:::util
        MPQueues["Multiplayer Queues"]:::util
        SoundUtils["Sound Helpers"]:::util
        Contexts["Context Providers"]:::util
    end

    subgraph "Build & Tooling"
        TSConfig["tsconfig.json"]:::tool
        BunConfig["bunfig.toml & bun.lock"]:::tool
        ViteConfig["vite.config.ts"]:::tool
        ESLint["eslint.config.js"]:::tool
        StyleLint["stylelint.config.js"]:::tool
        Prettier[".prettierrc.js"]:::tool
    end

    %% Interactions
    User["User"]:::external
    User -->|Interacts| UI
    UI -->|dispatch| Store
    Store -->|subscribe| UI
    Store -->|actions| EpicIndex
    EpicIndex --> CardsEpics
    EpicIndex --> GameEpics
    EpicIndex --> MultiplayerEpics
    EpicIndex --> ScreenEpics
    EpicIndex --> SettingsEpics
    EpicIndex --> StatusEpics

    GameEpics -->|runs| AIMain
    AIMain --> AIGetMax
    AIMain --> AICheck
    AIMain --> AICoefs
    AIMain -->|dispatch move| Store

    MultiplayerEpics -->|PeerJS calls| PeerClient
    PeerClient --> STUN
    PeerClient --> Signaling
    PeerClient -->|P2P Channel| PeerClient
    MultiplayerEpics -->|dispatch remote action| Store

    UI --> I18nCtx
    I18nCtx --> CardLocales
    I18nCtx --> UIText

    UI --> CardImg
    UI --> SFX
    UI --> Fonts

    UI --> UtilsGen
    UI --> Hooks
    UI --> MPQueues
    UI --> SoundUtils
    UI --> Contexts

    index["App Entry & SW Registration"]:::cache --> SW
    index -->|loads assets| CardImg
    ViteConfig -->|configures PWA| SW

    %% Click events
    click UI "https://github.com/arcomage/arcomage-hd/tree/main/src/components/"
    click Store "https://github.com/arcomage/arcomage-hd/blob/main/src/store.tsx"
    click Reducers "https://github.com/arcomage/arcomage-hd/tree/main/src/reducers/"
    click EpicIndex "https://github.com/arcomage/arcomage-hd/blob/main/src/epics/index.ts"
    click CardsEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/cards/"
    click GameEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/game_general/"
    click MultiplayerEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/multiplayer/"
    click ScreenEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/screen/"
    click SettingsEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/settings_lang_etc/"
    click StatusEpics "https://github.com/arcomage/arcomage-hd/tree/main/src/epics/status/"
    click AIMain "https://github.com/arcomage/arcomage-hd/blob/main/src/ai/main.ts"
    click AIGetMax "https://github.com/arcomage/arcomage-hd/blob/main/src/ai/getMaxScore.ts"
    click AICheck "https://github.com/arcomage/arcomage-hd/blob/main/src/ai/checkCardUseDiscard.ts"
    click AICoefs "https://github.com/arcomage/arcomage-hd/blob/main/src/ai/coefs.ts"
    click PeerClient "https://github.com/arcomage/arcomage-hd/blob/main/src/webrtc/peer.ts"
    click STUN "https://github.com/arcomage/arcomage-hd/blob/main/src/webrtc/icelist.ts"
    click index "https://github.com/arcomage/arcomage-hd/blob/main/src/index.tsx"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#000,stroke-width:1px
    classDef state fill:#d9ead3,stroke:#000,stroke-width:1px
    classDef side fill:#f9cb9c,stroke:#000,stroke-width:1px
    classDef ai fill:#ffe599,stroke:#000,stroke-width:1px
    classDef network fill:#f4cccc,stroke:#000,stroke-width:1px
    classDef cache fill:#d9d9d9,stroke:#000,stroke-width:1px
    classDef asset fill:#ead1dc,stroke:#000,stroke-width:1px
    classDef i18n fill:#b4a7d6,stroke:#000,stroke-width:1px
    classDef util fill:#fff2cc,stroke:#000,stroke-width:1px
    classDef tool fill:#c9daf8,stroke:#000,stroke-width:1px
    classDef external fill:#cccccc,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
