# アーキテクチャ設計書

## 概要

本ドキュメントは、Oh My Zsh（OMZ）のアーキテクチャ設計書です。Oh My Zshは、Zshシェルの設定管理を簡素化するためのオープンソースフレームワークであり、プラグイン・テーマシステムを核とした拡張可能なアーキテクチャを採用しています。本設計書では、システムの全体構成、モジュール構成、データフロー、および横断的関心事について説明します。

## システム全体構成

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

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

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Zsh Shell | シェルスクリプトの source 読み込み | OMZの起動・初期化、関数・エイリアス・補完の提供 |
| Git | CLIコマンド実行 | バージョン管理、自動更新、プラグイン管理 |
| GitHub API | HTTP REST API (curl/wget/fetch) | 更新確認、PRテスト機能 |
| ユーザーシェル設定 (.zshrc) | シェルスクリプトの source 読み込み | ユーザー設定の読み込み |

## レイヤー構成

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

**プラグインベースアーキテクチャ** + **モジュラーモノリス**

Oh My Zshは、中央のコアシステムが存在し、そこにプラグインやテーマを動的にロードする構造を採用しています。従来のWebアプリケーションで見られるレイヤードアーキテクチャとは異なり、シェル環境に特化した以下の構成を持ちます：

1. **Core Layer** - 初期化・設定管理・CLI機能を提供
2. **Library Layer** - 再利用可能なユーティリティ関数群
3. **Plugin Layer** - 拡張機能を提供する独立したモジュール群
4. **Theme Layer** - プロンプト外観をカスタマイズするテーマ群

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Core (oh-my-zsh.sh) | フレームワーク全体の初期化、プラグイン・テーマの読み込み、補完システム管理 | `oh-my-zsh.sh` |
| Tools | インストール、更新、ユーティリティスクリプト | `install.sh`, `upgrade.sh`, `check_for_upgrade.sh`, `uninstall.sh` |
| Library (lib/) | 共通機能、ユーティリティ関数、補完設定 | `cli.zsh`, `git.zsh`, `functions.zsh`, `completion.zsh`, `async_prompt.zsh` |
| Plugins (plugins/) | ツール固有の機能拡張（エイリアス、関数、補完） | 355個のプラグイン（git, docker, aws等） |
| Themes (themes/) | プロンプトの外観定義 | 143個のテーマ（robbyrussell, agnoster等） |
| Custom (custom/) | ユーザー定義のプラグイン・テーマ・設定 | ユーザー独自の拡張 |

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

```
[ユーザー .zshrc]
       |
       v
[Core: oh-my-zsh.sh]
       |
       +---> [Tools: check_for_upgrade.sh, upgrade.sh]
       |
       +---> [Library: lib/*.zsh]
       |            |
       |            v
       +---> [Plugins: plugins/*/*.plugin.zsh]
       |
       v
[Themes: themes/*.zsh-theme]
       |
       v
[Custom: custom/*.zsh, custom/plugins/*, custom/themes/*]
```

**依存の方向性:**
- Coreはすべてのレイヤーに対する参照が許可される
- Library関数はCore・他のLibrary関数から参照可能
- Plugins/Themesは Library関数を使用可能（git.zsh, functions.zsh等）
- CustomはすべてのLayerをオーバーライド・拡張可能

**禁止される参照:**
- Plugins間の直接的な依存関係（各プラグインは独立して動作すべき）
- Library→Pluginsへの直接参照
- Themes→Pluginsへの直接参照

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| 初期化 | Zsh環境のセットアップ、変数定義、fpath設定 | `oh-my-zsh.sh` |
| CLI管理 | omzコマンドによるOMZ操作 | `lib/cli.zsh` |
| Git統合 | Gitプロンプト情報、Git操作ヘルパー | `lib/git.zsh`, `lib/vcs_info.zsh`, `plugins/git/*` |
| 補完 | Zsh補完システムの設定・管理 | `lib/completion.zsh`, `lib/compfix.zsh` |
| 非同期処理 | プロンプトの非同期更新 | `lib/async_prompt.zsh` |
| テーマ | プロンプト外観管理 | `lib/theme-and-appearance.zsh`, `themes/` |
| 更新管理 | 自動更新確認・実行 | `tools/check_for_upgrade.sh`, `tools/upgrade.sh` |
| ユーティリティ | 汎用ヘルパー関数 | `lib/functions.zsh`, `lib/misc.zsh`, `lib/directories.zsh` |

