# インフラ設計書

## 概要

本ドキュメントは、Tailwind CSS（v4.2.1）プロジェクトのインフラストラクチャ設計を記載する。本プロジェクトはオープンソースのCSS ユーティリティフレームワークであり、TypeScript + Rust のハイブリッドモノレポ構成を採用している。デプロイ対象はサーバーアプリケーションではなくnpmパッケージであり、インフラストラクチャはCI/CD パイプライン、クロスプラットフォームビルド、パッケージ配布を中心に構成される。

## システム構成

### 全体構成

本プロジェクトは以下のレイヤーで構成される：

1. **ソースコード管理**: GitHub（`tailwindlabs/tailwindcss`）
2. **CI/CD**: GitHub Actions（5つのワークフロー）
3. **ビルドシステム**: pnpm ワークスペース + Turborepo + Cargo（Rust）
4. **パッケージ配布**: npm レジストリ（npmjs.org）+ GitHub Releases
5. **通知**: Discord Webhook

プロジェクト自体はライブラリであるため、常時稼働するサーバーインフラは存在しない。インフラは開発・ビルド・配布パイプラインを中心に設計されている。

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner (Linux) | CI テスト・ビルド実行 | namespace-profile-default | マトリクス実行（動的） |
| GitHub Actions Runner (macOS) | CI テスト・リリースビルド | macos-14（M1） | マトリクス実行（動的） |
| GitHub Actions Runner (Windows) | CI テスト・クロスプラットフォーム検証 | windows-latest | マトリクス実行（動的） |
| GitHub Actions Runner (FreeBSD) | FreeBSD 向けネイティブバイナリビルド | FreeBSD 14.0（VM: 13GB RAM, 3 CPU） | 1 |
| コンテナランナー (Linux各種) | クロスコンパイルビルド | napi-rs Docker イメージ | ターゲット数に応じた動的起動 |

### ネットワーク構成

本プロジェクトのネットワーク構成は以下の通り：

- **インバウンド**: GitHub Webhook によるイベント駆動（push / pull_request / release / tag push）
- **アウトバウンド**:
  - npm レジストリ（`registry.npmjs.org`）へのパッケージ公開
  - GitHub Container Registry（`ghcr.io`）からのコンテナイメージ取得
  - Rust ツールチェイン（`static.rust-lang.org`）のダウンロード
  - Discord Webhook による通知送信
  - Tailwind Play 更新トリガー（GitHub API 経由）
- **並行実行制御**: `concurrency` グループによるワークフロー重複実行の防止

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Node.js | 24 | JavaScript ランタイム・ビルド実行 |
| pnpm | 9.6.0 | パッケージマネージャー（ワークスペース管理） |
| Turborepo | ^2.7.6 | モノレポビルドオーケストレーション |
| Rust (stable) | stable | Oxide エンジンのコンパイル |
| NAPI-RS | napi 3.3.0 / napi-derive 3.2.5 | Rust → Node.js ネイティブバインディング |
| tsup | ^8.5.1 | TypeScript バンドラー |
| Vitest | ^4.0.18 | テストランナー |
| Playwright | ^1.58.0 | UI テスト（ブラウザ自動化） |
| LightningCSS | 1.31.1 | CSS パーサー/トランスフォーマー |
| Bun | ^1.3.9 | スタンドアロンCLI ビルド |
| Prettier | 3.8.1 | コードフォーマッター |
| Cargo (Rust ビルドシステム) | stable | Rust クレートのビルド・テスト |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理、CI/CD、リリース管理 | Git / GitHub API / GitHub Actions |
| npm レジストリ (npmjs.org) | パッケージ配布 | npm publish（`NODE_AUTH_TOKEN`） |
| GitHub Container Registry (ghcr.io) | ビルド用 Docker イメージの取得 | Docker pull（napi-rs イメージ） |
| Discord | CI 失敗通知 | Webhook URL（`DISCORD_WEBHOOK_URL`） |
| Tailwind Play (tailwindlabs/upgrades) | リリース時の自動アップグレード | GitHub API（`TAILWIND_PLAY_TOKEN`） |
| crates.io | Rust 依存クレートの取得 | Cargo |
| static.rust-lang.org | Rust ツールチェインの取得 | HTTPS（rustup） |

## スケーリング設計

本プロジェクトはライブラリ配布型であり、ランタイムのスケーリングは不要。ビルド・テストのスケーリングは以下の方式で実現している：

### CI/CD パラレル実行

- **マトリクスビルド戦略**: OS（Windows / Linux / macOS）× ターゲットアーキテクチャ（最大14ターゲット）の組み合わせで並列実行
- **条件付き実行**: feature ブランチでは Linux のみ実行し、`main` ブランチまたは `[ci-all]` タグ付き PR で全 OS を実行
- **並行実行制御**: `concurrency` グループにより同一ブランチの重複ワークフローをキャンセル
- **タイムアウト**: 各ジョブに 15〜30 分のタイムアウトを設定

### ビルドターゲット（クロスコンパイル）

