# アーキテクチャ設計書

## 概要

本ドキュメントは、Windows Terminal (microsoft/terminal) プロジェクトのアプリケーションアーキテクチャを記述する。Windows Terminal は、Windows Console Host (`conhost.exe`) と Windows Terminal (`WindowsTerminal.exe`) の2つの主要プロダクトを含むモノレポ構成のC++/C++WinRTプロジェクトである。コンポーネントベースのレイヤードアーキテクチャを採用しており、コアターミナルエミュレーション機能を共有コンポーネントとして抽出し、複数のフロントエンド（Windows Terminal UI / Console Host）から利用する設計となっている。

## システム全体構成

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

[アーキテクチャ構成図](./アーキテクチャ構成図.md) を参照。

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Windows ConPTY (conpty) | Win32 API / パイプ通信 | 疑似コンソール（Pseudo Console）を介したシェルプロセスとの入出力通信 |
| シェルプロセス (cmd, PowerShell, WSL等) | ConPTY経由のパイプ | ユーザーコマンドの実行とその出力の受信 |
| Windows Console Driver (condrv.sys) | カーネルドライバ通信 | Console Host利用時のコンソールI/O処理 |
| DirectX / Direct3D 11 / Direct2D / DirectWrite | COM / GPU API | Atlas Rendererによるテキスト描画・GPU加速レンダリング |
| GDI | Win32 API | GDI Rendererによるレガシーテキスト描画（Console Host用） |
| Windows UI Automation (UIA) | COM | スクリーンリーダー等アクセシビリティツールとの連携 |
| XAML Islands | WinRT / XAML | Windows Terminal UIフレームワーク（WinUI 2.x / XAML） |
| Windows レジストリ | Win32 API | Console Hostの設定永続化 |
| JSON設定ファイル (settings.json) | ファイルI/O + JsonCpp | Windows Terminalの設定読み書き |
| Azure Cloud Shell | REST API | Azure接続による遠隔シェルセッション |
| OpenSSH config | ファイルI/O | SSH接続プロファイルの動的生成 |
| Microsoft Store | MSIX パッケージング | アプリケーションの配布・更新 |

## レイヤー構成

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

**コンポーネントベースのレイヤードアーキテクチャ** を採用している。明確なレイヤー間の依存関係ルールが存在し、上位レイヤーから下位レイヤーへの一方向依存を原則とする。各コンポーネントはWinRT IDL (Interface Definition Language) によるインターフェース定義を通じて疎結合を実現している。

また、以下の設計パターンが顕著に見られる:
- **コールバックパターン**: `Terminal` クラスが `std::function` コールバックを通じて上位レイヤーに通知する
- **Observerパターン**: WinRT イベントシステムによるコンポーネント間の非同期通知
- **Abstractionレイヤーパターン**: `ITerminalApi`, `IRenderData`, `ITerminalConnection` 等のインターフェースによる抽象化
- **Compositeパターン**: ペインのツリー構造による分割表示の実現

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation (UI) | ウィンドウ管理、XAML UIレンダリング、ユーザー入力のハンドリング | `WindowsTerminal` (main.cpp, WindowEmperor, AppHost, IslandWindow), `TerminalApp` (AppLogic, TerminalWindow, Tab, Pane, CommandPalette), `TerminalSettingsEditor` |
| Control | ターミナルコントロールの管理、UIとコアの仲介 | `TerminalControl` (ControlCore, ControlInteractivity, TermControl), `WpfTerminalControl` |
| Core | ターミナルエミュレーションのコアロジック、バッファ管理、VTシーケンス処理 | `TerminalCore` (Terminal), `terminal/parser` (StateMachine), `terminal/adapter` (AdaptDispatch), `terminal/input` (TerminalInput), `buffer/out` (TextBuffer) |
| Settings Model | 設定の読み込み・永続化・シリアライゼーション | `TerminalSettingsModel` (CascadiaSettings, Profile, GlobalAppSettings, ActionMap, ColorScheme) |
| Connection | シェルプロセスとの接続管理 | `TerminalConnection` (ConptyConnection, AzureConnection, EchoConnection) |
| Renderer | テキストバッファの画面描画 | `renderer/base` (Renderer), `renderer/atlas` (AtlasEngine), `renderer/gdi` (GdiEngine), `renderer/uia` (UiaEngine) |
| Shared / Infrastructure | 共通型定義、ユーティリティ、プラットフォーム抽象化 | `types`, `til` (Terminal Implementation Library), `inc`, `buffer/out`, `propslib` |
| Console Host | Windows Console Host固有の機能 | `host` (conhost), `server` (API Dispatchers, IO処理), `interactivity` (win32/onecore/base) |

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

