ClassicAssist.Avalonia/.qoder/repowiki/en/content/Technical Architecture/Technical Architecture.md

# Technical Architecture

<cite>
**Referenced Files in This Document**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
- [CountersManager.cs](file://ClassicAssist.Shared/Data/Counters/CountersManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)
- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
</cite>

## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)

## Introduction
This document describes the technical architecture of ClassicAssist.Avalonia, focusing on layered design, packet processing pipeline, event-driven communication, lifecycle and plugin management, resource strategies, cross-platform considerations for Avalonia and .NET, system boundaries, integration points, scalability, memory management, performance optimization, technology stack decisions, and architectural trade-offs. The goal is to provide a comprehensive yet accessible guide for both developers and advanced users.

## Project Structure
The solution is organized into multiple projects with clear separation of concerns:
- ClassicAssist.Avalonia: Avalonia-based UI application entry point, platform-specific dispatchers, and UI composition.
- ClassicAssist.Shared: Core engine, game data models, networking, packet handling, agents, macros, hotkeys, commands, chat, and shared UI view models.
- ClassicAssist.Launcher: WPF-based launcher for shard selection and plugin management.
- ClassicAssist.Updater: WPF-based updater utility.
- Tests and tools under dedicated test and tool projects.

```mermaid
graph TB
subgraph "UI Layer (Avalonia)"
A_Program["Program.cs"]
A_App["App.axaml.cs"]
A_Engine["Engine.cs"]
A_Dispatcher["AvaloniaDispatcher.cs"]
A_Invoker["AvaloniaUIInvoker.cs"]
A_MainWindow["MainWindow.axaml.cs"]
end
subgraph "Shared Engine"
S_Engine["Engine.cs"]
S_NetIn["IncomingPacketHandlers.cs"]
S_NetOut["OutgoingPacketHandlers.cs"]
S_PktHdlr["PacketHandler.cs"]
S_Acq["ActionPacketQueue.cs"]
S_IncFilt["IncomingPacketFilters.cs"]
S_Entities["Entity.cs / Mobile.cs / Item.cs"]
S_Gump["Gump.cs"]
S_Hotkeys["HotkeyManager.cs"]
S_Macros["MacroManager.cs"]
S_Commands["CommandsManager.cs"]
S_Chat["ChatManager.cs"]
S_Target["TargetManager.cs"]
S_Platform["PlatformDetector.cs"]
end
A_Program --> A_App
A_App --> A_Engine
A_Engine --> S_Engine
A_Dispatcher --> S_Engine
A_Invoker --> S_Engine
A_MainWindow --> S_Engine
S_Engine --> S_NetIn
S_Engine --> S_NetOut
S_Engine --> S_PktHdlr
S_Engine --> S_Acq
S_Engine --> S_IncFilt
S_Engine --> S_Entities
S_Engine --> S_Gump
S_Engine --> S_Hotkeys
S_Engine --> S_Macros
S_Engine --> S_Commands
S_Engine --> S_Chat
S_Engine --> S_Target
S_Engine --> S_Platform
```

**Diagram sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)
- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)

**Section sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

## Core Components
- Application bootstrap and UI composition: Program initializes the Avalonia app, App configures services and root window, and MainWindow hosts main UI content.
- Cross-platform dispatcher and UI invoker: AvaloniaDispatcher and AvaloniaUIInvoker implement shared interfaces to marshal work onto the UI thread consistently across platforms.
- Shared engine: Centralizes lifecycle, subsystem initialization, configuration, and coordination between network, entities, agents, macros, hotkeys, and commands.
- Networking layer: Packet handlers, filters, queues, and target manager orchestrate incoming/outgoing traffic and maintain game state.
- Game objects: Entity hierarchy (Entity, Mobile, Item), Gumps, and collections represent world state.
- Managers: Hotkey, Macro, Commands, Chat, Autoloot, Dress, Scavenger, Organizer, Counters, and Target managers encapsulate domain logic and expose APIs to UI and plugins.

Key responsibilities:
- UI layer: Rendering, user input, and presentation logic only; delegates to shared engine via dispatchers.
- Shared engine: Orchestrates subsystems, manages lifecycle, exposes stable APIs, and coordinates events.
- Network layer: Parses packets, updates entities, enforces filters, and queues actions.
- Managers: Provide cohesive APIs for features like hotkeys, macros, chat, targeting, and agent behaviors.

**Section sources**
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)

## Architecture Overview
The system follows a layered architecture:
- Presentation Layer (Avalonia): Views, ViewModels, and controls. Uses MVVM patterns and binds to shared state exposed by the engine.
- Domain Layer (Shared): Business logic, game rules, managers, and object models.
- Infrastructure Layer (Networking and Platform Abstractions): Packet I/O, filters, queues, and platform-specific dispatchers.

