# Usage overview

What this suite can do for a site, and how the pieces fit together at the feature level.

## The mental model

Data comes from three distinct Blizzard API surfaces and lands in three kinds of local storage:

| Source | Example endpoints | Local storage |
|---|---|---|
| **Reference data** (global, slow-changing) | realms, classes, races, power types, reputation factions | taxonomy terms (in `wow_*` vocabularies) |
| **Catalogs** (global, rarely change) | achievements, mounts, pets, titles, toys, items | content entities (one per catalog) |
| **Profiles** (per-player) | character, achievements progress, collected mounts/pets/titles/toys, reputations | content entities + per-owner junction rows |

Reference data is the foundation (realms, classes, races) — characters reference it. Catalogs are the "what exists" dictionary (the ~9,000 achievements, ~1,000 mounts). Profile syncs fill in "what this player has" by creating junction rows that point at catalog entries.

**Auth note:** per-character and per-guild profile endpoints are called with the module's app token today — no per-player OAuth is required to import or refresh a character you know by realm + name. User OAuth is only used where Blizzard specifically requires it: the account-profile endpoint (`/profile/user/wow`), which lists the logged-in player's own characters and is invoked by `wow_user` during the selection flow.

## Enable what you need

Every capability is a separately-enablable submodule. Minimum viable set to start:

- `wow` (core)
- `wow_realm`, `wow_playable_class`, `wow_playable_race` (reference data characters need)
- `wow_character` (the thing that imports players)

Add from there as the site grows:

- `wow_achievement` for achievement tracking
- `wow_mount`, `wow_pet`, `wow_title`, `wow_toy` for collections
- `wow_reputation` for faction standings
- `wow_guild` for guild pages
- `wow_battlenet_login` + `wow_user` if players log in themselves

## Capabilities

| Capability | Admin-facing | Read [usage/](characters.md) |
|---|---|---|
| Import a named character and keep it fresh | ✓ | [Characters](characters.md) |
| Browse the full WoW achievement catalog, per-character progress | ✓ | [Achievements](achievements.md) |
| Mount / pet / title / toy collection tracking per character | ✓ | [Collections](collections.md) |
| Reputation standings per character across hundreds of factions | ✓ | [Reputation](reputation.md) |
| Creature catalog (types, families, on-demand lookup) | ✓ | — |
| Quest catalog (types, batch sync via queue) | ✓ | — |
| Guild profile + crest (roster / achievements / activity are extension-point only) | ✓ | [Guild recipe](recipes/guild-dashboard.md) |
| Battle.net login for players | ✓ | [Battle.net login](../getting-started/battlenet-login.md) |
| CKEditor 5 WoW link insertion (items, achievements, creatures, quests, etc.) | — | [Editor integration](editor-integration.md) |

## Recipes

End-to-end walkthroughs for the most common site shapes:

- **[Character tracking](recipes/character-tracking.md)** — public player profile pages, no login required
- **[Guild dashboard](recipes/guild-dashboard.md)** — guild profile + crest only; roster, shared achievements, and activity feeds require a custom `GuildDataProvider` (none ship in-tree today)
- **[Achievement planner](recipes/achievement-planner.md)** — browse catalog, filter by category, show completion status

## What the suite doesn't do (out of the box)

- No cross-realm searching or battlegroup roll-ups — Blizzard's APIs are region-scoped.
- No Views or displays are provided. Entities and fields are defined; you build the UX with Views / Twig / custom code.
- No scheduled character refreshes. Characters are refreshed on demand (dashboard button, drush, or your own cron task).
- No PvP ratings, Mythic+ data, equipment details, professions, or appearance. See the [API coverage matrix](../reference/apis.md) for exactly what is and isn't implemented.
