# Architecture Overview

<cite>
**Referenced Files in This Document**
- [README.md](file://README.md)
- [ClassicAssist.Shared/Engine.cs](file://ClassicAssist.Shared/Engine.cs)
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [ClassicAssist.Launcher/MainViewModel.cs](file://ClassicAssist.Launcher/MainViewModel.cs)
- [ClassicAssist.Shared/UO/Network/PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ClassicAssist.Shared/UO/Objects/Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [ClassicAssist.Shared/Data/Macros/MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
- [ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
- [ClassicAssist.Avalonia/Views/MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
- [ClassicAssist.Avalonia/AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [ClassicAssist/WPFDispatcher.cs](file://ClassicAssist/WPFDispatcher.cs)
- [ClassicAssist.Shared/IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.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)

## Introduction

ClassicAssist.Avalonia is a cross-platform Ultima Online game assistant application built using the Avalonia UI framework. The system follows a layered architecture pattern that separates concerns between the user interface layer, shared business logic, and platform-specific implementations. This design enables code reuse across multiple UI frameworks (WPF and Avalonia) while maintaining clean separation of responsibilities.

The application provides comprehensive game automation features including macro scripting, agent management, filtering systems, and real-time packet processing for Ultima Online gameplay enhancement.

## Project Structure

The ClassicAssist.Avalonia solution follows a modular architecture with clear separation between different functional areas:

```mermaid
graph TB
subgraph "UI Layer"
A[ClassicAssist.Avalonia]
B[ClassicAssist.WPF]
C[ClassicAssist.Launcher]
end
subgraph "Shared Core"
D[ClassicAssist.Shared]
E[ClassicAssist.Tests]
end
subgraph "External Dependencies"
F[UO Game Engine]
G[Plugin System]
end
A --> D
B --> D
C --> D
D --> F
D --> G
```

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

The project structure demonstrates a clean separation where:
- **ClassicAssist.Shared**: Contains all business logic, data models, and core functionality
- **ClassicAssist.Avalonia**: Avalonia-specific UI implementation
- **ClassicAssist.WPF**: WPF-specific UI implementation  
- **ClassicAssist.Launcher**: Application launcher and configuration management

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

## Core Components

### Shared Library Architecture

The ClassicAssist.Shared library serves as the foundation containing all reusable business logic:

#### Network Processing Pipeline
The network subsystem handles Ultima Online protocol communication through a sophisticated packet processing pipeline:

```mermaid
sequenceDiagram
participant Game as "UO Game Client"
participant Network as "PacketHandler"
participant Filters as "PacketFilters"
participant Handlers as "PacketHandlers"
participant UI as "UI Layer"
Game->>Network : Incoming Packet
Network->>Filters : Apply Filters
Filters-->>Network : Filtered Data
Network->>Handlers : Route to Handler
Handlers->>Handlers : Process Logic
Handlers->>UI : Update State
UI-->>Game : Response Actions
```

**Diagram sources**
- [ClassicAssist.Shared/UO/Network/PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ClassicAssist.Shared/UO/Objects/Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)

#### Plugin-Based Extensibility Model

The system implements a robust plugin architecture allowing third-party extensions:

```mermaid
classDiagram
class PluginBase {
<<abstract>>
+string Name
+string Version
+Initialize() void
+Execute(context) object
+Dispose() void
}
class MacroCommand {
+string CommandName
+string Description
+Execute(parameters) object
}
class AgentPlugin {
+AgentType Type
+ConfigureDialog() Window
+ProcessLogic() void
}
class FilterPlugin {
+FilterCriteria Criteria
+ApplyFilter(data) bool
}
PluginBase <|-- MacroCommand
PluginBase <|-- AgentPlugin
PluginBase <|-- FilterPlugin
```

**Diagram sources**
- [ClassicAssist.Shared/Data/Macros/MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)

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

## Architecture Overview

### High-Level System Architecture

The ClassicAssist.Avalonia system follows a multi-layered architecture pattern:

```mermaid
graph TB
subgraph "Presentation Layer"
A[Avalonia UI]
B[WPF UI]
C[Launcher UI]
end
subgraph "Application Layer"
D[Main Application Controller]
E[Window Management]
F[State Management]
end
subgraph "Business Logic Layer"
G[Shared Business Logic]
H[Game Engine Integration]
I[Plugin Framework]
end
subgraph "Data Layer"
J[Configuration Storage]
K[Game Data Cache]
L[Network Communication]
end
A --> D
B --> D
C --> D
D --> G
D --> H
D --> I
G --> J
H --> K
H --> L
```

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

### Cross-Platform UI Abstraction

The system achieves cross-platform compatibility through abstraction layers:

```mermaid
classDiagram
class IDispatcher {
<<interface>>
+Invoke(action) void
+BeginInvoke(action) void
+Synchronize(context) void
}
class AvaloniaDispatcher {
+Invoke(action) void
+BeginInvoke(action) void
+Synchronize(context) void
}
class WPFDispatcher {
+Invoke(action) void
+BeginInvoke(action) void
+Synchronize(context) void
}
class IUIInvoker {
<<interface>>
+ShowMessageBox(message) void
+OpenFileDialog() string
+SaveFileDialog() string
}
class AvaloniaUIInvoker {
+ShowMessageBox(message) void
+OpenFileDialog() string
+SaveFileDialog() string
}
class WPFUIInvoker {
+ShowMessageBox(message) void
+OpenFileDialog() string
+SaveFileDialog() string
}
IDispatcher <|.. AvaloniaDispatcher
IDispatcher <|.. WPFDispatcher
IUIInvoker <|.. AvaloniaUIInvoker
IUIInvoker <|.. WPFUIInvoker
```

**Diagram sources**
- [ClassicAssist.Shared/IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
- [ClassicAssist.Avalonia/AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
- [ClassicAssist/WPFDispatcher.cs](file://ClassicAssist/WPFDispatcher.cs)

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

## Detailed Component Analysis

### Main Application Flow

The application initialization and main flow follows a structured startup sequence:

```mermaid
sequenceDiagram
participant Program as "Program.Main"
participant App as "Avalonia Application"
participant Engine as "Shared Engine"
participant MainWindow as "Main Window"
participant ViewModel as "Main Window ViewModel"
Program->>App : Initialize Application
App->>Engine : Load Shared Engine
Engine->>Engine : Initialize Plugins
Engine->>Engine : Setup Network
App->>MainWindow : Create Main Window
MainWindow->>ViewModel : Bind ViewModel
ViewModel->>Engine : Request Initial Data
Engine-->>ViewModel : Provide Data
ViewModel-->>MainWindow : Update UI
```

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

### Data Flow Architecture

The system implements a unidirectional data flow pattern ensuring predictable state updates:

```mermaid
flowchart TD
A[Network Packet] --> B[Packet Handler]
B --> C{Filter Check}
C --> |Pass| D[Business Logic Processor]
C --> |Blocked| E[Discard]
D --> F[State Manager]
F --> G[ViewModel Update]
G --> H[UI Binding]
H --> I[Visual Update]
J[User Action] --> K[Command Handler]
K --> L[Business Logic]
L --> M[Network Outgoing]
M --> N[Game Server]
```

**Diagram sources**
- [ClassicAssist.Shared/UO/Network/PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
- [ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)

### Plugin System Implementation

The extensible plugin architecture supports multiple extension points:

```mermaid
classDiagram
class PluginManager {
-Dictionary~string,PluginBase~ plugins
+LoadPlugins(path) void
+GetPlugin(name) PluginBase
+ExecutePlugin(name, context) object
+UnloadPlugin(name) void
}
class PluginBase {
<<abstract>>
#string name
#string version
#string description
+virtual Initialize() void
+virtual Execute(context) object
+virtual Dispose() void
}
class MacroPlugin {
+MacroEntry[] macros
+RegisterCommands() void
+ExecuteMacro(name) void
}
class AgentPlugin {
+IAgent[] agents
+StartAgents() void
+StopAgents() void
}
PluginManager --> PluginBase : manages
PluginBase <|-- MacroPlugin
PluginBase <|-- AgentPlugin
```

**Diagram sources**
- [ClassicAssist.Shared/Data/Macros/MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)

**Section sources**
- [ClassicAssist.Avalonia/Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [ClassicAssist.Avalonia/Views/MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
- [ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)

## Dependency Analysis

### Component Coupling and Cohesion

The system demonstrates high cohesion within modules and loose coupling between components:

```mermaid
graph TB
subgraph "High Cohesion Modules"
A[Network Module]
B[UI Module]
C[Plugin Module]
D[Data Module]
end
subgraph "Low Coupling Interfaces"
E[IDispatcher]
F[IUIInvoker]
G[IPlugin]
H[IConfigProvider]
end
A --> E
B --> F
C --> G
D --> H
```

### External Dependencies Management

The system manages external dependencies through NuGet packages and assembly references:

```mermaid
graph LR
subgraph "Core Dependencies"
A[Avalonia Framework]
B[Newtonsoft.Json]
C[Microsoft.CSharp]
end
subgraph "Game Integration"
D[UO Protocol Parser]
E[Memory Access Libraries]
end
subgraph "UI Extensions"
F[Avalonia.Controls]
G[Avalonia.Themes]
end
A --> F
A --> G
B --> C
D --> E
```

**Diagram sources**
- [ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.Shared/ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)

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

## Performance Considerations

### Memory Management and Optimization

The system implements several performance optimization strategies:

- **Object Pooling**: Reusable objects for frequently created instances
- **Lazy Loading**: Deferred loading of heavy resources
- **Background Processing**: Asynchronous operations for non-blocking UI
- **Event Aggregation**: Efficient event handling patterns

### Threading Model

The application uses a single-threaded UI model with background workers:

```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Initializing : "Application Start"
Initializing --> Running : "Engine Ready"
Running --> Paused : "Pause Request"
Paused --> Running : "Resume Request"
Running --> Stopping : "Shutdown"
Stopping --> [*] : "Cleanup Complete"
```

## Troubleshooting Guide

### Common Issues and Solutions

#### Network Connectivity Problems
- Verify Ultima Online client connection status
- Check firewall settings for port access
- Validate packet filter configurations

#### UI Rendering Issues
- Ensure proper dispatcher usage for thread safety
- Verify Avalonia theme resource loading
- Check for memory leaks in custom controls

#### Plugin Loading Failures
- Validate plugin assembly signatures
- Check dependency version compatibility
- Review plugin manifest files

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

## Conclusion

ClassicAssist.Avalonia demonstrates a well-architected cross-platform game assistant application that successfully balances code reuse, maintainability, and extensibility. The layered architecture with clear separation of concerns enables efficient development across multiple UI frameworks while providing a robust foundation for plugin-based extensions.

The system's design principles emphasize:
- **Separation of Concerns**: Clear boundaries between UI, business logic, and data layers
- **Cross-Platform Compatibility**: Abstracted interfaces enabling multiple UI implementations
- **Extensibility**: Plugin architecture supporting third-party enhancements
- **Performance**: Optimized data flow and memory management strategies

This architectural approach ensures long-term maintainability while providing a solid foundation for future feature additions and platform support expansion.