```mermaid
graph TB
UI["Avalonia UI<br/>Views + ViewModels"] --> Dispatcher["AvaloniaDispatcher<br/>and AvaloniaUIInvoker"]
Dispatcher --> Engine["Shared Engine"]
Engine --> Net["Networking Layer<br/>Packets, Filters, Queues"]
Engine --> Entities["Game Objects<br/>Entity, Mobile, Item, Gump"]
Engine --> Managers["Managers<br/>Hotkeys, Macros, Commands, Chat, Agents, Target"]
Net --> Entities
Managers --> Entities
UI <- --> Managers
```

**Diagram sources**
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)

## Detailed Component Analysis

### Packet Processing Pipeline
End-to-end flow from network I/O to entity updates:
- Incoming packets are received and routed through filters.
- Filtered packets are dispatched to registered handlers.
- Handlers update game objects (entities, gumps).
- Actions may be queued for later execution or sent back out.

```mermaid
sequenceDiagram
participant Net as "Network I/O"
participant Filters as "IncomingPacketFilters"
participant Handler as "IncomingPacketHandlers"
participant Pkt as "PacketHandler"
participant Queue as "ActionPacketQueue"
participant Entities as "Entity/Mobile/Item/Gump"
Net->>Filters : "Receive raw packet"
Filters-->>Net : "Allow/Deny"
Filters->>Handler : "Dispatch allowed packet"
Handler->>Pkt : "Resolve handler by opcode"
Pkt->>Entities : "Update state"
Pkt->>Queue : "Enqueue action if needed"
Queue-->>Pkt : "Dequeue and execute"
Pkt-->>Net : "Send outgoing packets if required"
```

**Diagram sources**
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)

**Section sources**
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)

### Event-Driven Architecture and Message Bus Patterns
- Managers expose events and publish messages for decoupled communication between components (e.g., chat messages, macro triggers, hotkey activations).
- UI components subscribe to these events and update bindings accordingly.
- The shared engine coordinates event publication and subscription lifecycles.

```mermaid
classDiagram
class Engine {
+Initialize()
+PublishEvent(event)
+Subscribe(event, handler)
}
class ChatManager {
+OnMessageReceived()
+SendMessage(text)
}
class HotkeyManager {
+OnHotkeyPressed(key)
+Register(key, command)
}
class MacroManager {
+OnMacroTriggered(name)
+RunMacro(name)
}
class CommandsManager {
+Execute(command)
+Register(alias, handler)
}
class BaseViewModel {
+NotifyPropertyChanged()
+BindTo(event)
}
Engine --> ChatManager : "coordinates"
Engine --> HotkeyManager : "coordinates"
Engine --> MacroManager : "coordinates"
Engine --> CommandsManager : "coordinates"
BaseViewModel --> Engine : "subscribes"
```

**Diagram sources**
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)

**Section sources**
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)

### Game Engine Lifecycle Management
Lifecycle phases:
- Bootstrap: Program creates App, App constructs Engine and UI.
- Initialization: Engine loads configuration, registers packet handlers, initializes managers, and prepares resources.
- Runtime: Engine runs message loop, processes network events, handles hotkeys/macros/commands, and updates UI via dispatcher.
- Shutdown: Engine disposes resources, flushes queues, and releases subscriptions.

```mermaid
flowchart TD
Start(["Application Start"]) --> Boot["Program -> App -> Engine"]
Boot --> Init["Engine.Initialize()<br/>Load config, register handlers, init managers"]
Init --> Run["Engine.Run()<br/>Process network, UI, and subsystem events"]
Run --> Update["Update entities, gumps, and UI state"]
Update --> Run
Run --> Shutdown["Engine.Dispose()<br/>Flush queues, release resources"]
Shutdown --> End(["Exit"])
```

**Diagram sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

**Section sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

### Plugin Loading Mechanisms
- The launcher project provides plugin discovery and loading capabilities for external modules.
- Plugins can extend functionality such as commands, macros, or UI elements.
- The shared engine integrates with plugin manifests and metadata to load and manage extensions safely.

```mermaid
sequenceDiagram
participant Launcher as "Launcher"
participant Manifest as "Plugin Manifest"
participant Loader as "Plugin Loader"
participant Engine as "Shared Engine"
participant Plugin as "External Plugin"
Launcher->>Manifest : "Read manifest entries"
Manifest-->>Loader : "List of plugins"
Loader->>Engine : "Register plugin capabilities"
Engine->>Plugin : "Invoke extension points"
Plugin-->>Engine : "Provide commands/macro helpers/UI"
```