### パッケージ構造

```
oh-my-zsh/
├── oh-my-zsh.sh              # エントリーポイント（Core）
├── lib/                      # ライブラリ層
│   ├── async_prompt.zsh      # 非同期プロンプト処理
│   ├── cli.zsh               # omz CLIコマンド
│   ├── clipboard.zsh         # クリップボード操作
│   ├── compfix.zsh           # 補完セキュリティ修正
│   ├── completion.zsh        # 補完設定
│   ├── correction.zsh        # コマンド修正
│   ├── diagnostics.zsh       # 診断機能
│   ├── directories.zsh       # ディレクトリ操作
│   ├── functions.zsh         # 汎用関数
│   ├── git.zsh               # Git統合
│   ├── grep.zsh              # grep設定
│   ├── history.zsh           # 履歴設定
│   ├── key-bindings.zsh      # キーバインド
│   ├── misc.zsh              # その他設定
│   ├── nvm.zsh               # nvm統合
│   ├── prompt_info_functions.zsh # プロンプト情報関数
│   ├── spectrum.zsh          # 256色サポート
│   ├── termsupport.zsh       # ターミナルサポート
│   ├── theme-and-appearance.zsh # テーマ基盤
│   ├── vcs_info.zsh          # VCS情報
│   └── tests/                # テスト
├── plugins/                  # プラグイン層（355個）
│   ├── git/                  # Gitプラグイン
│   │   ├── git.plugin.zsh    # メイン実装
│   │   └── README.md         # ドキュメント
│   ├── docker/               # Dockerプラグイン
│   ├── aws/                  # AWSプラグイン
│   └── ...                   # その他350+プラグイン
├── themes/                   # テーマ層（143個）
│   ├── robbyrussell.zsh-theme # デフォルトテーマ
│   ├── agnoster.zsh-theme    # 人気テーマ
│   └── ...                   # その他140+テーマ
├── tools/                    # ツール層
│   ├── install.sh            # インストーラー
│   ├── uninstall.sh          # アンインストーラー
│   ├── upgrade.sh            # アップグレード
│   ├── check_for_upgrade.sh  # 更新確認
│   ├── changelog.sh          # 変更履歴表示
│   ├── theme_chooser.sh      # テーマ選択
│   └── require_tool.sh       # ツール要件チェック
├── templates/                # テンプレート
│   └── zshrc.zsh-template    # .zshrcテンプレート
├── custom/                   # ユーザーカスタム
│   ├── example.zsh           # サンプル設定
│   ├── plugins/              # カスタムプラグイン
│   └── themes/               # カスタムテーマ
├── cache/                    # キャッシュディレクトリ
├── log/                      # ログディレクトリ
└── functions/                # Zsh関数（fpathに追加）
    └── completions/          # 補完関数
```

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

```
oh-my-zsh.sh
    |
    +-- tools/check_for_upgrade.sh (source)
    |
    +-- lib/compfix.zsh (source - 条件付き)
    |
    +-- lib/*.zsh (source - 順次読み込み)
    |       |
    |       +-- autoload関数: compaudit, compinit, zrecompile, is-at-least
    |       +-- zmodload: zsh/system, zsh/datetime, zsh/complist, zsh/langinfo
    |       |
    |       +-- lib/async_prompt.zsh
    |       |       +-- precmdフック登録
    |       |       +-- 非同期FD管理
    |       |
    |       +-- lib/cli.zsh
    |       |       +-- omz関数定義
    |       |       +-- サブコマンド: plugin, theme, update, pr
    |       |
    |       +-- lib/git.zsh
    |               +-- git_prompt_info, git_prompt_status
    |               +-- parse_git_dirty, git_current_branch
    |
    +-- plugins/$plugin/$plugin.plugin.zsh (source)
    |       |
    |       +-- エイリアス定義
    |       +-- 関数定義
    |       +-- 補完定義 (_$plugin)
    |
    +-- themes/$ZSH_THEME.zsh-theme (source)
    |       |
    |       +-- PROMPT変数設定
    |       +-- RPROMPT変数設定
    |       +-- プロンプト関数定義
    |
    +-- custom/*.zsh (source)
```

