# アーキテクチャ設計書

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータのアーキテクチャ設計を記載する。Ghosttyは高速でネイティブかつ機能豊富なターミナルエミュレータであり、Zig言語で実装されたコアライブラリ（libghostty）を基盤として、macOS（Swift/SwiftUI）およびLinux（GTK）向けのネイティブアプリケーションを提供する。

## システム全体構成

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

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

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| PTY（Pseudo Terminal） | POSIX/Windows API | シェル・サブプロセスとのI/O |
| Sentry | HTTP（オプション） | クラッシュレポート送信 |
| フォントシステム | CoreText (macOS) / Fontconfig (Linux) / FreeType | フォント検出・レンダリング |
| GPU | Metal (macOS) / OpenGL (Linux) / WebGL (WASM) | ハードウェアアクセラレーションレンダリング |
| ウィンドウシステム | AppKit/SwiftUI (macOS) / GTK4 (Linux) / Wayland/X11 | ウィンドウ管理・入力処理 |
| シェル統合 | 環境変数・シェルスクリプト | シェル統合機能 |

## レイヤー構成

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

**モジュラーアーキテクチャ + プラットフォーム抽象化レイヤー**

Ghosttyは以下の設計原則に基づいている：
- クロスプラットフォーム対応のコア（Zig実装）と、プラットフォーム固有のUI層の分離
- コンパイル時にプラットフォーム・レンダラー・フォントバックエンドを選択
- libghosttyとしてC互換ライブラリを提供し、外部プロジェクトへの組み込みを可能にする

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Application Runtime (apprt) | プラットフォーム固有のアプリケーションライフサイクル管理、ウィンドウ作成、ユーザー入力 | `apprt.zig`, `gtk/`, `embedded.zig`, `browser.zig` |
| Surface | ターミナルサーフェス（描画領域）の管理、入力処理、レンダリング制御 | `Surface.zig`, `App.zig` |
| Renderer | ターミナル状態からグラフィカル出力への変換 | `renderer/Metal.zig`, `renderer/OpenGL.zig`, `renderer/generic.zig` |
| Terminal IO (termio) | PTYとのI/O、ストリームパース、サブプロセス管理 | `termio/Termio.zig`, `termio/Exec.zig`, `pty.zig` |
| Terminal | ターミナルエミュレーション状態管理、エスケープシーケンス処理 | `terminal/Terminal.zig`, `terminal/Parser.zig`, `terminal/Screen.zig` |
| Font | フォント検出、グリフレンダリング、シェイピング | `font/`, `font/face.zig`, `font/shaper/` |
| Config | 設定ファイルの解析・管理 | `config/Config.zig` |
| Input | キーバインディング、入力エンコーディング | `input/Binding.zig`, `input/key.zig` |
| OS Abstraction | OS固有機能の抽象化 | `os/` |

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

```
Application Runtime (apprt)
         |
         v
   App / Surface  <------- Config
         |
    +----+----+
    |         |
    v         v
 Renderer   Termio
    |         |
    v         v
  Font    Terminal
    |         |
    v         v
   OS     PTY / OS
```

- 上位レイヤーは下位レイヤーに依存可能
- `global.zig`のグローバル状態はC API用。Zig APIはグローバル状態を使用せず、アロケータをパラメータとして渡す
- `build_config.zig`によるコンパイル時フィーチャーフラグで、ランタイム・レンダラー・フォントバックエンドを選択

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| ターミナルエミュレーション | VT100/xterm互換のエスケープシーケンス処理、画面状態管理 | `terminal/`, `termio/` |
| レンダリング | グリッド・グリフ・カーソル・画像の描画 | `renderer/`, `font/` |
| 入力処理 | キーボード/マウスイベント処理、キーバインディング | `input/`, `apprt/` |
| 設定管理 | 設定ファイルの解析、ホットリロード | `config/` |
| プラットフォーム統合 | OS固有API、ウィンドウシステム | `apprt/gtk/`, `macos/`, `os/` |
| クラッシュ管理 | クラッシュレポートの生成・保存 | `crash/` |

### パッケージ構造

