# freezingmoon/ancientbeast architecture

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

- Interactive diagram: https://gitdiagram.com/freezingmoon/ancientbeast
- Repository: https://github.com/freezingmoon/ancientbeast

## Overview

##### Project type and purpose
- This is a browser-based, single-page turn-based strategy game (Ancient Beast).
- It’s built with TypeScript/JavaScript and Phaser for rendering, packaged via Webpack, and played online (PWA support via service worker).
- There is client-side logic only; multiplayer relies on external servers (WebSocket/API).

##### File structure
- Top-level build & config: Dockerfile, .env.example, webpack.config.js, tsconfig.json, Babel, ESLint, Prettier, Husky.
- Source code (“src/”):
- Core game modules: game.ts, creature.ts, effect.ts, drop.ts, damage.ts, etc.
- Abilities under “src/abilities/”, data under “src/data/”.
- UI under “src/ui/”: buttons, chat, interface, progress bars, etc.
- Multiplayer under “src/multiplayer/”: authentication, connection, gameplay, session management.
- Sound under “src/sound/”: buffer loader, music player, sound system, pre-match audio.
- Templates in “src/templates/” for analytics snippet, service worker registration.
- Utility under “src/utility/”: math, pathfinding, grid utilities, versioning, constants.
- Styles under “src/style/”: LESS/CSS for cards, grids, skin, avatars.
- Testing: Jest tests in “src/__tests__/”.
- Static PWA support: “static/worker.js”, “static/manifest.json”, “static/analytics.js”.

##### Insights from README
- Describes game features, online multiplayer, PWA optimizations, lightweight design.
- No server code in repo – multiplayer endpoints are external.

a. Main components
- Client (Browser)
- Game Engine (Phaser) & Core Logic
- UI Layer (DOM/Canvas controls, menu, chat)
- Asset Loader (images, audio, sprites)
- Sound System
- Service Worker (caching & offline support)
- Webpack Bundle (runtime code)
- Build System
- Webpack/Babel for bundling/transpiling
- npm scripts, Dockerfile for containerization
- Static Hosting
- CDN or web server serving HTML/CJS, assets, worker.js
- External Services
- Multiplayer Server (WebSocket/API for matches & session)
- Analytics (Google Analytics, custom analytics.js)
- Optional Auth (OAuth/JWT endpoint)
b. Relationships & interactions
- Developer runs build: webpack → bundles static files → Docker container or static host.
- Browser loads index.ejs → main.js → initializes Phaser game & UI modules.
- Asset Loader fetches assets from “assets/” path.
- Service Worker intercepts requests, caches bundles & assets, enabling offline play.
- Multiplayer module opens WebSocket to external server → handshake (authenticate.ts) → gameplay messages (connect.ts, gameplay.ts).
- UI events update game state; game logic produces commands → sent over WebSocket or consumed locally.
- Analytics snippet loads “static/analytics.js” → sends events to analytics backend.
c. Architectural patterns & design principles
- Modular separation: domain logic (game, creature), UI, utilities, multiplayer, sound.
- Single responsibility for each module folder.
- Separation of build vs. runtime: webpack config, Dockerfile distinct from src code.
- PWA pattern: service worker + manifest for caching and offline.
d. Key technologies/frameworks
- Phaser for rendering & game loop
- Webpack + Babel + TypeScript for build & transpile
- Jest for unit tests
- Service Worker API for offline
- WebSockets / REST for multiplayer
- LESS/CSS for theming

##### Elements
- Labels: e.g., “Game Engine”, “UI Layer”, “Service Worker”, “Build System”, “External WS Server”.
- Build → Host
- Browser → Asset Server
- Browser ↔ WebSocket Server
- Browser → Analytics API
- Browser ↔ Cache (Service Worker)
- Green for build/deploy (Webpack, Docker)
- Orange for external services (Multiplayer, Analytics)

