# アーキテクチャ設計書

## 概要

本ドキュメントは、Avalonia UIフレームワークのアーキテクチャ設計について記述します。Avaloniaは、クロスプラットフォームのデスクトップUIフレームワークであり、Windows、macOS、Linux、iOS、Android、WebAssemblyで動作します。WPF（Windows Presentation Foundation）に影響を受けた設計で、XAMLベースの宣言的UIとMVVMパターンをサポートしています。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照してください。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| SkiaSharp | ネイティブライブラリ連携 | 2Dグラフィックスレンダリング |
| HarfBuzzSharp | ネイティブライブラリ連携 | テキストシェーピング |
| Windows API (Win32/DirectX) | P/Invoke/COM | Windows固有のウィンドウ管理・レンダリング |
| macOS Native (Cocoa) | Native Interop | macOS固有のウィンドウ管理・レンダリング |
| X11/FreeDesktop | ネイティブ連携 | Linux固有のウィンドウ管理 |
| OpenGL/Vulkan/Metal | GPU API | ハードウェアアクセラレーション |
| WebAssembly | ブラウザAPI | Web環境でのレンダリング |

## レイヤー構成

### アーキテクチャスタイル

Avaloniaは**レイヤードアーキテクチャ**と**プラットフォーム抽象化パターン**を採用しています。コアとなるUI機能を抽象化し、プラットフォーム固有の実装を分離することで、クロスプラットフォーム対応を実現しています。また、依存性注入（DI）パターンを活用し、コンポーネント間の疎結合を維持しています。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Application | アプリケーションライフサイクル管理、テーマ、リソース管理 | Application, AppBuilder, ApplicationLifetimes |
| Controls | UIコントロールの実装、レイアウト管理 | Button, TextBox, Grid, StackPanel, ItemsControl等 |
| Base | コアプロパティシステム、データバインディング、スタイリング、レンダリング基盤 | AvaloniaObject, AvaloniaProperty, StyledElement, Visual |
| Media | グラフィックス描画、ブラシ、ジオメトリ、アニメーション | DrawingContext, Brush, Geometry, Transform |
| Platform | プラットフォーム抽象化インターフェース | IPlatformRenderInterface, IPlatformSettings |
| Platform Implementations | プラットフォーム固有実装 | Avalonia.Win32, Avalonia.Native, Avalonia.X11, Avalonia.Browser |
| Rendering | レンダリングエンジン、コンポジション | Compositor, ImmediateRenderer, CompositingRenderer |

### レイヤー間の依存関係ルール

```
Application Layer
       |
       v
Controls Layer -----> Markup Layer (XAML)
       |
       v
   Base Layer <-----> Media Layer
       |
       v
 Platform Layer (抽象インターフェース)
       |
       v
Platform Implementations
       |
       v
  Rendering Backend (Skia/GPU)
```

**依存の方向性:**
- 上位レイヤーは下位レイヤーに依存
- 下位レイヤーは上位レイヤーに依存しない（依存関係逆転の原則）
- プラットフォーム固有実装はPlatform Layerの抽象に依存

**許可される参照:**
- Controls -> Base, Media
- Application -> Controls, Base
- Platform Implementations -> Base, Platform

**禁止される参照:**
- Base -> Controls
- Platform -> Platform Implementations

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Core Property System | 依存プロパティシステム、値継承、変更通知 | Avalonia.Base (AvaloniaObject, AvaloniaProperty) |
| Visual Tree | ビジュアルツリー管理、レイアウト計算 | Avalonia.Base (Visual, VisualTree) |
| Logical Tree | 論理ツリー管理、データコンテキスト継承 | Avalonia.Base (LogicalTree) |
| Styling | スタイル適用、セレクタ評価、テーマバリアント | Avalonia.Base (Styling) |
| Data Binding | データバインディング、バリューコンバーター | Avalonia.Base (Data, Data.Core) |
| Input Handling | 入力イベント処理、フォーカス管理、ジェスチャ認識 | Avalonia.Base (Input) |
| Rendering | 描画コンテキスト、コンポジション、GPU連携 | Avalonia.Base (Rendering), Avalonia.Skia |
| Controls | 標準UIコントロール群 | Avalonia.Controls |
| XAML | XAMLパース、マークアップ拡張 | Avalonia.Markup.Xaml |
| Themes | Fluentテーマ、Simpleテーマ | Avalonia.Themes.Fluent, Avalonia.Themes.Simple |
| Platform Windows | Windows固有実装 | Avalonia.Win32 |
| Platform macOS | macOS固有実装 | Avalonia.Native |
| Platform Linux | Linux固有実装 | Avalonia.X11, Avalonia.FreeDesktop |
| Platform Browser | WebAssembly実装 | Avalonia.Browser |
| Platform Mobile | iOS/Android実装 | Avalonia.iOS, Avalonia.Android |

