# erorus/shatari architecture

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

- Interactive diagram: https://gitdiagram.com/erorus/shatari
- Repository: https://github.com/erorus/shatari

## Overview

Shatari is a persistent auction-data collector for Undermine Exchange: its main process polls Battle.net, schedules realm and token work, and delegates auction processing before maintaining compressed global, regional, realm, and item states on disk. Separate jobs refresh realm metadata and generate addon data; the README also documents bound-item discovery. The graph preserves these major capabilities, but some job internals and orchestration are unsampled, so only documented or indexed relationships are shown.

Main entry points: [`src/main.js`](https://github.com/erorus/shatari/blob/master/src/main.js) (Collector), [`src/shatariWriter.js`](https://github.com/erorus/shatari/blob/master/src/shatariWriter.js) (Atomic file writer), [`src/realmState.js`](https://github.com/erorus/shatari/blob/master/src/realmState.js) (Realm state), [`src/realmProcess.js`](https://github.com/erorus/shatari/blob/master/src/realmProcess.js) (Realm processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection"]
  node_main["Collector<br/>[main.js]"]
  node_bnet["Battle.net client<br/>[battlenet.js]"]
  node_commodity["Commodity routing<br/>[commodityRealm.js]"]
  node_realmproc["Realm processor<br/>[realmProcess.js]"]
  node_alive["Process liveness<br/>[aliveness.js]"]
  node_realmjob["Realm list refresh<br/>[realmList.js]"]
end

subgraph group_states["Auction States"]
  node_global[("Global state<br/>[globalState.js]")]
  node_region[("Region state<br/>[regionState.js]")]
  node_realm[("Realm state<br/>[realmState.js]")]
  node_item[("Item history<br/>[itemState.js]")]
  node_token[("Token state<br/>[tokenState.js]")]
  node_deals[("Deal state<br/>[dealState.js]")]
end

subgraph group_storage["Storage Formats"]
  node_key["Item key codec"]
  node_writer["Atomic file writer<br/>[shatariWriter.js]"]
  node_itemkey["Item key model<br/>[itemKey.js]"]
end

subgraph group_products["Published Data"]
  node_itemlist["Item list output<br/>[ItemList.js]"]
  node_addon["Addon data generator<br/>[addon.js]"]
  node_bound["Bound-item updates<br/>[make-bound-json.sh]"]
end

node_operator(("Scheduled runtime"))
node_blizzard{{"Battle.net API"}}

node_operator -->|"runs persistently"| node_main
node_main -->|"fetches API data"| node_bnet
node_main -->|"delegates realm work"| node_realmproc
node_main -->|"loads realm state"| node_realm
node_main -->|"loads region state"| node_region
node_main -->|"checks token state"| node_token
node_main -->|"updates snapshots"| node_global
node_main -->|"updates deals"| node_deals
node_main -->|"routes commodity realms"| node_commodity
node_bnet -->|"requests data"| node_blizzard
node_realmproc -->|"reads and writes"| node_realm
node_realmproc -->|"updates history"| node_item
node_realmproc -->|"builds item keys"| node_itemkey
node_realmproc -->|"reports liveness"| node_alive
node_region -->|"publishes API lists"| node_itemlist
node_realm -->|"builds item lists"| node_itemlist
node_region -->|"serializes item keys"| node_key
node_realm -->|"serializes item keys"| node_key
node_item -->|"parses item keys"| node_key
node_region -->|"writes compressed state"| node_writer
node_realm -->|"writes compressed state"| node_writer
node_global -->|"writes state"| node_writer
node_token -->|"writes state"| node_writer
node_deals -->|"writes state"| node_writer
node_itemlist -->|"writes API files"| node_writer
node_realmjob -->|"refreshes realms"| node_bnet
node_realmjob -->|"writes realm list"| node_writer
node_operator -->|"runs periodically"| node_addon
node_addon -->|"reads price history"| node_realm
node_addon -->|"reads item history"| node_item
node_operator -->|"runs regularly"| node_bound
node_bound -.->|"checks bound items"| node_region

click node_main "https://github.com/erorus/shatari/blob/master/src/main.js"
click node_bnet "https://github.com/erorus/shatari/blob/master/src/battlenet.js"
click node_commodity "https://github.com/erorus/shatari/blob/master/src/commodityRealm.js"
click node_realmproc "https://github.com/erorus/shatari/blob/master/src/realmProcess.js"
click node_alive "https://github.com/erorus/shatari/blob/master/src/aliveness.js"
click node_realmjob "https://github.com/erorus/shatari/blob/master/src/realmList.js"
click node_global "https://github.com/erorus/shatari/blob/master/src/globalState.js"
click node_region "https://github.com/erorus/shatari/blob/master/src/regionState.js"
click node_realm "https://github.com/erorus/shatari/blob/master/src/realmState.js"
click node_item "https://github.com/erorus/shatari/blob/master/src/itemState.js"
click node_token "https://github.com/erorus/shatari/blob/master/src/tokenState.js"
click node_deals "https://github.com/erorus/shatari/blob/master/src/dealState.js"
click node_key "https://github.com/erorus/shatari/blob/master/src/itemKeySerialize.js"
click node_writer "https://github.com/erorus/shatari/blob/master/src/shatariWriter.js"
click node_itemkey "https://github.com/erorus/shatari/blob/master/src/itemKey.js"
click node_itemlist "https://github.com/erorus/shatari/blob/master/src/api/ItemList.js"
click node_addon "https://github.com/erorus/shatari/blob/master/src/addon.js"
click node_bound "https://github.com/erorus/shatari/blob/master/make-bound-json.sh"

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_main,node_bnet,node_commodity,node_realmproc,node_alive,node_realmjob toneBlue
class node_global,node_region,node_realm,node_item,node_token,node_deals toneAmber
class node_key,node_writer,node_itemkey,node_blizzard toneMint
class node_itemlist,node_addon,node_bound toneRose
class node_operator toneIndigo
```

## Components

### Collection

- [Collector](https://github.com/erorus/shatari/blob/master/src/main.js): `src/main.js`
- [Battle.net client](https://github.com/erorus/shatari/blob/master/src/battlenet.js): `src/battlenet.js`
- [Commodity routing](https://github.com/erorus/shatari/blob/master/src/commodityRealm.js): `src/commodityRealm.js`
- [Realm processor](https://github.com/erorus/shatari/blob/master/src/realmProcess.js): `src/realmProcess.js`
- [Process liveness](https://github.com/erorus/shatari/blob/master/src/aliveness.js): `src/aliveness.js`
- [Realm list refresh](https://github.com/erorus/shatari/blob/master/src/realmList.js): `src/realmList.js`

### Auction States

- [Global state](https://github.com/erorus/shatari/blob/master/src/globalState.js): `src/globalState.js`
- [Region state](https://github.com/erorus/shatari/blob/master/src/regionState.js): `src/regionState.js`
- [Realm state](https://github.com/erorus/shatari/blob/master/src/realmState.js): `src/realmState.js`
- [Item history](https://github.com/erorus/shatari/blob/master/src/itemState.js): `src/itemState.js`
- [Token state](https://github.com/erorus/shatari/blob/master/src/tokenState.js): `src/tokenState.js`
- [Deal state](https://github.com/erorus/shatari/blob/master/src/dealState.js): `src/dealState.js`

### Storage Formats

- [Item key codec](https://github.com/erorus/shatari/blob/master/src/itemKeySerialize.js): `src/itemKeySerialize.js`
- [Atomic file writer](https://github.com/erorus/shatari/blob/master/src/shatariWriter.js): `src/shatariWriter.js`
- [Item key model](https://github.com/erorus/shatari/blob/master/src/itemKey.js): `src/itemKey.js`

### Published Data

- [Item list output](https://github.com/erorus/shatari/blob/master/src/api/ItemList.js): `src/api/ItemList.js`
- [Addon data generator](https://github.com/erorus/shatari/blob/master/src/addon.js): `src/addon.js`
- [Bound-item updates](https://github.com/erorus/shatari/blob/master/make-bound-json.sh): `make-bound-json.sh`

### Other components

- **Scheduled runtime**
- **Battle.net API**

## Connections

- Scheduled runtime → Collector: runs persistently (evidence: `README.md`)
- Collector → Battle.net client: fetches API data (evidence: `src/main.js`)
- Collector → Realm processor: delegates realm work (evidence: `src/main.js`)
- Collector → Realm state: loads realm state (evidence: `src/main.js`)
- Collector → Region state: loads region state (evidence: `src/main.js`)
- Collector → Token state: checks token state (evidence: `src/main.js`)
- Collector → Global state: updates snapshots (evidence: `src/main.js`)
- Collector → Deal state: updates deals (evidence: `src/main.js`)
- Collector → Commodity routing: routes commodity realms (evidence: `src/main.js`)
- Battle.net client → Battle.net API: requests data (evidence: `src/battlenet.js`)
- Realm processor → Realm state: reads and writes (evidence: `src/realmProcess.js`)
- Realm processor → Item history: updates history (evidence: `src/realmProcess.js`)
- Realm processor → Item key model: builds item keys (evidence: `src/realmProcess.js`)
- Realm processor → Process liveness: reports liveness (evidence: `src/realmProcess.js`)
- Region state → Item list output: publishes API lists (evidence: `src/regionState.js`)
- Realm state → Item list output: builds item lists (evidence: `src/realmState.js`)
- Region state → Item key codec: serializes item keys (evidence: `src/regionState.js`)
- Realm state → Item key codec: serializes item keys (evidence: `src/realmState.js`)
- Item history → Item key codec: parses item keys (evidence: `src/itemState.js`)
- Region state → Atomic file writer: writes compressed state (evidence: `src/regionState.js`)
- Realm state → Atomic file writer: writes compressed state (evidence: `src/realmState.js`)
- Global state → Atomic file writer: writes state (evidence: `src/globalState.js`)
- Token state → Atomic file writer: writes state (evidence: `src/tokenState.js`)
- Deal state → Atomic file writer: writes state (evidence: `src/dealState.js`)
- Item list output → Atomic file writer: writes API files (evidence: `src/api/ItemList.js`)
- Realm list refresh → Battle.net client: refreshes realms (evidence: `src/realmList.js`)
- Realm list refresh → Atomic file writer: writes realm list (evidence: `src/realmList.js`)
- Scheduled runtime → Addon data generator: runs periodically (evidence: `README.md`)
- Addon data generator → Realm state: reads price history (evidence: `src/addon.js`)
- Addon data generator → Item history: reads item history (evidence: `src/addon.js`)
- Scheduled runtime → Bound-item updates: runs regularly (evidence: `README.md`)
- Bound-item updates → Region state: checks bound items