# Service reference

The services every submodule exposes, grouped by role. Cross-module consumers should use the service IDs below; don't instantiate classes directly.

## Core

| Service ID | Class | Role |
|---|---|---|
| `wow.battlenet.auth` | `BattleNetAuth` | OAuth token fetch / refresh |
| `wow.battlenet.client` | `BattleNetClient` | Authenticated HTTP client (rate limit, retry, conditional requests) |
| `wow.dashboard_section_provider_manager` | `DashboardSectionProviderManager` | Plugin discovery for dashboard sections |
| `wow.dashboard_renderer` | `DashboardRenderer` | Owns dashboard markup |
| `wow.searchable_data_provider_manager` | `SearchableDataProviderManager` | Plugin discovery for search providers |
| `wow.search_orchestrator` | `SearchOrchestrator` | Multi-provider search with budget allocation and failure isolation |
| `wow.ttl_sweeper` | `TtlSweeper` | 30-day TTL enforcement |
| `logger.channel.wow` | Logger channel | Shared logger channel; use this for all WoW-related logging |

## Per-module Api + Sync

Every submodule follows the `wow_<module>.api.<entity>` / `wow_<module>.sync.<entity>` naming convention. The Api class wraps Blizzard endpoints; the Sync class orchestrates fetch → entity writes.

### Reference data

| Module | Api service | Sync service |
|---|---|---|
| `wow_realm` | `wow_realm.api.realm` | `wow_realm.sync.realm` |
| `wow_playable_class` | `wow_playable_class.api.playable_class` | `wow_playable_class.sync.playable_class` |
| `wow_playable_race` | `wow_playable_race.api.playable_race` | `wow_playable_race.sync.playable_race` |
| `wow_playable_specialization` | `wow_playable_specialization.api.playable_specialization` | `wow_playable_specialization.sync.playable_specialization` |
| `wow_power_type` | `wow_power_type.api.power_type` | `wow_power_type.sync.power_type` |
| `wow_reputation` | `wow_reputation.api.reputation` | `wow_reputation.sync.reputation_faction` |

### Catalogs

| Module | Api service | Sync service |
|---|---|---|
| `wow_achievement` | `wow_achievement.api.achievement` | `wow_achievement.sync.achievement`, `wow_achievement.sync.category` |
| `wow_mount` | `wow_mount.api.mount` | `wow_mount.sync.mount` |
| `wow_pet` | `wow_pet.api.pet` | `wow_pet.sync.pet` |
| `wow_title` | `wow_title.api.title` | `wow_title.sync.title` |
| `wow_toy` | `wow_toy.api.toy` | `wow_toy.sync.toy` |
| `wow_item` | `wow_item.api.item` | `wow_item.sync.item`, `wow_item.sync.item_class` |
| `wow_creature` | `wow_creature.api.creature` | `wow_creature.sync.creature`, `wow_creature.sync.creature_type`, `wow_creature.sync.creature_family` |
| `wow_quest` | `wow_quest.api.quest` | `wow_quest.sync.quest`, `wow_quest.sync.quest_type` |

### Owners

| Module | Api service | Sync service |
|---|---|---|
| `wow_character` | `wow_character.api.character` | `wow_character.sync.character` |
| `wow_guild` | `wow_guild.api.guild` | `wow_guild.sync.guild` |

## Plugin managers

| Service ID | Plugins it discovers |
|---|---|
| `wow.dashboard_section_provider_manager` | `DashboardSectionProvider` (every submodule with a dashboard row) |
| `wow.searchable_data_provider_manager` | `SearchableDataProvider` (per-type search providers used by editor modal and search endpoints) |
| `wow_character.character_data_provider_manager` | `CharacterDataProvider` (per-character data fetchers + page section builders) |
| `wow_guild.guild_data_provider_manager` | `GuildDataProvider` (per-guild data fetchers — interface exists, no in-tree implementations) |

## Card builders / page helpers

| Service ID | Class | Role |
|---|---|---|
| `wow_character.card_builder` | `CharacterCardBuilder` | Builds render arrays for character cards (used by `wow_user`'s selection UI and anywhere a character summary is displayed) |
| `wow_character.page_renderer` | `CharacterPageRenderer` | Collects `CharacterPageSection` objects from all data provider plugins, groups by slot, sorts by weight |

## User-scope API

| Service ID | Class | Role |
|---|---|---|
| `wow_user.account_profile_api` | `AccountProfileApi` | Calls `/profile/user/wow` using a stored user OAuth token to list the user's characters |

## Dependency rules

Consumer rules based on module layer:

- **Core services** (wow.*) can be consumed by anything.
- **Reference data services** can be consumed by catalog and owner modules.
- **Catalog Api/Sync services** can be consumed by owner modules and by other catalog modules (but catalog ↔ catalog coupling is a code smell — audit closely).
- **Owner services** must not be consumed by catalog modules. Consuming them would break the "enable catalogs without owners" guarantee.
- **Auth/glue services** can consume anything but must not be consumed by the modules they glue (e.g. `wow_battlenet_login` consumes nothing above its layer).