| ターゲット | OS | アーキテクチャ |
| --- | --- | --- |
| x86_64-pc-windows-msvc | Windows | x86_64 |
| aarch64-pc-windows-msvc | Windows | ARM64 |
| x86_64-apple-darwin | macOS | x86_64 |
| aarch64-apple-darwin | macOS | ARM64 (Apple Silicon) |
| x86_64-unknown-linux-gnu | Linux | x86_64 (glibc) |
| x86_64-unknown-linux-musl | Linux | x86_64 (musl) |
| aarch64-unknown-linux-gnu | Linux | ARM64 (glibc) |
| aarch64-unknown-linux-musl | Linux | ARM64 (musl) |
| armv7-unknown-linux-gnueabihf | Linux | ARMv7 (glibc) |
| aarch64-linux-android | Android | ARM64 |
| armv7-linux-androideabi | Android | ARMv7 |
| x86_64-unknown-freebsd | FreeBSD | x86_64 |
| wasm32-wasip1-threads | WASM | WASI |

## 可用性設計

本プロジェクトはライブラリであるため、ランタイムの可用性設計は適用外。以下はCI/CD パイプラインにおける信頼性担保の設計：

- **マルチプラットフォームテスト**: 3 OS（Windows / Linux / macOS）での並列テスト実行
- **フェイルファスト無効化**: `fail-fast: false` によりマトリクス内の 1 ジョブが失敗しても他ジョブは継続実行
- **キャッシュ戦略**: Cargo 依存・Oxide ビルド成果物・pnpm パッケージのキャッシュにより、ビルド時間を短縮しワークフローの安定性を向上
- **失敗通知**: `main` ブランチの CI 失敗時に Discord で即時通知
- **リリースチャネル分離**: `latest`（安定版）と `insiders`（開発版）のリリースチャネルを分離

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | GitHub リポジトリ（分散型 Git） | コミットごと | 無期限 |
| ビルドアーティファクト | GitHub Actions Artifacts | リリースごと | GitHub デフォルト保持期間 |
| リリースバイナリ | GitHub Releases | リリースごと | 無期限 |
| npm パッケージ | npm レジストリ | パブリッシュごと | 無期限（npm ポリシーに準拠） |
| パッケージ tarball | GitHub Actions Artifacts（`npm-package-tarballs`） | リリースごと | GitHub デフォルト保持期間 |

## 監視設計

本プロジェクトの監視は以下の方式で実施：

### CI/CD 監視

- **GitHub Actions ダッシュボード**: ワークフロー実行状況のリアルタイム監視
- **Discord 通知**: `main` ブランチの CI / Integration Tests 失敗時に自動通知（`discord-actions/message@v2`）
- **PR ステータスチェック**: Pull Request に対する CI 結果の自動報告

### パッケージ監視

- **npm provenance**: パッケージ公開時の来歴証明（`publishConfig.provenance: true`）
- **リリースチャネル管理**: `latest` / `insiders` タグによるバージョン管理

### ビルドパフォーマンス監視

- **タイムアウト設定**: 各ジョブに 15〜30 分のタイムアウトを設定し、無限ハングを防止
- **キャッシュヒット率**: GitHub Actions Cache のヒット率による間接的なビルドパフォーマンス把握

## 備考

### モノレポ構成

本プロジェクトは pnpm ワークスペースによるモノレポ構成を採用しており、以下のパッケージを含む：

| パッケージ | パス | 説明 |
| --- | --- | --- |
| tailwindcss | `packages/tailwindcss` | コアライブラリ（v4.2.1） |
| @tailwindcss/cli | `packages/@tailwindcss-cli` | CLI ツール |
| @tailwindcss/postcss | `packages/@tailwindcss-postcss` | PostCSS プラグイン |
| @tailwindcss/vite | `packages/@tailwindcss-vite` | Vite プラグイン |
| @tailwindcss/webpack | `packages/@tailwindcss-webpack` | Webpack プラグイン |
| @tailwindcss/node | `packages/@tailwindcss-node` | Node.js ユーティリティ |
| @tailwindcss/browser | `packages/@tailwindcss-browser` | ブラウザ用ビルド |
| @tailwindcss/standalone | `packages/@tailwindcss-standalone` | スタンドアロン CLI |
| @tailwindcss/upgrade | `packages/@tailwindcss-upgrade` | アップグレードツール |
| @tailwindcss/oxide | `crates/node` | Rust ネイティブバインディング |

### Rust（Oxide）ネイティブバインディング

Tailwind CSS v4 では、パフォーマンスクリティカルな処理（CSSパーシングやクラス名スキャン等）を Rust で実装し、NAPI-RS を通じて Node.js から呼び出す構成を採用している。これにより、14のプラットフォーム向けにプリビルドバイナリを配布し、各環境での最適なパフォーマンスを実現している。

### コンテナイメージ（ビルド用）

リリースビルドで使用する Docker イメージ（GitHub Container Registry 経由）：

| イメージ | 用途 |
| --- | --- |
| `ghcr.io/napi-rs/napi-rs/nodejs-rust:lts-debian` | Linux x86_64 (glibc) ビルド |
| `ghcr.io/napi-rs/napi-rs/nodejs-rust:lts-debian-aarch64` | Linux ARM64 (glibc) ビルド |
| `ghcr.io/napi-rs/napi-rs/nodejs-rust:lts-debian-zig` | Linux ARMv7 (glibc) ビルド |
| `ghcr.io/napi-rs/napi-rs/nodejs-rust:lts-alpine` | Linux x86_64/ARM64 (musl) ビルド |

### シークレット管理

| シークレット名 | 用途 |
| --- | --- |
| `NPM_TOKEN` | npm レジストリへのパッケージ公開認証 |
| `DISCORD_WEBHOOK_URL` | Discord 通知用 Webhook URL |
| `TAILWIND_PLAY_TOKEN` | Tailwind Play リポジトリへのワークフローディスパッチ権限 |