## ミドルウェア構成

### データベース

Oh My Zshはデータベースを使用しません。すべての状態はファイルシステムまたはシェル変数として管理されます。

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| ファイルストレージ | ローカルファイルシステム | - | 設定・キャッシュ・履歴の永続化 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| ファイルシステムキャッシュ | - | 補完ダンプファイル (.zcompdump) | 無期限（OMZリビジョン変更時に再生成） |
| ファイルシステムキャッシュ | - | 更新確認状態 (.zsh-update) | 13日（設定可能） |
| メモリキャッシュ | - | 非同期プロンプト出力 (_OMZ_ASYNC_OUTPUT) | セッション中 |

### メッセージキュー

該当なし（Oh My Zshはメッセージキューを使用しません）

### 検索エンジン

該当なし（Oh My Zshは検索エンジンを使用しません）

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

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Git | 1.7.2+ | OMZリポジトリ管理、自動更新、PRテスト |
| Zsh | 5.0.6+ (推奨) | シェル環境、非同期プロンプト |
| curl/wget/fetch | 任意 | GitHub APIへのアクセス（更新確認） |

## データフロー

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

**シェル起動時の初期化フロー:**

1. ユーザーの `.zshrc` が `oh-my-zsh.sh` を source する
2. `oh-my-zsh.sh` が ZSH, ZSH_CUSTOM, ZSH_CACHE_DIR 変数を初期化
3. `tools/check_for_upgrade.sh` を source して更新確認を実行
4. fpath にOMZディレクトリを追加（functions, completions）
5. `compaudit`, `compinit`, `zrecompile` を autoload
6. `$plugins` 配列に定義されたプラグインの存在確認
7. 各プラグインディレクトリを fpath に追加
8. 補完ダンプファイル (.zcompdump) のメタデータ検証
9. `compinit` を実行して補完システムを初期化
10. `_omz_source` 関数で lib/*.zsh を順次読み込み
11. `_omz_source` 関数で各プラグインを読み込み
12. custom/*.zsh を読み込み
13. `$ZSH_THEME` で指定されたテーマを読み込み
14. LS_COLORS に基づいて補完色を設定

### 非同期処理の流れ

**非同期プロンプト更新フロー（lib/async_prompt.zsh）:**

1. `_omz_register_handler` で非同期関数を登録
2. `precmd` フックで `_omz_async_request` が呼び出される
3. 既存の非同期プロセスがあればキャンセル（FDクローズ、プロセスkill）
4. 各ハンドラに対してサブシェルを fork
5. サブシェルが結果をFDに出力
6. `zle -F` でFDの読み取り可能イベントを監視
7. `_omz_async_callback` でFDから結果を読み取り
8. 結果が変更されていれば `zle .reset-prompt` でプロンプトを再描画

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

**キャッシュデータの永続化:**

| データ種別 | 保存先 | タイミング | 形式 |
| --- | --- | --- | --- |
| 補完ダンプ | $ZSH_COMPDUMP | compinit実行時 | Zsh compiled format (.zwc) |
| 更新状態 | $ZSH_CACHE_DIR/.zsh-update | 更新確認後 | Shell変数代入形式 |
| 補完キャッシュ | $ZSH_CACHE_DIR/completions/ | 補完生成時 | プラグイン依存 |

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| ファイルシステム権限 | oh-my-zsh.sh, lib/compfix.zsh | $ZSHディレクトリの書き込み・所有権確認 |
| 補完セキュリティ | lib/compfix.zsh | insecure directoriesの検出・警告 |
| sudo権限チェック | tools/install.sh | シェル変更時のsudo利用可否判定 |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | `_omz::log` 関数 | stderr |
| デバッグログ | `$_OMZ_DEBUG` 変数で制御 | stderr |
| 診断ログ | `lib/diagnostics.zsh` | stdout/stderr |
| 更新ログ | tools/upgrade.sh | stdout/ファイル |

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

**エラーハンドリングの方針:**
- 致命的エラー: `return 1` でスクリプト終了、ユーザーへのエラーメッセージ表示
- 警告: `_omz::log warn` で警告表示、処理は継続
- 回復可能エラー: ロールバック処理（.zshrc.bck からの復元等）

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 非Zsh実行 | oh-my-zsh.sh冒頭でチェック | エラーメッセージとプロセスツリー表示、return 1 |
| エミュレーションモード | oh-my-zsh.sh冒頭でチェック | エラーメッセージ表示、return 1 |
| プラグイン未検出 | is_plugin関数でチェック | 警告メッセージ "plugin 'X' not found" |
| テーマ未検出 | is_theme関数でチェック | 警告メッセージ "theme 'X' not found" |
| .zshrc構文エラー | `zsh -n` による事前検証 | ロールバック "Rolling back changes..." |
| Git操作失敗 | 各ツールスクリプト内でチェック | エラーメッセージ、処理中断 |

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

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| .zshrc更新 | バックアップ＋ロールバック | ファイルレベル（.zshrc.bck, .zshrc.pre-oh-my-zsh） |
| 更新処理 | ロックディレクトリ方式 | プロセスレベル（$ZSH/log/update.lock） |
| プラグイン有効化/無効化 | .zshrc書き換え＋検証＋ロールバック | ファイルレベル |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任原則 | プラグイン設計 | 各プラグインは1つのツール/機能のみを担当 |
| 開放閉鎖原則 | プラグイン/テーマシステム | 既存コードを変更せずに機能追加可能 |
| 依存性逆転 | _omz_source関数 | カスタムディレクトリのファイルが標準を上書き可能 |
| 設定より規約 | ディレクトリ構造 | plugins/$name/$name.plugin.zsh の命名規約 |
| フェイルセーフ | 更新処理 | .zshrc.bck によるロールバック機構 |
| プログレッシブエンハンスメント | 非同期プロンプト | Zshバージョンに応じた機能の段階的提供 |

### コーディング規約

**スクリプト規約:**
- シェバン: Zshスクリプトは `#!/usr/bin/env zsh`、POSIXシェルスクリプトは `#!/bin/sh`
- 関数命名: 内部関数は `_omz::` プレフィックス、または `_` プレフィックス
- エイリアス: アルファベット順にソート（READMEと同じ順序）
- インデント: スペース2つ

**プラグイン規約:**
- ファイル名: `$name.plugin.zsh` または `_$name`（補完のみ）
- README.md必須
- 独立動作: 他プラグインへの依存禁止

**テーマ規約:**
- ファイル名: `$name.zsh-theme`
- PROMPT/RPROMPT変数の設定
- ZSH_THEME_* 変数によるカスタマイズサポート

**Git統合規約:**
- GIT_OPTIONAL_LOCKS=0 を使用して他プロセスへの干渉を防止
- git config oh-my-zsh.* で OMZ固有設定を管理

## 備考

### バージョン互換性

- Zsh 5.0.6以上を推奨（非同期プロンプト機能のため）
- Zsh 5.0未満でも基本機能は動作
- Git 1.7.2以上が必要（--jobs オプション等は 2.8以上）
- Git 2.30以上で追加の安全機能（--force-if-includes）が有効化

### パフォーマンス考慮事項

- プラグインの過剰な追加はシェル起動時間に影響
- 非同期プロンプトは大規模Gitリポジトリでのパフォーマンス向上に寄与
- 補完ダンプのコンパイル（.zwc）により補完読み込み高速化
- DISABLE_UNTRACKED_FILES_DIRTY=true で大規模リポジトリのステータス確認高速化

### 拡張ポイント

1. **プラグイン追加**: `plugins/` または `custom/plugins/` にディレクトリ作成
2. **テーマ追加**: `themes/` または `custom/themes/` にファイル作成
3. **関数追加**: `functions/` または `custom/functions/` に配置
4. **設定オーバーライド**: `custom/*.zsh` に設定を記述
5. **既存ライブラリの上書き**: `custom/lib/` に同名ファイルを配置