### パッケージ構造

```
src/
├── Avalonia.Base/                    # コアライブラリ
│   ├── Animation/                    # アニメーションシステム
│   ├── Collections/                  # コレクション型
│   ├── Controls/                     # 基本コントロール抽象
│   ├── Data/                         # データバインディング
│   │   ├── Core/                     # バインディングコア
│   │   └── Converters/               # バリューコンバーター
│   ├── Diagnostics/                  # 診断・デバッグ
│   ├── Input/                        # 入力処理
│   │   ├── GestureRecognizers/       # ジェスチャ認識
│   │   ├── Platform/                 # プラットフォーム入力
│   │   ├── Raw/                      # 生入力イベント
│   │   └── TextInput/                # テキスト入力
│   ├── Interactivity/                # インタラクティブ動作
│   ├── Layout/                       # レイアウトシステム
│   ├── Logging/                      # ログ機能
│   ├── LogicalTree/                  # 論理ツリー
│   ├── Media/                        # メディア・グラフィックス
│   │   ├── Effects/                  # エフェクト
│   │   ├── Fonts/                    # フォント管理
│   │   ├── Imaging/                  # 画像処理
│   │   ├── Immutable/                # 不変メディアオブジェクト
│   │   └── TextFormatting/           # テキストフォーマット
│   ├── Metadata/                     # メタデータ
│   ├── Platform/                     # プラットフォーム抽象
│   │   ├── Internal/                 # 内部実装
│   │   ├── Interop/                  # 相互運用
│   │   └── Storage/                  # ストレージ
│   ├── PropertyStore/                # プロパティ値ストア
│   ├── Reactive/                     # リアクティブ拡張
│   ├── Rendering/                    # レンダリングコア
│   │   ├── Composition/              # コンポジションレンダラー
│   │   │   ├── Animations/           # コンポジションアニメーション
│   │   │   ├── Brushes/              # コンポジションブラシ
│   │   │   ├── Drawing/              # 描画コマンド
│   │   │   ├── Expressions/          # 式評価
│   │   │   ├── Server/               # サーバーサイド
│   │   │   └── Transport/            # トランスポート
│   │   └── SceneGraph/               # シーングラフ
│   ├── Styling/                      # スタイリングシステム
│   │   └── Activators/               # スタイルアクティベータ
│   ├── Threading/                    # スレッディング
│   ├── Utilities/                    # ユーティリティ
│   └── VisualTree/                   # ビジュアルツリー
├── Avalonia.Controls/                # 標準コントロール
│   ├── ApplicationLifetimes/         # ライフタイム管理
│   ├── Automation/                   # UIオートメーション
│   ├── Calendar/                     # カレンダー
│   ├── DateTimePickers/              # 日時ピッカー
│   ├── Documents/                    # ドキュメント
│   ├── Flyouts/                      # フライアウト
│   ├── Notifications/                # 通知
│   ├── Platform/                     # プラットフォーム固有
│   ├── Presenters/                   # プレゼンター
│   ├── Primitives/                   # プリミティブ
│   ├── Selection/                    # 選択管理
│   ├── Shapes/                       # 図形
│   ├── SplitButton/                  # スプリットボタン
│   ├── SplitView/                    # スプリットビュー
│   ├── Templates/                    # テンプレート
│   └── Utils/                        # ユーティリティ
├── Avalonia.Desktop/                 # デスクトップ統合
├── Markup/
│   ├── Avalonia.Markup/              # マークアップ基盤
│   ├── Avalonia.Markup.Xaml/         # XAMLサポート
│   └── Avalonia.Markup.Xaml.Loader/  # XAMLローダー
├── Skia/
│   └── Avalonia.Skia/                # Skiaレンダリング
├── Avalonia.OpenGL/                  # OpenGLサポート
├── Avalonia.Vulkan/                  # Vulkanサポート
├── Avalonia.Metal/                   # Metalサポート
├── Avalonia.Themes.Fluent/           # Fluentテーマ
├── Avalonia.Themes.Simple/           # Simpleテーマ
├── Windows/
│   ├── Avalonia.Win32/               # Windows実装
│   ├── Avalonia.Win32.Automation/    # Windows UIオートメーション
│   └── Avalonia.Win32.Interoperability/ # WPF相互運用
├── Avalonia.Native/                  # macOS実装
├── Avalonia.X11/                     # X11実装
├── Avalonia.FreeDesktop/             # FreeDesktop統合
├── Linux/
│   └── Avalonia.LinuxFramebuffer/    # Linuxフレームバッファ
├── Browser/
│   └── Avalonia.Browser/             # WebAssembly実装
├── Android/
│   └── Avalonia.Android/             # Android実装
├── iOS/
│   └── Avalonia.iOS/                 # iOS実装
├── Headless/
│   ├── Avalonia.Headless/            # ヘッドレス実行
│   ├── Avalonia.Headless.XUnit/      # XUnitテスト
│   └── Avalonia.Headless.NUnit/      # NUnitテスト
└── tools/
    ├── Avalonia.Generators/          # コード生成
    └── Avalonia.Analyzers.*/         # コードアナライザー
```

