# fujik/rpg-cljs-develop architecture

> Architecture diagram of the GitHub repository fujik/rpg-cljs-develop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fujik/rpg-cljs-develop
- Repository: https://github.com/fujik/rpg-cljs-develop

## Overview

##### Project type and overall purpose
- This is a browser-based, single-page 2D RPG “engine” written in ClojureScript.
- There’s no backend server: all logic runs in the browser, with data loaded from static EDN files and optional persistence via `localStorage`.
- Shadow-CLJS drives builds, live‐reloading, and test runners (Node and browser).

##### Main architectural components
A. Runtime & UI Layer
- **index.html** + **Canvas 2D**: hosts the game viewport.
- **js/main.js**: glue code that loads the compiled ClojureScript bundle into the page.
B. Application Code (ClojureScript modules)
1) **src/rpg/main.cljs**
- Bootstraps the app: initializes state, triggers scene loading, starts loop.
2) **Data Layer (src/rpg/data/) & Static EDN (data/…)**
- `loader.cljs` fetches `data/maps/*.edn`, `items.edn`, `enemies.edn` → validates them with Malli (`spec.cljs`) → injects into runtime state.
3) **Engine Layer (src/rpg/engine/…)**
- **state.cljs**: single atom holding the entire game state.
- **input.cljs**: key/mouse event listeners → dispatch events.
- **map.cljs**: movement rules, collision detection.
- **events.cljs**: RPG DSL handlers (`:say`, `:chest`, `:warp`, `:give-item`).
- **dialog.cljs**: simple UI overlays.
- **render.cljs**: draws map, player, UI on Canvas.
- **loop.cljs**: game loop (tick → update → render).
- **storage.cljs**: `localStorage` persistence API (save/load partial state).
4) **Scenes (src/rpg/scenes/…)**
- e.g. `overworld.cljs`: high‐level orchestrator—calls the data loader, sets up initial map, hooks loop and input.
C. Persistence & Testing
- **localStorage**: browser API for saves.
- **Tests (test/rpg/…)**
- Node‐based unit tests for pure logic (map rules, event DSL).
- Browser integration tests via shadow’s `:browser-test` build.
D. Build & Dev Tooling
- **shadow-cljs.edn**: defines three builds (`:app`, `:node-test`, `:browser-test`).
- **package.json/npm scripts**: for watch, build, testing.
- **dev/**: helper scripts for REPL‐driven development.

##### Relationships & data flows
- At startup: index.html → loads compiled bundle → `main.cljs` calls `load-scene`.
- Data loader reads EDN → Malli validates → populates the state atom.
- The loop tick reads state → input events write to state → events DSL mutates state → render reads state and draws Canvas.
- On player action (e.g. open chest) → storage module writes partial state to localStorage.
- Tests invoke pure modules directly in Node or via a headless browser.

##### Architectural patterns & design principles
- **Data-Driven**: game content (maps, items, enemies) is purely EDN + schema validation.
- **Modular Engine**: each subsystem (input, map, events, render) is isolated, interacts via the central state atom.
- **Single Source of Truth**: the state atom holds all runtime data.
- **Separation of Concerns**: Scenes orchestrate, engine modules implement, data layer loads.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI / Runtime Layer
    subgraph "UI / Runtime Layer"
        direction TB
        IndexHTML["index.html"]:::ui
        JSMain["js/main.js"]:::ui
        Canvas["Canvas 2D"]:::ui
    end

    %% Application Bootstrap
    subgraph "Application Bootstrap"
        direction TB
        MainCLJS["src/rpg/main.cljs"]:::engine
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        Loader["Data Loader\nsrc/rpg/data/loader.cljs"]:::data
        Spec["Schema Validation\nsrc/rpg/data/spec.cljs"]:::data
        MapsEDN["Maps EDN\ndata/maps/overworld.edn"]:::data
        ItemsEDN["Items EDN\ndata/items.edn"]:::data
        EnemiesEDN["Enemies EDN\ndata/enemies.edn"]:::data
    end

    %% Engine Layer
    subgraph "Engine Layer"
        direction TB
        State["State Atom\nsrc/rpg/engine/state.cljs"]:::engine
        Input["Input Listeners\nsrc/rpg/engine/input.cljs"]:::engine
        MapLogic["Map Logic\nsrc/rpg/engine/map.cljs"]:::engine
        Events["Event DSL Handlers\nsrc/rpg/engine/events.cljs"]:::engine
        Dialog["Dialog Overlays\nsrc/rpg/engine/dialog.cljs"]:::engine
        Render["Renderer\nsrc/rpg/engine/render.cljs"]:::engine
        Loop["Game Loop\nsrc/rpg/engine/loop.cljs"]:::engine
        Storage["Persistence API\nsrc/rpg/engine/storage.cljs"]:::persistence
    end

    %% Scenes
    subgraph "Scenes"
        direction TB
        Overworld["Overworld Scene\nsrc/rpg/scenes/overworld.cljs"]:::engine
    end

    %% Persistence
    subgraph "Persistence"
        direction TB
        LocalStorage["Browser localStorage"]:::persistence
    end

    %% Tooling & Tests
    subgraph "Build & Dev Tooling"
        direction TB
        Shadow["shadow-cljs.edn"]:::tooling
        PackageJSON["package.json"]:::tooling
        DevFundation["dev/dev_fundationtest.cljs"]:::tooling
        DevUtil["dev/dev_util.cljs"]:::tooling
    end

    subgraph "Tests"
        direction TB
        EventsTest["test/rpg/engine/events_test.cljs"]:::tooling
        MapTest["test/rpg/engine/map_test.cljs"]:::tooling
        LoaderTest["test/rpg/scenes/loader_test.cljs"]:::tooling
    end

    %% Connections
    IndexHTML --> JSMain
    JSMain --> MainCLJS
    MainCLJS --> Overworld
    Overworld --> Loader
    MapsEDN --> Loader
    ItemsEDN --> Loader
    EnemiesEDN --> Loader
    Loader --> Spec
    Spec --> State

    Loop --> State
    Input --> State
    State --> Render
    State --> Events
    State --> MapLogic
    Events --> State
    MapLogic --> State
    Dialog --> Render
    Render --> Canvas
    Loop --> Render
    Loop --> Input

    Storage --> LocalStorage
    State --> Storage

    Shadow --> MainCLJS
    Shadow --> EventsTest
    Shadow --> MapTest
    Shadow --> LoaderTest
    PackageJSON --> Shadow
    DevFundation --> MainCLJS
    DevUtil --> MainCLJS

    %% Click Events
    click IndexHTML "https://github.com/fujik/rpg-cljs-develop/blob/main/index.html"
    click JSMain "https://github.com/fujik/rpg-cljs-develop/blob/main/js/main.js"
    click MainCLJS "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/main.cljs"
    click Loader "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/data/loader.cljs"
    click Spec "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/data/spec.cljs"
    click MapsEDN "https://github.com/fujik/rpg-cljs-develop/blob/main/data/maps/overworld.edn"
    click ItemsEDN "https://github.com/fujik/rpg-cljs-develop/blob/main/data/items.edn"
    click EnemiesEDN "https://github.com/fujik/rpg-cljs-develop/blob/main/data/enemies.edn"
    click State "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/state.cljs"
    click Input "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/input.cljs"
    click MapLogic "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/map.cljs"
    click Events "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/events.cljs"
    click Dialog "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/dialog.cljs"
    click Render "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/render.cljs"
    click Loop "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/loop.cljs"
    click Storage "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/engine/storage.cljs"
    click Overworld "https://github.com/fujik/rpg-cljs-develop/blob/main/src/rpg/scenes/overworld.cljs"
    click EventsTest "https://github.com/fujik/rpg-cljs-develop/blob/main/test/rpg/engine/events_test.cljs"
    click MapTest "https://github.com/fujik/rpg-cljs-develop/blob/main/test/rpg/engine/map_test.cljs"
    click LoaderTest "https://github.com/fujik/rpg-cljs-develop/blob/main/test/rpg/scenes/loader_test.cljs"
    click Shadow "https://github.com/fujik/rpg-cljs-develop/blob/main/shadow-cljs.edn"
    click PackageJSON "https://github.com/fujik/rpg-cljs-develop/blob/main/package.json"
    click DevFundation "https://github.com/fujik/rpg-cljs-develop/blob/main/dev/dev_fundationtest.cljs"
    click DevUtil "https://github.com/fujik/rpg-cljs-develop/blob/main/dev/dev_util.cljs"

    %% Styles
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef data fill:#1E90FF,stroke:#333,stroke-width:1px;
    classDef engine fill:#32CD32,stroke:#333,stroke-width:1px;
    classDef persistence fill:#A9A9A9,stroke:#333,stroke-width:1px;
    classDef tooling fill:#800080,stroke:#FFF,stroke-width:1px;
```