**Diagram sources**
- [ManifestEntry.cs](file://ClassicAssist.Launcher/ManifestEntry.cs)
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

**Section sources**
- [ManifestEntry.cs](file://ClassicAssist.Launcher/ManifestEntry.cs)
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

### Resource Management Strategies
- Static resources (fonts, icons, themes) are packaged within the Avalonia project and loaded at startup.
- Data files (JSON configurations, cliloc, tile data) are loaded lazily and cached to minimize I/O overhead.
- Memory-sensitive structures (entity collections, buffers) use efficient containers and avoid unnecessary allocations.

```mermaid
flowchart TD
LoadStart["Startup"] --> LoadResources["Load static resources<br/>Fonts, Icons, Themes"]
LoadResources --> LoadData["Load data files<br/>JSON configs, Cliloc, TileData"]
LoadData --> Cache["Cache in memory<br/>Lazy reload on change"]
Cache --> Runtime["Runtime access<br/>Fast lookups"]
```

**Diagram sources**
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

**Section sources**
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

### Cross-Platform Considerations (Avalonia and .NET)
- Avalonia provides consistent UI across Windows, macOS, and Linux.
- Platform detection abstracts OS-specific behavior and influences runtime paths and native calls.
- Dispatchers ensure UI updates occur on the correct thread per platform.

```mermaid
classDiagram
class IDispatcher {
+Invoke(action)
+BeginInvoke(action)
}
class AvaloniaDispatcher {
+Invoke(action)
+BeginInvoke(action)
}
class IUIInvoker {
+ShowDialog(title, content)
+MessageBox(message)
}
class AvaloniaUIInvoker {
+ShowDialog(title, content)
+MessageBox(message)
}
class PlatformDetector {
+GetOS() string
+IsWindows() bool
+IsMacOS() bool
+IsLinux() bool
}
IDispatcher <|.. AvaloniaDispatcher
IUIInvoker <|.. AvaloniaUIInvoker
PlatformDetector ..> AvaloniaDispatcher : "uses"
PlatformDetector ..> AvaloniaUIInvoker : "uses"
```

**Diagram sources**
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)

**Section sources**
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)

### System Boundaries and Integration Points
- External dependencies:
  - Avalonia UI framework for cross-platform rendering.
  - .NET runtime for managed code execution.
  - Optional native libraries for platform-specific features.
- Integration points:
  - Network socket I/O to Ultima Online servers.
  - File system for configuration and data assets.
  - Plugin loader for extensibility.

```mermaid
graph TB
App["ClassicAssist.Avalonia"] --> Shared["ClassicAssist.Shared"]
App --> Avalonia["Avalonia UI Framework"]
App --> DotNet[".NET Runtime"]
Shared --> UOServer["Ultima Online Server"]
Shared --> FileSystem["File System"]
Shared --> Plugins["Plugin Loader"]
```

**Diagram sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

**Section sources**
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)

## Dependency Analysis
High-level dependency relationships among core components:

```mermaid
graph TB
Engine["Engine.cs"] --> NetIn["IncomingPacketHandlers.cs"]
Engine --> NetOut["OutgoingPacketHandlers.cs"]
Engine --> PktHdlr["PacketHandler.cs"]
Engine --> Acq["ActionPacketQueue.cs"]
Engine --> IncFilt["IncomingPacketFilters.cs"]
Engine --> Ent["Entity.cs / Mobile.cs / Item.cs"]
Engine --> Gump["Gump.cs"]
Engine --> Hotkeys["HotkeyManager.cs"]
Engine --> Macros["MacroManager.cs"]
Engine --> Commands["CommandsManager.cs"]
Engine --> Chat["ChatManager.cs"]
Engine --> Target["TargetManager.cs"]
UI["AvaloniaDispatcher.cs / AvaloniaUIInvoker.cs"] --> Engine
```

**Diagram sources**
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)

**Section sources**
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/UO/Network/Targeting/TargetManager.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)

## Performance Considerations
- Packet filtering reduces CPU usage by dropping irrelevant messages early.
- Action queues batch operations to avoid excessive UI updates and reduce contention.
- Efficient data structures (collections, caches) minimize allocations and improve lookup times.
- Lazy loading of heavy resources prevents startup delays.
- Threading model ensures UI responsiveness by marshalling updates off the UI thread using dispatchers.

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and diagnostics:
- Network connectivity problems: Verify server address, firewall settings, and packet filter rules.
- UI freezes: Ensure all UI updates go through the dispatcher; check for long-running tasks blocking the UI thread.
- Missing resources: Confirm asset paths and that resources are included in the build output.
- Plugin failures: Validate plugin manifests and compatibility with the current engine version.

Recommended steps:
- Enable verbose logging in the engine and review logs for errors.
- Temporarily disable filters to isolate packet-related issues.
- Use the launcher’s options to reset configuration and reinitialize resources.

**Section sources**
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)

## Conclusion
ClassicAssist.Avalonia employs a clean layered architecture with a robust shared engine, explicit networking pipeline, and event-driven communication. The Avalonia UI layer remains thin and focused on presentation, while the shared layer encapsulates game logic, state, and integrations. Cross-platform abstractions and careful resource management contribute to stability and performance. Scalability is supported through modular managers, queues, and lazy loading, while plugin mechanisms enable extensibility.

[No sources needed since this section summarizes without analyzing specific files]

## Appendices
- Technology stack decisions:
  - Avalonia for cross-platform UI consistency.
  - .NET runtime for managed performance and ecosystem.
  - JSON-based configuration and data assets for portability.
- Architectural trade-offs:
  - Separation of UI and engine improves testability but adds indirection.
  - Event-driven design enhances modularity but requires careful lifecycle management.
  - Queued actions balance throughput and UI responsiveness.

[No sources needed since this section provides general guidance]