1. **上位から下位への一方向依存**: Presentation -> Control -> Core -> Shared の順に依存する。下位レイヤーは上位レイヤーを参照しない。
2. **インターフェースによる逆方向通知**: コアからUIへの通知は `std::function` コールバック（Terminal クラス）やWinRTイベント（ControlCore クラス）を通じて行う。
3. **Rendererの特殊な位置づけ**: Renderer は Core の `IRenderData` インターフェースに依存し、Core は Renderer への参照を保持する（循環依存だが、ライフタイム管理で解決）。
4. **Connection の独立性**: Connection レイヤーは `ITerminalConnection` インターフェースを定義し、Control レイヤーから利用される。Core への直接依存は持たない。
5. **Settings Model の横断的利用**: Settings Model は Presentation, Control の各レイヤーから参照される。Core レイヤーは `ICoreSettings` インターフェースを通じて間接的に設定値を受け取る。
6. **Console Host の独自スタック**: Console Host は独自のI/Oスタック（server, host）を持つが、Core レイヤー（buffer, terminal/parser, terminal/adapter, renderer）を共有する。

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| ターミナルエミュレーション | VT100/VT220/xterm互換のターミナルエミュレーション | `terminal/parser`, `terminal/adapter`, `terminal/input`, `TerminalCore` |
| テキストバッファ管理 | 文字データの格納、属性管理、スクロールバック | `buffer/out` (TextBuffer, TextAttribute) |
| レンダリング | テキストバッファから画面への描画 | `renderer/base`, `renderer/atlas`, `renderer/gdi`, `renderer/uia` |
| ウィンドウ・UI管理 | ウィンドウ、タブ、ペイン、設定UIの管理 | `WindowsTerminal`, `TerminalApp`, `TerminalSettingsEditor`, `UIHelpers` |
| 設定管理 | ユーザー設定の読み込み・保存・検証 | `TerminalSettingsModel`, `propslib` |
| 接続管理 | シェルプロセスやリモート接続の管理 | `TerminalConnection`, `winconpty` |
| コンソールホスト | Windows Console Host (conhost.exe) の実装 | `host`, `server`, `interactivity` |
| アクセシビリティ | UIオートメーション、スクリーンリーダー対応 | `types` (UIA providers), `renderer/uia` |
| 共通基盤 | 共通型、ユーティリティライブラリ | `til`, `types`, `inc` |

### パッケージ構造

```
src/
├── cascadia/                          # Windows Terminal (Cascadia) プロダクト
│   ├── WindowsTerminal/               # エントリポイント (main.cpp, WindowEmperor, AppHost)
│   ├── TerminalApp/                   # アプリケーションロジック (AppLogic, TerminalWindow, Tab, Pane)
│   ├── TerminalControl/               # ターミナルUIコントロール (ControlCore, ControlInteractivity)
│   ├── TerminalCore/                  # ターミナルコアロジック (Terminal class)
│   ├── TerminalConnection/            # 接続抽象化 (ConptyConnection, AzureConnection)
│   ├── TerminalSettingsModel/         # 設定モデル (CascadiaSettings, Profile, ActionMap)
│   ├── TerminalSettingsEditor/        # 設定UI (XAML pages)
│   ├── TerminalSettingsAppAdapterLib/ # 設定UI アダプター
│   ├── Remoting/                      # マルチウィンドウ間通信
│   ├── ShellExtension/               # Windowsシェル拡張
│   ├── ElevateShim/                   # 権限昇格シム
│   ├── CascadiaPackage/              # MSIXパッケージ定義
│   ├── UIHelpers/                     # UI共通ヘルパー
│   ├── UIMarkdown/                    # Markdownレンダリング
│   ├── WinRTUtils/                    # WinRTユーティリティ
│   ├── WpfTerminalControl/           # WPF用ターミナルコントロール
│   ├── wt/                            # wt.exe エントリポイント (シム)
│   ├── inc/                           # 共通ヘッダ
│   └── *Tests*/                       # 各種テストプロジェクト
├── host/                              # Console Host (conhost.exe) 本体
│   ├── exe/                           # conhost実行可能ファイル
│   ├── lib/                           # conhostライブラリ
│   ├── proxy/                         # プロキシ
│   └── *ft_*/ut_*/                    # テスト
├── server/                            # コンソールサーバーAPI (ApiDispatchers, IoDispatchers)
├── terminal/                          # VTパーサー・アダプター・入力処理
│   ├── parser/                        # VTシーケンスパーサー (StateMachine)
│   ├── adapter/                       # VTシーケンスディスパッチャー (AdaptDispatch)
│   └── input/                         # ターミナル入力処理 (TerminalInput)
├── renderer/                          # レンダリングエンジン
│   ├── base/                          # レンダラー基底クラス (Renderer)
│   ├── atlas/                         # Atlas GPU レンダラー (DirectX 11)
│   ├── gdi/                           # GDI レンダラー
│   ├── uia/                           # UIオートメーション レンダラー
│   ├── wddmcon/                       # WDDMコンソール レンダラー
│   └── inc/                           # レンダラー共通ヘッダ (IRenderData)
├── buffer/
│   └── out/                           # テキストバッファ実装 (TextBuffer, TextAttribute)
├── types/                             # 共通型定義 (Viewport, ColorTable, UIA providers)
├── inc/                               # プロジェクト共通ヘッダ
│   └── til/                           # Terminal Implementation Library ヘッダ
├── til/                               # TILテストプロジェクト
├── interactivity/                     # プラットフォーム固有対話処理
│   ├── base/                          # 基底実装
│   ├── win32/                         # Win32実装
│   └── onecore/                       # OneCore実装
├── winconpty/                         # Windows Pseudo Console (ConPTY) ライブラリ
├── audio/
│   └── midi/                          # MIDIオーディオ再生
├── tsf/                               # Text Services Framework (IME) 統合
├── propslib/                          # プロパティシート・レジストリ操作
├── tools/                             # 開発ツール (ColorTool等)
├── propsheet/                         # コンソールプロパティシート
├── internal/                          # 内部専用コンポーネント
├── staging/                           # ステージング
└── samples/                           # サンプルコード
```

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

