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

# Architecture & Deep Dive

> Understanding how Quest Codex categories, assignments, and menus work together.

# Quest Codex Architecture

The Quest Codex extension operates on a strictly decoupled architecture. Categories, quests, and UI menus are completely separated and only linked via declarative entries.

## 1. The Core Relationship

At the heart of the system is the **Quest Category**. Quests are never hardcoded into menus. Instead, they are *assigned* to a category.

```mermaid theme={null}
graph TD
    QC[Quest Category Definition]
    QA[Quest Assignment]
    Q[Quest]
    QL[Quest Lore]

    QC <-- "Links to" --> QA
    QA -- "Assigns multiple" --> Q
    QL -- "Overrides lore for" --> Q
```

1. **Quest Category**: Defines the identity (e.g., "Main Quests", "Side Quests"), the icon shown in parent menus, and visibility requirements.
2. **Quest Assignment**: Takes existing quests from the `QuestExtension` and assigns them to a specific category. It also determines the order in which they appear.
3. **Quest Lore**: Optionally overrides the default lore of a quest based on its status (Not Started, In Progress, Completed).

## 2. Navigational Defaults & The UI

The Quest Codex uses the GUI Extension's layout pool system to render everything.

```mermaid theme={null}
graph LR
    CM[Category Menu] --> LP[Layout Pool]
    LP --> S1[SimpleLayout: Background]
    LP --> S2[ScrollableLayout: Quests]
    
    S2 -. "Injects QUEST_SLOT" .-> QBtn[Quest Buttons]
    S2 -. "Injects SORT_SLOT" .-> SBtn[Sort Button]
```

When a player opens a category (e.g., `/tw codex main_quests`), the extension:

1. Finds the `category_menu` linked to that category.
2. Evaluates the Layout Pool.
3. Dynamically injects quests assigned to that category into any layout component requesting the `QUEST_SLOT` placeholder.
4. Dynamically injects the sorting button into the `SORT_SLOT`.

## 3. BlueMap Integration

The codex automatically syncs with BlueMap (if installed) to display markers for quests.

```mermaid theme={null}
sequenceDiagram
    participant Player
    participant Codex
    participant BlueMap

    Player->>Codex: Accepts Quest
    Codex->>BlueMap: Updates marker state (visible)
    Player->>Codex: Completes Quest
    Codex->>BlueMap: Removes/Updates marker
```

The integration reads the `BlueMapIconEntry` definitions mapped to quests and manages their visibility based on the player's progression state.