### コンポーネント依存関係

**コアコンポーネント依存:**
- `Avalonia.Controls` -> `Avalonia.Base`, `Avalonia.Remote.Protocol`
- `Avalonia.Markup.Xaml` -> `Avalonia.Base`, `Avalonia.Controls`, `Avalonia.Markup`
- `Avalonia.Skia` -> `Avalonia（パッケージ）`

**プラットフォーム依存:**
- `Avalonia.Win32` -> `Avalonia（パッケージ）`, `Avalonia.Win32.Automation`
- `Avalonia.Native` -> `Avalonia（パッケージ）`, `Avalonia.Dialogs`
- `Avalonia.X11` -> `Avalonia.FreeDesktop`

## ミドルウェア構成

### グラフィックスライブラリ

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| 2Dレンダリング | SkiaSharp | NuGetパッケージ | クロスプラットフォーム2Dグラフィックス |
| テキストシェーピング | HarfBuzzSharp | NuGetパッケージ | 高品質テキストレンダリング |
| Windows GPU | ANGLE | 2.1.x | Windows上でのOpenGL ES実装 |
| Windows GPU | Direct3D 11 | OS標準 | Windows DirectX レンダリング |
| macOS GPU | Metal | OS標準 | macOS GPUアクセラレーション |
| Linux GPU | Vulkan | OS依存 | Linux GPUアクセラレーション |

### ビルドツール

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| .NET SDK | 10.0.101 | ビルド・実行環境 |
| Microsoft.Build.Traversal | 4.1.0 | マルチプロジェクトビルド |
| MicroCom.CodeGenerator | 0.11.0 | COM相互運用コード生成 |
| CsWin32 | 0.3.257 | Win32 API P/Invoke生成 |

### コード生成・アナライザー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Avalonia.Generators | 内部 | 型付きNameOf等のコード生成 |
| DevAnalyzers | 内部 | 開発時コード解析 |
| Avalonia.Analyzers.CSharp | 内部 | Avalonia固有の解析ルール |

## データフロー

### リクエスト処理の流れ（入力イベント）

1. **プラットフォーム入力受信**: Win32/Cocoa/X11等のネイティブ入力イベントを受信
2. **Raw Input変換**: `RawInputEventArgs` に変換してInputManagerへ転送
3. **InputManager処理**: イベントのルーティング・前処理
4. **PointerOverPreProcessor**: ポインター位置に基づくヒットテスト
5. **ビジュアルツリートラバース**: イベントターゲットを特定
6. **トンネル/バブルルーティング**: Preview*イベント（トンネル）、*イベント（バブル）の発火
7. **イベントハンドラ実行**: コントロールのイベントハンドラが処理
8. **コマンド実行（オプション）**: ICommandバインディングの実行