主要コンポーネントの依存関係を以下に示す。

**Windows Terminal 側**:
- `WindowsTerminal` -> `TerminalApp` -> `TerminalControl` -> `TerminalCore`
- `TerminalApp` -> `TerminalSettingsModel`
- `TerminalControl` -> `TerminalConnection`
- `TerminalControl` -> `renderer/atlas`
- `TerminalCore` -> `terminal/parser` -> `terminal/adapter`
- `TerminalCore` -> `buffer/out`
- `TerminalCore` -> `terminal/input`

**Console Host 側**:
- `host/exe` -> `host/lib` -> `server`
- `host` -> `buffer/out`
- `host` -> `terminal/parser` -> `terminal/adapter`
- `host` -> `renderer/gdi`, `renderer/atlas`
- `host` -> `interactivity/win32` or `interactivity/onecore`
- `host` -> `winconpty`

**共有コンポーネント**:
- `terminal/parser`, `terminal/adapter`, `terminal/input`: VTシーケンス処理
- `buffer/out`: テキストバッファ
- `renderer/base`: レンダラー基盤
- `types`: 共通型
- `til` (inc/til/): Terminal Implementation Library

## ミドルウェア構成

### データベース

本プロジェクトはデータベースを使用しない。設定データはJSONファイル（settings.json）およびWindowsレジストリに永続化される。

| 種類 | ミドルウェア | 用途 |
| --- | --- | --- |
| ファイルストレージ | JSON (settings.json) | Windows Terminal のユーザー設定・プロファイル・カラースキーム・キーバインド |
| レジストリ | Windows Registry | Console Host のプロパティ設定（フォント、色、サイズ等） |
| アプリケーション状態 | JSON (state.json) | ウィンドウ状態、セッション復元データ |

### キャッシュ

| ミドルウェア | 用途 | TTL |
| --- | --- | --- |
| TextBuffer (メモリ内) | ターミナル出力のスクロールバックバッファ | セッション中（設定可能な行数） |
| AtlasEngine フォントキャッシュ | グリフレンダリングキャッシュ（GPU上） | セッション中 |
| MsBuildCache | ビルドキャッシュ（Azure Pipelines / ローカル） | ビルドセッション間 |

### メッセージキュー

本プロジェクトは外部メッセージキューを使用しない。コンポーネント間通信はWin32メッセージループ、WinRTイベント、コールバック関数、パイプ通信で実現される。

### 検索エンジン