```
src/
├── App.zig                    # アプリケーション管理
├── Surface.zig                # ターミナルサーフェス
├── Command.zig                # コマンド実行
├── apprt/                     # アプリケーションランタイム
│   ├── action.zig             # アクション定義
│   ├── embedded.zig           # 組み込みモード（libghostty）
│   ├── gtk/                   # GTK4実装
│   │   ├── App.zig
│   │   ├── Surface.zig
│   │   ├── class/
│   │   └── ui/
│   └── ipc.zig                # プロセス間通信
├── benchmark/                 # ベンチマークツール
├── build/                     # ビルドシステム
├── cli/                       # CLIインターフェース
├── config/                    # 設定管理
│   ├── Config.zig             # 設定定義（405K+ LOC）
│   ├── theme.zig              # テーマ管理
│   └── url.zig                # URL処理
├── crash/                     # クラッシュレポート
├── datastruct/                # データ構造
├── font/                      # フォント処理
│   ├── Atlas.zig              # グリフアトラス
│   ├── Collection.zig         # フォントコレクション
│   ├── SharedGrid.zig         # 共有グリッドキャッシュ
│   ├── discovery.zig          # フォント検出
│   ├── face.zig               # フォントフェース
│   └── shaper/                # テキストシェイピング
├── input/                     # 入力処理
│   ├── Binding.zig            # キーバインディング
│   ├── key.zig                # キー定義
│   ├── key_encode.zig         # キーエンコード
│   └── mouse.zig              # マウス処理
├── inspector/                 # ターミナルインスペクター
├── lib/                       # ライブラリインターフェース
├── os/                        # OS抽象化
├── renderer/                  # レンダリング
│   ├── Metal.zig              # Metalレンダラー
│   ├── OpenGL.zig             # OpenGLレンダラー
│   ├── generic.zig            # 汎用レンダラー
│   ├── Thread.zig             # レンダースレッド
│   ├── State.zig              # レンダー状態
│   └── shaders/               # シェーダー
├── simd/                      # SIMD最適化
├── terminal/                  # ターミナルエミュレーション
│   ├── Terminal.zig           # ターミナル状態機械
│   ├── Parser.zig             # エスケープシーケンスパーサー
│   ├── Screen.zig             # 画面バッファ
│   ├── PageList.zig           # ページリスト（スクロールバック）
│   ├── Selection.zig          # テキスト選択
│   ├── color.zig              # カラー処理
│   ├── kitty/                 # Kittyプロトコル
│   ├── osc.zig                # OSCシーケンス
│   └── stream.zig             # ストリーム処理
├── termio/                    # ターミナルI/O
│   ├── Termio.zig             # I/O管理
│   ├── Exec.zig               # サブプロセス実行
│   ├── Thread.zig             # I/Oスレッド
│   └── backend.zig            # バックエンド選択
├── terminfo/                  # terminfo処理
├── unicode/                   # Unicode処理
│   ├── grapheme.zig           # 書記素クラスタ
│   └── props.zig              # Unicode属性
├── global.zig                 # グローバル状態（C API用）
├── pty.zig                    # PTY管理
└── main.zig                   # エントリーポイント

macos/                         # macOS固有実装
├── Sources/
│   ├── App/                   # アプリケーション
│   ├── Features/              # 機能実装
│   ├── Ghostty/               # メインモジュール
│   └── Helpers/               # ヘルパー
└── Ghostty.xcodeproj/         # Xcodeプロジェクト

pkg/                           # 外部依存関係
├── freetype/                  # FreeType
├── harfbuzz/                  # HarfBuzz
├── fontconfig/                # Fontconfig
├── opengl/                    # OpenGL
├── sentry/                    # Sentry SDK
└── ...
```

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

主要コンポーネント間の依存関係:

- **App** → Surface, Config, apprt.App, font.SharedGridSet
- **Surface** → Renderer, Termio, Terminal, Config, Font, Input
- **Renderer** → Font, Terminal.Screen, renderer.State
- **Termio** → Terminal, PTY, Config
- **Terminal** → Parser, Screen, PageList, Selection
- **Font** → FreeType, HarfBuzz, CoreText/Fontconfig

## ミドルウェア構成

### データベース

該当なし（Ghosttyはデータベースを使用しない）

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| font.SharedGridSet | - | フォントグリッドキャッシュ（同一フォント設定のサーフェス間で共有） | アプリケーション終了まで |
| font.Atlas | - | グリフテクスチャアトラス | アプリケーション終了まで |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| BlockingQueue | 内部実装 | App/Surface間のメッセージング |
| Mailbox | 内部実装 | スレッド間通信（Renderer/Termio） |

### 検索エンジン

該当なし

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

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| libxev | - | 非同期イベントループ（epoll/kqueue/IOCP） |
| FreeType | pkg依存 | フォントレンダリング |
| HarfBuzz | pkg依存 | テキストシェイピング |
| Fontconfig | pkg依存 | フォント検出（Linux） |
| CoreText | OS付属 | フォント検出・レンダリング（macOS） |
| Metal | OS付属 | GPUレンダリング（macOS） |
| OpenGL | pkg/OS依存 | GPUレンダリング（Linux） |
| Oniguruma | pkg依存 | 正規表現（検索機能） |
| glslang | pkg依存 | シェーダーコンパイル |
| Sentry SDK | pkg依存 | クラッシュレポート |

## データフロー

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

**入力イベント処理（キー入力）:**

1. apprt（GTK/SwiftUI）がキーイベントを受信
2. Surface.keyEvent()が呼び出される
3. Input.Bindingでキーバインディングをチェック
   - バインディングがある場合: アクションを実行
   - バインディングがない場合: 続行
4. キーエンコード（input/key_encode.zig）でエスケープシーケンスに変換
5. Termio.queueMessage()でPTYに書き込み
6. PTYからシェルにデータ送信

