> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootroute.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Load order, the runtime contract, and how the framework and bot layers fit together.

## The runtime contract

Every Lua file in the repository is loaded in-game by WGG and starts with:

```lua theme={null}
local WGG, volvox = ...
```

* `WGG` is the unlocker API (object scanning and properties, position and movement, navigation, protected calls, tracelines, filesystem, HTTP, JSON, encryption).
* `volvox` is the shared framework table — **the only channel for cross-file shared state** that isn't a plain global.

There is no compiler, test runner, or standalone Lua interpreter. "Running" means loading the addon in-game through WGG.

## Authoritative references

Use the documentation source that owns each part of the runtime:

* **WGG API:** [WGG documentation](https://docs.8g90jerssb.space/) for unlocker calls such as object access, movement, navigation, protected calls, tracelines, files, HTTP, JSON, and encryption.
* **World of Warcraft API:** [Warcraft Wiki](https://warcraft.wiki.gg/wiki/World_of_Warcraft_API) for WoW API functions and events, including exact namespaces, parameters, return values, availability, and restrictions.
* **Game data IDs:** [Wowhead](https://www.wowhead.com/) for numeric item, GameObject, spell, NPC, quest, zone, area, faction, and profession IDs.

Never invent an API signature or numeric game-data ID. If the relevant authoritative source is unreachable or does not cover the requested API or entity, stop and ask for clarification rather than guessing.

## Load order

`loadorder.json` at the repository root is the manifest: module names **without `.lua`**, in the exact order WGG loads them. Order is load-bearing — a file may only reference `volvox.*` members and globals defined by files **above** it.

<Warning>
  Adding a `.lua` file requires adding it to `loadorder.json` at the correct position, or it never loads.
</Warning>

The layering, from first to last:

```
Libs/  →  Util/ + Hooks/ + Module/ + Core/  →  Interface/  →  Gatherer/  →  _SingleButtonAssistant  →  Main
```

One deliberate exception within the middle layers: `Interface/Theme.lua` is a foundational cross-cutting dependency that loads between `Module/Module` and `Core/StatusToggles`, so `volvox.Theme` exists before every GUI consumer (including `Core/StatusToggles.lua`). The remaining interface files load after the core framework.

`Main.lua` loads last and calls `volvox:Init()` to start the [runtime loops](/framework/runtime).

### Load-guard pattern

Files guard against double-execution with a flag on `volvox`:

```lua theme={null}
if volvox.GathererXxxLoaded then return end
volvox.GathererXxxLoaded = true
```

## Framework services

The root files (everything outside `Gatherer/`) provide the services the bot builds on:

| Service                                                  | Provided by                                 | Reference                                 |
| -------------------------------------------------------- | ------------------------------------------- | ----------------------------------------- |
| Runtime loops (`OnTick` / `OnUpdate`)                    | `Main.lua`                                  | [Runtime](/framework/runtime)             |
| `volvox.Module` base class                               | `Module/Module.lua`                         | [Modules](/framework/modules)             |
| `volvox.Config` persistence                              | `Util/Config.lua`                           | [Configuration](/framework/configuration) |
| `volvox.EventHandler` dispatcher                         | `Hooks/CombatLogReader.lua`                 | [Events](/framework/events)               |
| `volvox.GuiBuilder` settings DSL                         | `Interface/GuiBuilder.lua`                  | [GUI builder](/framework/gui-builder)     |
| Theme, settings window, minimap, toggles, slash commands | `Interface/`, `Core/`                       | [Interface](/framework/interface)         |
| Logging (`volvox:Logger` and helpers)                    | `Remote/_VolvoxLoader.lua` (reference only) | [Logging](/framework/logging)             |
| API resolution and secret unwrapping                     | `Util/Api.lua`, `Util/Secure.lua`           | [Utilities](/framework/utilities)         |

## Repository map

| Path                            | Purpose                                                                                                                |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `loadorder.json`                | Load manifest — module names (no `.lua`) in load order                                                                 |
| `Main.lua`                      | Bootstraps the runtime via `volvox:Init()`; loads **last**                                                             |
| `Libs/`                         | Vendored third-party libs (load first): LibStub, AceLocale-3.0, StdUi (`"volvoxStdUi"`), !LibUIDropDownMenu            |
| `Util/Api.lua`                  | `volvox.ResolveApi` / `volvox.ResolveApiFunction` — WGG-first API resolution                                           |
| `Util/Config.lua`               | `volvox.Config` persistence layer                                                                                      |
| `Util/Secure.lua`               | `volvox.UnwrapSecret` and friends — unwrap WoW "secret value" protections                                              |
| `Core/Macro.lua`                | `/volvox` slash commands and `volvox.OpenSettings()`                                                                   |
| `Hooks/CombatLogReader.lua`     | `volvox.EventHandler` — event dispatcher                                                                               |
| `Module/Module.lua`             | `volvox.Module` base class                                                                                             |
| `Interface/Theme.lua`           | `volvox.Theme` — foundational shared palette, font, spacing, size tokens, and color helpers (`:Get`, `:Table`, `:Hex`) |
| `Core/StatusToggles.lua`        | Status frame + `volvox:AddGlobalToggle`                                                                                |
| `Interface/Sidebar.lua`         | `volvox.Sidebar` — left navigation panel for the settings window                                                       |
| `Interface/Default.lua`         | `volvox.Interface` — main settings window                                                                              |
| `Interface/GuiBuilder.lua`      | `volvox.GuiBuilder` — declarative settings-page DSL                                                                    |
| `Interface/Minimap/Minimap.lua` | Minimap button + dropdown                                                                                              |
| `Interface/Layout/`             | Built-in "General" and "Modules" settings pages                                                                        |
| `Remote/_VolvoxLoader.lua`      | Production remote loader and logger reference; not part of the root manifest                                           |
| `scripts/`                      | Local verification helpers (`verify.sh`, `core-concat.sh`, `changelog-release.sh`)                                     |
| `Gatherer/`                     | The bot layer — see [Gatherer overview](/gatherer/overview)                                                            |

## WGG call rules

When touching any unlocker call, the codebase follows three rules:

1. **Prefer the documented `WGG.*` form.** If the [WGG docs](https://docs.8g90jerssb.space/) expose a capability as `WGG.Foo`, call `WGG.Foo` even though a bare global (e.g. `ReadFile`, `JsonEncode`) may also work.
2. **Flag bare globals; don't silently extend them.** Existing code uses some bare globals; new or modified work switches to the documented `WGG.*` form.
3. **Handle sentinel returns.** WGG functions may return `0`, `false`, `nil`, or empty strings on failure. Check before driving movement, combat, file I/O, HTTP, or route state.

The [`volvox.ResolveApiFunction`](/framework/utilities) helper exists precisely for cases where an API is exposed under multiple candidate names.