本プロジェクトは検索エンジンを使用しない。テキストバッファ内の検索は `Search` クラスにより提供される。

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| JsonCpp | 1.9.5 | JSON設定ファイルのパース・シリアライゼーション |
| fmt | 11.1.4 | 高性能文字列フォーマッティング |
| Microsoft GSL (ms-gsl) | 3.1.0 | C++ ガイドラインサポートライブラリ（span, not_null等） |
| CLI11 | 2.4.2 | コマンドライン引数パーサー |
| cmark | 0.30.3 | Markdownパーサー（Markdownペイン用） |
| WIL (Windows Implementation Libraries) | - | Windows API ラッパー・リソース管理 |
| C++/WinRT | - | WinRT コンポーネント実装・コード生成 |
| XAML Islands (WinUI 2.x) | - | Win32アプリケーション内のXAML UIホスティング |
| vcpkg | - | C++パッケージマネージャー |

## データフロー

### リクエスト処理の流れ

#### ユーザー入力からシェルプロセスへの流れ

1. ユーザーがキーボード入力を行う
2. `IslandWindow` が Win32 メッセージ（WM_KEYDOWN等）を受信する
3. `TermControl` (XAML コントロール) がキーイベントをハンドリングする
4. `ControlInteractivity` がキーイベントを処理し、キーバインド判定やマーク選択を行う
5. `ControlCore::TrySendKeyEvent()` がコアにキーイベントを転送する
6. `Terminal::SendKeyEvent()` が VT シーケンスに変換する（`TerminalInput` 経由）
7. `_pfnWriteInput` コールバックにより `ControlCore::_sendInputToConnection()` が呼ばれる
8. `ITerminalConnection::WriteInput()` によりConPTYパイプ経由でシェルプロセスに送信される

#### シェル出力からレンダリングまでの流れ

1. シェルプロセスが標準出力にデータを書き込む
2. ConPTYが出力をVTシーケンスに変換する
3. `ConptyConnection::_OutputThread()` がパイプからデータを読み取る
4. `TerminalOutput` イベントが発火し、`ControlCore::_connectionOutputHandler()` が呼ばれる
5. `Terminal::Write()` がVTシーケンスを `StateMachine` に渡す
6. `StateMachine` がVTシーケンスをパースし、`AdaptDispatch` にアクションをディスパッチする
7. `AdaptDispatch` が `ITerminalApi` を通じて `TextBuffer` を更新する
8. `Renderer` が変更を検知し、`AtlasEngine` を通じてDirectXで画面を描画する

### 非同期処理の流れ

1. **出力スロットリング**: `ControlCore` 内の `ThrottledFunc` により、高頻度の出力更新がスロットリングされる（`outputIdle` イベント）
2. **スクロールバー更新**: `updateScrollBar` が `ThrottledFunc` によりスロットリングされ、UIスレッドでのスクロールバー位置更新がバッチ処理される
3. **設定リロード**: ファイルシステム変更監視（`folder_change_reader`）が設定ファイルの変更を検知し、`ThrottledFunc` によりスロットリング後にリロードされる
4. **セッション永続化**: `WindowEmperor` の `_persistStateTimer` がタイマーベースでウィンドウ状態を定期保存する
5. **レンダリング**: `Renderer` が独自のスレッドとタイマーを持ち、無効化されたリージョンのみを非同期で再描画する

### データ永続化の流れ

1. **設定保存**: ユーザーが設定UIで変更 -> `CascadiaSettings` がJSON文字列を生成 -> `settings.json` にファイル書き込み
2. **セッション復元**: `WindowEmperor::_persistState()` -> アプリケーション状態を `ApplicationState` にシリアライズ -> `state.json` に書き込み
3. **Console Host 設定**: コンソールプロパティシートから変更 -> `RegistrySerialization` / `ShortcutSerialization` でレジストリ / ショートカットに永続化

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| 権限昇格 (UAC) | `ElevateShim`, `AppLogic::IsRunningElevated()` | 管理者権限が必要な操作の権限昇格判定 |
| Azure認証 | `AzureConnection` (OAuth Device Code Flow) | Azure Cloud Shellへの接続認証 |
| プロセスポリシー | `ProcessPolicy`, `ConsoleShimPolicy` | コンソールプロセスのアクセス制御ポリシー |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| テレメトリ | TraceLogging (ETW) | Windows Event Tracing (ETW セッション) |
| 診断ログ | TraceLogging (ETW) with TIL_KEYWORD_TRACE | Windows Event Tracing |
| UIA トレーシング | `UiaTracing` クラス（ETW） | Windows Event Tracing |
| エラーレポーティング | WIL (WilErrorReporting.h) | Windows Error Reporting |
| パフォーマンス計測 | WPR プロファイル (ConsolePerf.wprp, Terminal.wprp) | WPR セッション |

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

エラーハンドリングは WIL (Windows Implementation Libraries) のマクロとパターンを全面的に使用する。

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| Win32 API エラー | `THROW_IF_WIN32_BOOL_FALSE`, `THROW_LAST_ERROR` 等のWILマクロ | 例外としてスロー、WILによるETWログ出力 |
| HRESULT エラー | `THROW_IF_FAILED`, `RETURN_IF_FAILED` | 例外としてスロー or HRESULTとして返却 |
| レンダリングエラー | `_rendererEnteredErrorState()` コールバック | レンダリングリトライ、フォールバック（`Feature_AtlasEnginePresentFallback`） |
| 設定読み込みエラー | `SettingsTypedDeserializationException` | 警告メッセージ表示、デフォルト設定へのフォールバック |
| 接続エラー | `ConnectionState` 状態遷移 | UI上に終了ステータス表示 |
| VTパースエラー | `StateMachine` 内部で無視 | 不正なシーケンスはスキップ（VT仕様に準拠） |

### トランザクション管理

本プロジェクトはデータベーストランザクションを使用しない。データの整合性は以下の仕組みで確保される。

| 範囲 | 管理方式 | 備考 |
| --- | --- | --- |
| ターミナルバッファアクセス | `til::recursive_ticket_lock` による読み書きロック | `Terminal::LockForReading()` / `LockForWriting()` で排他制御 |
| 設定ファイル書き込み | アトミックファイル書き換え | 設定ファイルの更新はアトミックに行う |
| ConPTYパイプ書き込み | `til::ticket_lock` による排他制御 | `ConptyConnection::_writeLock` |
| レンダリング同期 | ロック + 無効化リージョン管理 | Terminal ロックとRenderer の同期 |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| インターフェース分離の原則 (ISP) | コンポーネント間境界 | `ITerminalApi`, `IRenderData`, `ITerminalConnection`, `ITerminalInput`, `ICoreSettings`, `IControlSettings` 等の細粒度インターフェース |
| 依存性逆転の原則 (DIP) | Core - Renderer間, Core - Connection間 | `Terminal` が `IRenderData` を実装し Renderer に渡す / `ITerminalConnection` による接続の抽象化 |
| 単一責任の原則 (SRP) | コンポーネント設計 | `ControlCore`(ロジック) / `ControlInteractivity`(ユーザー操作) / `TermControl`(XAML UI) の責務分離 |
| 開放閉鎖の原則 (OCP) | レンダラーの切り替え | `RenderEngineBase` を継承した複数レンダラー（Atlas, GDI, UIA, WDDM） |
| コンポジション > 継承 | ペイン管理 | `Pane` がツリー構造のコンポジションで分割レイアウトを実現 |
| Feature Flags | フィーチャー管理 | `features.xml` により機能を `AlwaysEnabled` / `AlwaysDisabled` / ブランディングトークンベースで制御 |

### コーディング規約

- **言語**: C++20 / C++/WinRT
- **コードスタイル**: `.clang-format` によるフォーマット、`.editorconfig` による基本設定
- **命名規則**: メンバ変数はアンダースコアプレフィックス (`_memberVariable`)、WinRT プロパティは PascalCase
- **静的解析**: `StaticAnalysis.ruleset` による静的コード分析、AuditMode ビルド構成
- **XAML スタイル**: `XamlStyler.json` による XAML フォーマット設定
- **ヘッダ管理**: プリコンパイル済みヘッダ (`pch.h` / `precomp.h`) の使用
- **リソース管理**: WIL のスマートハンドル (`wil::unique_handle`, `wil::unique_hfile` 等) による RAII
- **スレッドセーフティ**: `til::recursive_ticket_lock`, `til::ticket_lock` による明示的なロック管理、`_assertLocked()` / `_assertUnlocked()` によるデバッグ時検証
- **テスト**: TAEF (Test Authoring and Execution Framework) ベースの単体テスト、UIオートメーションテスト

## 備考

- 本プロジェクトは Windows Console Host と Windows Terminal の2つのプロダクトを単一リポジトリで管理するモノレポ構成である。
- `WindowsInbox` ブランディングトークンにより、Windows同梱版（conhost）とストア配布版（Windows Terminal）で有効化される機能を分離している。
- TIL (Terminal Implementation Library) は、`src/inc/til/` 配下のヘッダオンリーライブラリとして、プロジェクト全体で使用される基盤ユーティリティを提供する。
- ビルドシステムは MSBuild (.vcxproj) を使用し、vcpkg による外部依存管理、`common.build.pre.props` / `common.build.post.props` による共通ビルド設定を行う。
- 対象プラットフォームは x64, x86, ARM64 であり、Windows 10 2004 (build 19041) 以降をサポートする。