##### Final recommendations
- Break the client into sub-components matching the “src/” folders to illustrate modularity.
- Static hosting layer as the boundary between build artifacts and runtime.
- Asynchronous flows (asset loading, WebSocket messaging).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Layer
    subgraph "Build System" 
        direction TB
        Webpack["Webpack/Babel/TS"]:::build
        Webpack -->|uses| Babel[".babelrc.js"]:::build
        Webpack -->|config| TSConfig["tsconfig.json"]:::build
        Webpack -->|bundle| Docker["Dockerfile"]:::build
        click Webpack "https://github.com/freezingmoon/ancientbeast/blob/master/webpack.config.js"
        click Babel "https://github.com/freezingmoon/ancientbeast/blob/master/.babelrc.js"
        click TSConfig "https://github.com/freezingmoon/ancientbeast/blob/master/tsconfig.json"
        click Docker "https://github.com/freezingmoon/ancientbeast/tree/master/Dockerfile"
    end

    StaticHost["CDN / Web Server (serving HTML, bundles, assets)"]:::build

    Webpack -->|deploy| StaticHost

    %% Client Runtime Layer
    subgraph "Browser (Client)" 
        direction TB

        Index["index.html"]:::client
        ServiceWorker["Service Worker"]:::support
        click ServiceWorker "https://github.com/freezingmoon/ancientbeast/blob/master/static/worker.js"
        TemplatesSW["SW Template"]:::support
        click TemplatesSW "https://github.com/freezingmoon/ancientbeast/blob/master/src/templates/service_worker.html"
        AnalyticsTemplate["Analytics Template"]:::support
        click AnalyticsTemplate "https://github.com/freezingmoon/ancientbeast/blob/master/src/templates/analytics.html"

        subgraph "Client Modules"
            direction TB

            subgraph "Game Engine & Core Logic"
                direction TB
                CoreGame["game.ts"]:::client
                Creature["creature.ts"]:::client
                Effect["effect.ts"]:::client
                Damage["damage.ts"]:::client
                Drop["drop.ts"]:::client
                AbilityCore["ability.ts"]:::client
                Animations["animations.ts"]:::client
                AssetsEntry["assets.ts"]:::client

                click CoreGame "https://github.com/freezingmoon/ancientbeast/blob/master/src/game.ts"
                click Creature "https://github.com/freezingmoon/ancientbeast/blob/master/src/creature.ts"
                click Effect "https://github.com/freezingmoon/ancientbeast/blob/master/src/effect.ts"
                click Damage "https://github.com/freezingmoon/ancientbeast/blob/master/src/damage.ts"
                click Drop "https://github.com/freezingmoon/ancientbeast/blob/master/src/drop.ts"
                click AbilityCore "https://github.com/freezingmoon/ancientbeast/blob/master/src/ability.ts"
                click Animations "https://github.com/freezingmoon/ancientbeast/blob/master/src/animations.ts"
                click AssetsEntry "https://github.com/freezingmoon/ancientbeast/blob/master/src/assets.ts"
            end

            Abilities["Abilities Module"]:::client
            click Abilities "https://github.com/freezingmoon/ancientbeast/tree/master/src/abilities/"

            DataModule["Data Module"]:::client
            click DataModule "https://github.com/freezingmoon/ancientbeast/tree/master/src/data/"

            UILayer["UI Layer"]:::client
            click UILayer "https://github.com/freezingmoon/ancientbeast/tree/master/src/ui/"

            AssetLoader["Asset Loader"]:::client
            AssetsFolder["assets/"]:::client
            click AssetLoader "https://github.com/freezingmoon/ancientbeast/blob/master/src/assets.ts"
            click AssetsFolder "https://github.com/freezingmoon/ancientbeast/tree/master/assets/"

            Sound["Sound System"]:::client
            click Sound "https://github.com/freezingmoon/ancientbeast/tree/master/src/sound/"

            Multiplayer["Multiplayer Module"]:::client
            click Multiplayer "https://github.com/freezingmoon/ancientbeast/tree/master/src/multiplayer/"

            Utility["Utility Functions"]:::client
            click Utility "https://github.com/freezingmoon/ancientbeast/tree/master/src/utility/"

            Style["Styling & Themes"]:::client
            click Style "https://github.com/freezingmoon/ancientbeast/tree/master/src/style/"

            Tests["Unit Tests"]:::client
            click Tests "https://github.com/freezingmoon/ancientbeast/tree/master/src/__tests__/"
        end

        %% PWA & Caching
        subgraph "PWA Caching"
            direction TB
            Cache[(Cache Storage)]:::storage
        end

        Index -->|loads| Webpack
        Index -->|registers| ServiceWorker
        ServiceWorker -->|intercepts| AssetLoader
        ServiceWorker -->|caches| Cache
        AssetLoader -->|fetch| AssetsFolder
        AssetLoader -->|load into| CoreGame

        CoreGame -->|uses| Creature
        CoreGame -->|uses| Effect
        CoreGame -->|uses| Damage
        CoreGame -->|uses| Drop
        CoreGame -->|calls| AbilityCore
        CoreGame -->|renders via| Animations

        UILayer -->|updates| CoreGame
        CoreGame -->|updates| UILayer

        Sound -->|plays audio for| CoreGame

        Multiplayer -->|opens WS| WS["WebSocket Server"]:::external
        Multiplayer -->|REST calls| Auth["Auth Endpoint"]:::external

        Analytics["Analytics Snippet"]:::support
        click Analytics "https://github.com/freezingmoon/ancientbeast/blob/master/static/analytics.js"
        AnalyticsTemplate --> Analytics
        Analytics -->|sends events| AnalyticsAPI["Analytics API"]:::external

    end

    %% External Services
    WS -->|messages| Multiplayer
    Auth -->|authenticates| Multiplayer

    %% Connections
    StaticHost -->|serves| Index

    %% Styles
    classDef client fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef build fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef support fill:#D1C4E9,stroke:#5E35B1,color:#311B92
    classDef storage fill:#FFF9C4,stroke:#F9A825,color:#F57F17
```
