# Deployment and Distribution

<cite>
**Referenced Files in This Document**
- [ClassicAssist.sln](file://ClassicAssist.sln)
- [appveyor.yml](file://appveyor.yml)
- [azure-pipelines.yml](file://azure-pipelines.yml)
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
- [ClassicAssist.csproj](file://ClassicAssist/ClassicAssist.csproj)
- [ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj)
- [ClassicAssist.Launcher.csproj](file://ClassicAssist.Launcher/ClassicAssist.Launcher.csproj)
- [ClassicAssist.Updater.csproj](file://ClassicAssist.Updater/ClassicAssist.Updater.csproj)
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.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 provides comprehensive deployment and distribution guidance for ClassicAssist.Avalonia, a cross-platform Ultima Online assistant application built with Avalonia UI framework. The system supports multiple platforms including Windows, macOS, and Linux, with automated build pipelines and update mechanisms.

The application follows a modular architecture with separate components for the main application, launcher, updater, and shared functionality. This structure enables flexible deployment strategies and platform-specific optimizations.

## Project Structure

The ClassicAssist.Avalonia solution consists of multiple projects organized by functionality:

```mermaid
graph TB
subgraph "Solution Structure"
SLN[ClassicAssist.sln]
subgraph "Main Applications"
AVA[ClassicAssist.Avalonia]
LAUNCHER[ClassicAssist.Launcher]
UPDATER[ClassicAssist.Updater]
end
subgraph "Core Libraries"
SHARED[ClassicAssist.Shared]
CLASSIC[ClassicAssist]
end
subgraph "Testing"
TESTS[ClassicAssist.Tests]
UITEST[ClassicAssist.UITest]
end
subgraph "Tools"
EXPORT[ExportCommands]
end
end
SLN --> AVA
SLN --> LAUNCHER
SLN --> UPDATER
SLN --> SHARED
SLN --> CLASSIC
SLN --> TESTS
SLN --> UITEST
SLN --> EXPORT
AVA --> SHARED
AVA --> CLASSIC
LAUNCHER --> SHARED
UPDATER --> SHARED
```

**Diagram sources**
- [ClassicAssist.sln](file://ClassicAssist.sln)

The solution is structured to support both WPF (legacy) and Avalonia (modern) UI frameworks, with the Avalonia version being the primary target for cross-platform deployment.

**Section sources**
- [ClassicAssist.sln](file://ClassicAssist.sln)

## Core Components

### Build System Architecture

The build system leverages MSBuild with .NET SDK-style project files, supporting multi-targeting for different platforms and frameworks.

#### Key Build Configuration Points

1. **Multi-targeting Support**: Projects target multiple .NET versions for compatibility
2. **Cross-platform Compilation**: Avalonia framework enables Windows, macOS, and Linux builds
3. **Asset Management**: Embedded resources and content files are handled through project configuration
4. **Platform-specific Optimizations**: Conditional compilation for platform-specific features

#### Project Dependencies

```mermaid
graph LR
subgraph "Runtime Dependencies"
DOTNET[.NET Runtime]
AVALONIA[Avalonia Framework]
UO[UO Game Client]
end
subgraph "Build Dependencies"
MSBUILD[MSBuild]
NUGET[NuGet Packages]
GIT[Git Version Control]
end
subgraph "Deployment Artifacts"
WIN[Windows Installer]
MAC[macOS Package]
LINUX[Linux Package]
CONTAINER[Docker Image]
end
DOTNET --> WIN
DOTNET --> MAC
DOTNET --> LINUX
AVALONIA --> WIN
AVALONIA --> MAC
AVALONIA --> LINUX
UO --> WIN
UO --> MAC
UO --> LINUX
MSBUILD --> WIN
MSBUILD --> MAC
MSBUILD --> LINUX
NUGET --> WIN
NUGET --> MAC
NUGET --> LINUX
GIT --> WIN
GIT --> MAC
GIT --> LINUX
```

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

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

## Architecture Overview

### Application Architecture

The ClassicAssist.Avalonia application follows a layered architecture pattern with clear separation of concerns:

```mermaid
classDiagram
class Program {
+Main(args) void
+CreateBuilder() AppBuilder
}
class App {
+OnFrameworkInitializationCompleted() void
+ConfigureServices() void
+SetupApplication() void
}
class Engine {
+Initialize() void
+Start() void
+Stop() void
+UpdateCheck() bool
}
class MainWindow {
+DataContext MainWindowViewModel
+InitializeComponent() void
+OnLoaded() void
}
class SharedComponents {
<<library>>
+DataModels
+BusinessLogic
+Utilities
}
Program --> App : "initializes"
App --> Engine : "configures"
App --> MainWindow : "creates"
MainWindow --> SharedComponents : "uses"
Engine --> SharedComponents : "depends on"
```

**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)

### Update System Architecture

The auto-update system provides seamless version management with rollback capabilities:

```mermaid
sequenceDiagram
participant App as "Main Application"
participant Updater as "Updater Process"
participant Server as "Update Server"
participant FileSystem as "File System"
App->>Updater : CheckForUpdates()
Updater->>Server : GET /api/versions/latest
Server-->>Updater : LatestVersionInfo
Updater->>Updater : CompareVersions()
alt New Version Available
Updater->>Server : DownloadUpdate(version)
Server-->>Updater : UpdatePackage
Updater->>FileSystem : VerifySignature()
Updater->>FileSystem : BackupCurrentVersion()
Updater->>FileSystem : InstallNewVersion()
Updater->>App : RestartWithNewVersion()
else No Updates
Updater->>App : ContinueRunning()
end
Note over App,FileSystem : Rollback if update fails
```

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

## Detailed Component Analysis

### Build Pipeline Configuration

#### Multi-Targeting Strategy

The project uses conditional compilation and platform-specific configurations to support multiple targets:

| Target Platform | Framework | Output Format | Special Requirements |
|----------------|-----------|---------------|---------------------|
| Windows (.NET 8.0) | net8.0-windows | EXE/DLL | Windows SDK, Visual Studio |
| macOS (.NET 8.0) | net8.0-macos | APP Bundle | Xcode Command Line Tools |
| Linux (.NET 8.0) | net8.0 | Self-contained | Platform dependencies |
| Cross-platform | net8.0 | Portable | .NET Runtime only |

#### Build Stages

1. **Source Compilation**: C# code compilation with Roslyn compiler
2. **Resource Processing**: XAML/Axaml processing and asset embedding
3. **Native Dependencies**: Platform-specific native library linking
4. **Packaging**: Application bundling and artifact generation
5. **Signing**: Code signing and integrity verification
6. **Distribution**: Artifact publishing to release channels

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

### Auto-Update System Implementation

#### Version Management

The update system implements semantic versioning with automatic comparison logic:

```mermaid
flowchart TD
Start([Application Start]) --> CheckLocal["Read Local Version"]
CheckLocal --> FetchRemote["Fetch Remote Manifest"]
FetchRemote --> ParseRemote["Parse Remote Version"]
ParseRemote --> Compare{"Version > Local?"}
Compare --> |Yes| Download["Download Update Package"]
Compare --> |No| Skip["Skip Update"]
Download --> Verify["Verify Digital Signature"]
Verify --> ValidSig{"Signature Valid?"}
ValidSig --> |No| Error["Display Security Warning"]
ValidSig --> |Yes| Backup["Backup Current Installation"]
Backup --> Install["Install New Version"]
Install --> TestRun["Test Run New Version"]
TestRun --> Success{"Test Successful?"}
Success --> |Yes| Complete["Complete Update"]
Success --> |No| Rollback["Rollback to Previous Version"]
Skip --> End([Continue Running])
Error --> End
Complete --> End
Rollback --> End
```

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

#### Update Server Configuration

The update server requires specific endpoints and response formats:

| Endpoint | Method | Purpose | Response Format |
|----------|--------|---------|-----------------|
| `/api/versions/latest` | GET | Get latest version info | JSON manifest |
| `/api/updates/{version}` | GET | Download update package | Binary stream |
| `/api/signatures/{version}` | GET | Get signature file | Cryptographic signature |
| `/api/changelog/{version}` | GET | Get version changelog | Markdown text |

**Section sources**
- [ClassicAssist.Updater.csproj](file://ClassicAssist.Updater/ClassicAssist.Updater.csproj)

### Distribution Channels

#### Windows Distribution

Windows deployments support multiple installation methods:

1. **MSI Installer**: Traditional Windows installer with registry integration
2. **Portable Executable**: Standalone executable without installation
3. **Microsoft Store**: Modern app store distribution
4. **Chocolatey**: Package manager distribution

#### macOS Distribution

macOS deployments utilize Apple's ecosystem:

1. **DMG Disk Image**: Standard macOS disk image format
2. **PKG Installer**: System-level installation with permissions
3. **Homebrew**: Package manager distribution
4. **App Bundle**: Self-contained application bundle

#### Linux Distribution

Linux deployments support various package formats:

1. **AppImage**: Portable Linux application format
2. **Snap Package**: Canonical's containerized packages
3. **Flatpak**: Universal Linux package format
4. **DEB/RPM**: Native package manager formats

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

## Dependency Analysis

### External Dependencies

The application has several critical external dependencies that must be managed during deployment:

```mermaid
graph TB
subgraph "Critical Dependencies"
DOTNETCORE[.NET 8.0 Runtime]
AVALONIAUI[Avalonia UI Framework]
SERIALIZATION[System.Text.Json]
LOGGING[Serilog Logging]
CONFIGURATION[Configuration Management]
end
subgraph "Optional Dependencies"
PYTHON[Python Integration]
NATIVE[Native Libraries]
DATABASE[SQLite Database]
NETWORK[HTTP Client]
end
subgraph "Platform Specific"
WINSDK[Windows SDK]
XCODE[Xcode Tools]
LINUXDEPS[Linux Dependencies]
end
DOTNETCORE --> AVALONIAUI
AVALONIAUI --> SERIALIZATION
AVALONIAUI --> LOGGING
AVALONIAUI --> CONFIGURATION
SERIALIZATION --> PYTHON
LOGGING --> DATABASE
CONFIGURATION --> NETWORK
WINSDK --> DOTNETCORE
XCODE --> DOTNETCORE
LINUXDEPS --> DOTNETCORE
```

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

### Build-Time Dependencies

Build-time dependencies include development tools and packaging utilities:

| Tool | Purpose | Platform Support |
|------|---------|------------------|
| MSBuild | Project compilation | All platforms |
| NuGet | Package management | All platforms |
| Signtool | Code signing | Windows only |
| codesign | Apple code signing | macOS only |
| fpm | Package creation | All platforms |
| docker | Containerization | All platforms |

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

## Performance Considerations

### Build Optimization

Several strategies can optimize build performance:

1. **Incremental Builds**: Leverage MSBuild incremental compilation
2. **Parallel Compilation**: Enable parallel project building
3. **Artifact Caching**: Cache NuGet packages and build artifacts
4. **Conditional Compilation**: Use preprocessor directives for platform-specific code
5. **Trimming**: Enable .NET trimming for reduced deployment size

### Runtime Performance

Runtime performance considerations include:

1. **Memory Management**: Efficient memory usage patterns
2. **I/O Operations**: Asynchronous file operations for better responsiveness
3. **Network Requests**: Connection pooling and caching strategies
4. **UI Rendering**: Optimized Avalonia rendering pipeline usage
5. **Background Processing**: Proper thread management for long-running tasks

## Troubleshooting Guide

### Common Build Issues

| Issue | Symptoms | Resolution |
|-------|----------|------------|
| Missing .NET Runtime | Application fails to start | Install .NET 8.0 Runtime |
| Platform-specific errors | Crashes on specific OS | Verify platform dependencies |
| Permission denied | Cannot write to installation directory | Run with elevated privileges |
| Network timeout | Update check fails | Check firewall/proxy settings |
| Invalid signature | Update rejected | Verify certificate chain |

### Deployment Validation

Post-deployment validation steps:

1. **Installation Verification**: Confirm all files are present
2. **Permission Testing**: Verify read/write access to required directories
3. **Network Connectivity**: Test update server connectivity
4. **Signature Validation**: Verify digital signatures
5. **Functionality Testing**: Run core application features

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

## Conclusion

ClassicAssist.Avalonia provides a robust, cross-platform deployment architecture supporting multiple distribution channels and update mechanisms. The modular design enables flexible deployment strategies while maintaining security and reliability through digital signatures and rollback capabilities.

The CI/CD pipeline ensures consistent builds across platforms, while the update system provides seamless version management. Platform-specific optimizations ensure optimal performance on each target operating system.

## Appendices

### Quick Start Deployment Checklist

- [ ] Install required development tools
- [ ] Configure build environment variables
- [ ] Set up code signing certificates
- [ ] Configure update server endpoints
- [ ] Test builds on all target platforms
- [ ] Validate digital signatures
- [ ] Deploy to staging environment
- [ ] Perform smoke testing
- [ ] Release to production channels

### Environment Variables

| Variable | Purpose | Default Value |
|----------|---------|---------------|
| `SIGNING_CERT_PATH` | Path to signing certificate | None |
| `UPDATE_SERVER_URL` | Update server endpoint | https://updates.classicassist.com |
| `BUILD_CONFIGURATION` | Build configuration | Release |
| `TARGET_PLATFORM` | Target platform | net8.0 |
| `OUTPUT_DIRECTORY` | Build output path | ./bin/Release |