### レンダリングの流れ

1. **InvalidateVisual呼び出し**: UIの変更検知
2. **レイアウトパス**: Measure/Arrangeの実行
3. **コンポジションツリー更新**: 変更をコンポジションツリーに反映
4. **Compositor同期**: UIスレッドからレンダースレッドへの同期
5. **描画コマンド生成**: DrawingContextを通じた描画コマンドの記録
6. **GPUサブミット**: Skia/GPU APIを通じたレンダリング
7. **スワップチェーン表示**: 画面への反映

### データバインディングの流れ

1. **バインディング定義**: XAMLまたはコードでバインディングを設定
2. **CompiledBinding/ReflectionBinding**: バインディング式の評価
3. **ソース値取得**: DataContextからプロパティパスを解決
4. **コンバーター適用（オプション）**: IValueConverterでの値変換
5. **ターゲットプロパティ更新**: AvaloniaPropertyの値を更新
6. **変更通知**: PropertyChangedイベントの発火
7. **再レンダリングトリガー**: 必要に応じてInvalidateVisual

## 横断的関心事

### スタイリング・テーマ

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| セレクタベースのスタイル | Avalonia.Base/Styling/ | 全UIコントロール |
| ControlTheme | Avalonia.Base/Styling/ControlTheme.cs | コントロールテーマ |
| ThemeVariant | Avalonia.Base/Styling/ThemeVariant.cs | ライト/ダークテーマ切り替え |
| リソースディクショナリ | Avalonia.Controls/ResourceDictionary | 共有リソース |

### ロギング・診断

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | Avalonia.Logging（ILogSink） | カスタマイズ可能 |
| 診断情報 | Avalonia.Diagnostics | デバッグウィンドウ |
| レンダリング診断 | RendererDiagnostics | オーバーレイ表示 |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| XAML解析エラー | XamlLoadException | 例外スロー、詳細メッセージ |
| バインディングエラー | BindingNotification | Error状態の伝播、フォールバック値 |
| レンダリングエラー | RenderTargetCorruptedException | ターゲット再作成 |
| プラットフォームエラー | AvaloniaInternalException | 内部エラーとして処理 |

### スレッディング管理

| 範囲 | 管理方式 | 備考 |
| --- | --- | --- |
| UIスレッド | Dispatcher | 単一UIスレッドモデル |
| レンダースレッド | Compositor | 独立したレンダリングスレッド |
| スレッドアクセス検証 | VerifyAccess | UIオブジェクトへのスレッドセーフティ |
| 非同期ディスパッチ | Dispatcher.InvokeAsync | バックグラウンドからUIスレッドへ |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 依存関係逆転 (DIP) | Platform Layer | IPlatformRenderInterface, IPlatformSettings |
| 単一責任 (SRP) | コントロール分離 | Button, TextBox等の独立した責務 |
| オープン/クローズド (OCP) | スタイルシステム | セレクタによる外部からの拡張 |
| インターフェース分離 (ISP) | プラットフォーム抽象 | 細分化されたプラットフォームインターフェース |
| コンポジション | ビジュアルツリー | Visual, Control間のコンポジション |

### コーディング規約

- **C#コーディング規約**: .editorconfigによる統一
- **名前空間構成**: Avaloniaルート名前空間の下に機能別に分類
- **Nullableの有効化**: NullableEnable.propsで全プロジェクトで有効
- **トリミング対応**: TrimmingEnable.propsでAOT/トリミングサポート
- **InternalsVisibleTo**: テストプロジェクトとの内部アクセス許可
- **プロパティ定義**: StyledPropertyまたはDirectPropertyの使用

## 備考

- Avaloniaは.NET Standard 2.0以上をターゲットとし、.NET Framework 4.6.2以上および.NET Core/.NET 5以上で動作
- GPUアクセラレーションはオプションであり、ソフトウェアレンダリングへのフォールバックをサポート
- XAMLコンパイルにより実行時のパフォーマンスを最適化
- コンポジションレンダラーにより、アニメーションとスクロールがスムーズに動作