**出力処理（ターミナル出力）:**

1. PTY読み取りスレッドがシェル出力を受信
2. Termio.handleRead()でデータを処理
3. terminal.Streamでエスケープシーケンスをパース
4. Terminal.process()で状態を更新（Screen, PageList）
5. Renderer.Threadに描画要求を送信
6. Rendererが新しいフレームを描画

### 非同期処理の流れ

**マルチスレッドアーキテクチャ:**

1. **メインスレッド（UIスレッド）**
   - apprtイベントループ実行
   - ユーザー入力処理
   - App.tick()でメールボックス処理

2. **IOスレッド（termio.Thread）**
   - PTY読み取り/書き込み
   - ターミナル状態更新
   - libxevイベントループ使用

3. **レンダースレッド（renderer.Thread）**
   - フレームレンダリング
   - GPU描画コマンド発行
   - VSync待機

4. **検索スレッド（オプション）**
   - テキスト検索実行
   - terminal.search.Thread

スレッド間通信:
- Mailbox（BlockingQueue）でメッセージパッシング
- xev.Asyncで相互ウェイクアップ
- 共有状態はMutexで保護

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

1. **設定ファイル**
   - `~/.config/ghostty/config`から読み込み
   - ホットリロード対応（config変更検知）

2. **クラッシュレポート**
   - `$XDG_STATE_HOME/ghostty/crash/`に保存
   - Sentry envelope形式

3. **ターミナル状態**
   - スクロールバックはメモリ内（PageList）
   - 永続化なし（セッション終了で消失）

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| macOS Sandbox | Ghostty.entitlements | ファイルアクセス、ネットワーク |
| PTYアクセス制御 | pty.zig | シェルプロセス |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | std.log（Zig標準ログ） | stderr / macOS unified log |
| デバッグログ | GHOSTTY_LOG環境変数で制御 | stderr |
| クラッシュレポート | Sentry SDK | `$XDG_STATE_HOME/ghostty/crash/` |

ログレベル:
- Debug: デバッグビルドのみstderr出力
- Info/Warn/Err: 常に出力

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

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 設定エラー | DiagnosticList | エラーメッセージ表示、デフォルト値使用 |
| PTYエラー | エラー返却 | ターミナルクローズ |
| レンダリングエラー | フォールバック | ソフトウェアレンダリング |
| メモリ不足 | Allocator.Error | 適切なクリーンアップ |
| クラッシュ | Sentry捕捉 | クラッシュレポート保存、次回起動時表示 |

Zigのエラーユニオン型を全面的に使用し、明示的なエラーハンドリングを強制。

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

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| ターミナル状態更新 | Mutex (renderer_state) | 単一更新 |
| 設定リロード | 全サーフェス更新 | アトミック |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| コンパイル時多相性 | build_config.zig | ランタイム/レンダラー/フォントバックエンドの選択 |
| 明示的なメモリ管理 | 全モジュール | Allocatorパラメータの明示的な受け渡し |
| エラー明示化 | 全モジュール | Zigのエラーユニオン型 |
| プラットフォーム抽象化 | apprt, renderer, font | インターフェースの統一とコンパイル時切り替え |
| スレッド分離 | IO/Renderer | 専用スレッドによる責務分離 |
| ゼロコピー最適化 | terminal, renderer | スライス参照、共有メモリ |

### コーディング規約

1. **言語**: Zig（コア）、Swift（macOS UI）、C（libghostty API）
2. **フォーマット**:
   - Zig: zigfmt
   - Swift: SwiftLint
   - その他: Prettier
3. **命名規則**:
   - Zig: camelCase（関数・変数）、PascalCase（型）
   - ファイル: snake_case.zig
4. **エラーハンドリング**: 全てのエラーは明示的に処理
5. **メモリ管理**: アロケータは引数として渡す、グローバル状態はC API専用
6. **テスト**: 各モジュールにテスト関数を含める

## 備考

### ビルドターゲット

| ターゲット | 説明 |
| --- | --- |
| exe (ghostty) | 実行可能ターミナル |
| lib (libghostty) | 組み込み用ライブラリ |
| lib-vt (libghostty-vt) | VTパーサー専用ライブラリ |
| wasm_module | WebAssemblyモジュール |

### 対応プラットフォーム

| プラットフォーム | ランタイム | レンダラー | 状態 |
| --- | --- | --- | --- |
| macOS | SwiftUI + libghostty | Metal | 安定 |
| Linux | GTK4 | OpenGL | 安定 |
| Windows | - | - | 開発中 |
| Web/WASM | Browser | WebGL | 実験的 |

### パフォーマンス最適化

- **SIMD**: `simd/`モジュールでベクトル化
- **メモリプール**: `terminal/bitmap_allocator.zig`
- **参照カウント**: `terminal/ref_counted_set.zig`
- **フォントキャッシュ**: `font/SharedGridSet.zig`
- **ゼロコピーI/O**: `termio/`での効率的なバッファ管理
