# Architecture

> The contract between the addon's modules, the compiled guide data, the toolchain and the tests.

Page: https://polestar.guide/docs/contributors/architecture (Polestar docs > Contributors)

Polestar is a leveling-guide system for **World of Warcraft: Forever** (client
1.60.1, `## Interface: 16001`, install folder `_classic_beta_` during beta).
This file is the contract between modules: the code follows it, and a change
to a contract changes this file with it.

Reference material, checked out locally (gitignored):

- `.ref/wow-ui-source-forever/` — Blizzard's Forever UI source (Gethe/wow-ui-source,
  branch `forever`). `Interface/AddOns/Blizzard_APIDocumentationGenerated/*.lua`
  declares every C API function and event with argument types. **Verify every
  client API you call against it**; a retail or Era assumption is not evidence.
- The live client's AddOns folder, as found by `tools/lib/addons.js`
  (`$WOW_FOREVER_ADDONS`, then the detected clients:
  `<client>/_classic_beta_/Interface/AddOns/`; read-only for reference;
  EllesmereUI's `SKINNING_API.md` lives there).

## Overview

Polestar is a set of addons, a folder of guides and the Node tools that turn
one into the other. The addons:

| Addon | What it holds | Built by (`node tools/polestar.js …`) | In git | Ships |
|---|---|---|---|---|
| `Polestar` (`addon/Polestar/`) | The addon: engine, navigation, quests, gear, maps, quality of life, Lookup, Dungeons, Rares and every window | hand-written, plus a few generated data files | yes | yes |
| `Polestar_Guides` (`addon/Polestar_Guides/`) | Polestar's own pack (pack id `guides`) | `compile`, from `guides/` | yes (generated) | yes |
| community addons | Addons by other authors (`X-Polestar-Pack` in their TOC; `docs/PACKS.md`, `docs/PACK_FORMAT.md`) | the same compiler, from their own repositories | in their own repositories | by their authors |
| `Polestar_ItemDB` (`addon/Polestar_ItemDB/`) | Item stats and Forever reward choices for the gear advice; loaded on demand | `itemdb build` (`Items.lua`), then `gear build` (`Forever.lua`) | yes (generated) | yes |
| `Polestar_Names_<locale>` (`addon/Polestar_Names_deDE/` … `zhTW/`) | Quest, NPC, object and item names in one client language, for `Polestar.Names`; loaded on demand, only the client's own, never in English | `i18n names`, from the community names database (pinned) and the Era quest database | yes (generated) | yes |
| `Polestar_QuestDB` (`addon/Polestar_QuestDB/`) | The quest database behind quest markers and tooltips; loaded on demand | `questdb build` | no (local, gitignored) | yes, when built |
| `Polestar_Codex` (`addon/Polestar_Codex/`) | Lookup's Codex, and the Dungeons and Rares data; loaded on demand | `codex build`, from release-safe inputs (`--local-extras` builds a local-only one) | no (generated, gitignored) | yes, always: `pack` fails without it |
| `Polestar_Nav` (`addon/Polestar_Nav/`) | Polestar's walking router (started from Shortest Path Forever v1.16.0 by Cillian Berragan, GPL-3.0-or-later; Polestar's since 2026-10-16) with Polestar's walking maps of Eastern Kingdoms, Kalimdor and Zephras Isle (maps format 2, grown from his format) and the walk's chokepoints, for the arrow's walking routes; loaded on demand at login, never while an installed Shortest Path Forever guides (the target handed to it, or a journey of its own running; Nav, "In-game walking routes (Polestar_Nav)", "Hand-off to Shortest Path Forever") | the router hand-written (`Routing/`); `nav pack` (the maps, `PACK.json`, from the navigation grid and the ground layers) | yes | yes, always |
| `Polestar_Travel` (`addon/Polestar_Travel/`) | Zone crossings for the travel planner, from an optional local crossings file; loaded with Polestar | `travel build` | no (local, gitignored) | no, never packaged (Nav, "Travel planner and zone crossings") |
| `Polestar_Recorder` (`addon/Polestar_Recorder/`) | The optional standalone recorder of play sessions, for authoring | hand-written | yes | yes, as its own zip |

A guide goes from a `.guide` file to the game in four steps. An author
writes it in a pack (`guides/` for Polestar's own). `lint` and
`compile` parse it and fill in names, places and coordinates from the
reference data in `data/forever`. `compile` writes the result as Lua into the
pack's addon folder (`addon/Polestar_Guides` for ours). `install` copies that
folder into the game, where the pack registers its guides with
`Core/Guides.lua` at load time and the Engine plays them ("Guide data" and
"Engine" below).

Where to look next: [docs/README.md](https://polestar.guide/docs/contributors/docs-map) maps every document;
[addon/README.md](https://polestar.guide/docs/contributors/addon) lists every addon file with its public
table; [tools/README.md](https://polestar.guide/docs/contributors/tools) lists the commands, every
generated file and the rebuild order; [tests/README.md](https://polestar.guide/docs/contributors/tests)
describes the test layers and the fake client.

`addon/Polestar/Polestar.toc` loads eleven XML manifests in this order. Each
module's manifest lists that module's files.
The module sections below follow this order.

```
Core\Core.xml           Core: namespace, lifecycle, events, settings, Compat, guide registry, Engine, automation, commands
Theme\Theme.xml         Theme + widget kit
Nav\Nav.xml             Waypoint arrow, map/minimap pins, travel planner, TomTom bridge
Quests\Quests.xml       Quest database access, markers, tooltips, quest levels
Gear\Gear.xml           Item stats, stat weights, upgrade tooltips, reward picks
Maps\Maps.xml           World map: no fog of war, coordinates, zone levels, dungeon and travel pins, instances
QoL\QoL.xml             Quality-of-life helpers
Lookup\Lookup.xml       Codex, sources, generated guides, mount spotting
Dungeons\Dungeons.xml   Dungeon quest journal data
UI\UI.xml               Guide window, guide menu, zone art, Lookup and Dungeons views, route choice, options
Rares\Rares.xml         Rare NPCs and treasures: detection, pins, alerts, view
Talents\Talents.xml     Talent plans: the hub section, talent frame marks, reminder
```

Manifests use only `<Script file="..."/>` and `<Include file="..."/>` (paths
relative to the XML file, backslashes allowed). The test harness parses the
TOC and these manifests, so tests always load exactly what the client loads.

### Globals

Only these globals may be assigned anywhere under `addon/` (enforced by
`tests/syntax.test.js` via `luac -l`):

`Polestar`, `PolestarDB`, `PolestarCharDB`, `PolestarRecorderDB`,
`SLASH_POLESTAR<n>`, `SLASH_POLESTARREC<n>`, `SLASH_POLESTARWAY<n>` (`/way`,
claimed only while no addon has it), `BINDING_HEADER_POLESTAR`,
`BINDING_NAME_POLESTAR_*`, in `Polestar_Nav` only `Polestar_NavEngine`
(the engine's handoff), `PolestarPathData` (the walking maps) and, in
`Routing/Costs.lua` only, `Polestar_NavCosts` (the router's ground-class
costs), and in `Nav/Journey.lua` only `TomTom` (its stand-in, set while TomTom is not
installed and cleared when it stands down; "Nav API").

Everything else is `local` or lives on the `Polestar` table. Named frames must
be prefixed `Polestar`.

---

Next page: [Core](https://polestar.guide/docs/contributors/architecture/core.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt