Questie-Octo/Docs/ARCHITECTURE.md

Questie-Octo architecture base

Non-negotiable design

• ClassicAPI is the only required enhanced-client compatibility layer.
• SuperWoW and Nampower may be detected later, but no core feature may depend on them.
• Questie 5.2.3 is the main UI/behavior target.
• Questie 6.0.0 is the architecture bridge.
• Questie 7-9 are bug-fix references.
• Questie 10-11 are references for service separation and mature availability logic.
• Questie 11.34.1 is an edge-case reference, not a runtime base.
• pfQuest/pfQuest-turtle are transitional raw data/reference sources only.
• Tortoise/Turtle server data should become the authoritative offline-generated relationship layer.
• No heavy whole-world calculation may run in one frame.
• Login and zone changes must remain responsive.
• Map nodes will use persistent diff/reuse, never continuous clear/recreate.

Runtime service order

ClassicAPI contract -> Scheduler -> raw-data provider merge (incremental) -> QuestLog cache (ClassicAPI IDs) -> Turtle completion history -> canonical Quest model -> AvailableQuests -> Objectives / ItemStarts -> persistent Map + Minimap -> Tracker / Tooltips / Options

0.1.0 scope

0.1.0 intentionally stops after:

• ClassicAPI verification
• gentle scheduler
• isolated raw DB provider
• ClassicAPI quest-ID quest log cache
• Turtle .queststatus / TWQUEST completion service
• diagnostics

No map, minimap, tracker, availability engine, or tooltip UI yet.

0.1.1 milestone

Introduces the public database boundary and canonical quest services:

Legacy/raw data provider -> DatabaseAPI -> QuestModel -> Completion + QuestLog -> AvailableQuests

No module outside Database/ should add new direct pfDB dependencies.

0.1.3 milestone

Adds the canonical node-generation boundary:

QuestModel -> Objectives -> ItemStarts -> Nodes -> future persistent Map/Minimap

Map/Minimap must consume Nodes and must not rediscover quest/item/source relationships itself.

Quest-truth publication rules

The runtime quest system is intentionally layered:

pfQuest/Turtle raw DB truth -> QuestModel semantic normalization -> Completion / EventAvailability / QuestLog runtime truth -> AvailableQuests transactional snapshot -> Objectives / ItemStarts -> Nodes transactional snapshot -> PreparedMap -> World Map / Minimap / Tracker / Quests browser

Important invariants:

• lvl is presentation/difficulty; min is the minimum-level availability gate.
• A quest DB event value is event membership only. It never means the event is active now.
• Repeatability and event membership are independent flags; rendering must use an explicit precedence instead of assuming one classification excludes the other.
• Completion data must be queried authoritatively before it is published. When QueryQuestsCompleted exists, request the cache and wait for QUEST_QUERY_COMPLETE before reading GetQuestsCompleted; otherwise use the Turtle .queststatus / TWQUEST fallback.
• Async services never clear a published live snapshot while rebuilding it. Build into a private buffer and atomically swap at the publication boundary. This prevents map/minimap blinking during settings or quest-state refreshes.
• Prepared/map presentation stays valid until a complete replacement node snapshot exists.