# UltraCloud 単体運用と統合アーキテクチャのバランス設計

## 概要

本設計書は、UltraCloudシステムにおいて「各コンポーネントが単体で完全に動作すること」を基本原則としつつ、必要に応じて統合機能を追加できるアーキテクチャを定義します。

**設計の核心:**
- 単体運用時は外部依存なしで完全に動作
- 統合時は段階的に機能を追加可能
- 設定のみでモード切り替えが可能
- データフローの明確な分離

---

## 1. コンポーネントの分類と依存関係

### 1.1 コンポーネント分類マトリクス

| カテゴリ | コンポーネント | 単体運用 | 最小依存 | 統合時の依存 |
|---------|--------------|---------|---------|-------------|
| **独立系** | lightningstor | ◎ 完全独立 | なし | chainfire（オプション） |
| | flashdns | ◎ 完全独立 | なし | chainfire（オプション） |
| | fiberlb | ◎ 完全独立 | なし | flashdns, chainfire（オプション） |
| | nightlight | ◎ 完全独立 | なし | chainfire（オプション） |
| **準独立系** | chainfire | ○ 準独立 | なし（自己完結） | クラスター形成時に他chainfireノード |
| | flaredb | ○ 準独立 | chainfire | chainfire |
| | creditservice | ○ 準独立 | chainfire（推奨） | chainfire, photonauth |
| **統合系** | photonnet | △ 統合設計 | chainfire | chainfire, 各ネットワークコンポーネント |
| | photonauth | △ 統合設計 | chainfire | chainfire, iam, mtls-agent |
| **コントロールプレーン** | API Gateway | × 統合専用 | photonauth, chainfire | 全サービス |
| | Resource Manager | × 統合専用 | chainfire, EventBus | 全エージェント |
| | Scheduler | × 統合専用 | chainfire | Resource Manager |

### 1.2 依存関係詳細図

```mermaid
graph TB
    subgraph 独立系_Standalone[独立系: 単体完全動作]
        LS[lightningstor]
        FD[flashdns]
        FL[fiberlb]
        NL[nightlight]
    end

    subgraph 準独立系_Quasi[準独立系: 最小依存]
        CF[chainfire]
        FDB[flaredb]
        CS[creditservice]
    end

    subgraph 統合系_Integration[統合系: 統合前提]
        PN[photonnet]
        PA[photonauth]
    end

    subgraph コントロールプレーン_CP[コントロールプレーン]
        AG[API Gateway]
        RM[Resource Manager]
        SCH[Scheduler]
    end

    FDB -.->|メタデータ保存| CF
    CS -.->|状態保存| CF

    PN -.->|状態保存| CF
    PA -.->|状態保存| CF

    AG -->|認証| PA
    AG -->|リソース管理| RM
    RM -->|スケジューリング| SCH
    RM -.->|状態保存| CF
    SCH -.->|状態保存| CF

    style LS fill:#90EE90
    style FD fill:#90EE90
    style FL fill:#90EE90
    style NL fill:#90EE90
    style CF fill:#FFD700
    style FDB fill:#FFD700
    style CS fill:#FFD700
    style PN fill:#FFA500
    style PA fill:#FFA500
```

### 1.3 各コンポーネントの依存詳細

#### lightningstor（オブジェクトストレージ）

**単体運用時:**
- ストレージ: ローカルファイルシステム
- メタデータ: ローカルRocksDB
- 認証: ローカルアクセスキー
- 設定: ローカル設定ファイルのみ

**統合運用時（オプション）:**
- メタデータ: chainfire分散KV
- 認証: photonauth統合
- マルチテナント: Resource Manager経由

#### flashdns（DNSサーバー）

**単体運用時:**
- ゾーン管理: ファイルベース（BIND形式互換）
- API: DNSプロトコルのみ（TCP/UDP 53）
- 設定: ゾーンファイル

**統合運用時（オプション）:**
- ゾーン管理: chainfireバックエンド
- API: gRPC管理API + DNS
- 統合: photonnet VPC内DNS連携

#### fiberlb（ロードバランサー）

**単体運用時:**
- 設定: ローカル設定ファイルまたはREST API
- データプレーン: 直接動作（iptables/IPVS/ebpf）
- ヘルスチェック: 組み込み

**統合運用時（オプション）:**
- 設定: Resource Manager経由
- サービスディスカバリ: flashdns連携
- 証明書管理: photonauth統合

#### chainfire（分散KV）

**単体運用時:**
- 動作: 単一ノードRaft（自己完結）
- 用途: ローカルアプリケーションの状態保存

**統合運用時:**
- 動作: マルチノードRaftクラスター
- 用途: UltraCloud全体の状態保存基盤

---

## 2. 各コンポーネントの単体運用モード設計

### 2.1 lightningstor単体運用モード

**提供機能:**
- S3互換API（PUT/GET/DELETE/LIST等）
- バケット管理
- アクセスキー認証（シンプル）
- ローカルファイルシステムストレージ

**設定例（TOML）:**
```toml
[photon]
mode = "standalone"
component_id = "lightningstor-01"

[photon.standalone]
# ストレージバックエンド
storage_backend = "filesystem"
metadata_backend = "rocksdb"
auth_backend = "local"

[standalone.server]
grpc_addr = "0.0.0.0:9000"
s3_addr = "0.0.0.0:9001"
log_level = "info"

[standalone.storage]
data_dir = "/var/lib/lightningstor/data"

[standalone.metadata]
path = "/var/lib/lightningstor/meta"
cache_size_mb = 256

[standalone.auth]
# シンプルなアクセスキー認証
type = "access_key"
access_key = "AKIAIOSFODNN7EXAMPLE"
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
# またはファイルから読み込み
# credentials_file = "/etc/lightningstor/credentials"

[standalone.features]
# 単体時は基本機能のみ
versioning = false
lifecycle = false
replication = false
```

**起動コマンド:**
```bash
lightningstor-server --config /etc/lightningstor/standalone.toml
# または環境変数でモード指定
PHOTON_MODE=standalone lightningstor-server
```

**API提供状況:**
| API | 単体運用時 | 備考 |
|-----|-----------|------|
| S3 PutObject | ◎ | 完全サポート |
| S3 GetObject | ◎ | 完全サポート |
| S3 ListBuckets | ◎ | 完全サポート |
| S3 ListObjectsV2 | ◎ | 完全サポート |
| S3 DeleteObject | ◎ | 完全サポート |
| S3 MultiPartUpload | ◎ | 完全サポート |
| gRPC Admin API | ◎ | 基本機能のみ |
| IAM連携認証 | × | 単体時はローカル認証 |
| マルチテナント | × | 単体時はシングルテナント |

### 2.2 flashdns単体運用モード

**提供機能:**
- 権威DNSサーバー機能
- ゾーンファイル管理
- DNSSEC（オプション）
- キャッシュ機能

**設定例（TOML）:**
```toml
[photon]
mode = "standalone"
component_id = "flashdns-01"

[photon.standalone]
zone_backend = "file"

[standalone.server]
dns_addr = "0.0.0.0:53"
dns_tcp_addr = "0.0.0.0:53"
admin_api_addr = "127.0.0.1:8053"

[standalone.zones]
zone_dir = "/etc/flashdns/zones"
auto_reload = true
reload_interval_sec = 300

[[standalone.zones.zone]]
name = "example.com"
file = "/etc/flashdns/zones/example.com.zone"
ttl = 3600

[[standalone.zones.zone]]
name = "internal.local"
file = "/etc/flashdns/zones/internal.local.zone"
type = "master"

[standalone.features]
dnssec = false
dynamic_update = false
axfr_allow = ["127.0.0.1"]
```

**ゾーンファイル例:**
```
$ORIGIN example.com.
$TTL 3600

@       IN      SOA     ns1.example.com. admin.example.com. (
                        2024010101      ; Serial
                        3600            ; Refresh
                        1800            ; Retry
                        604800          ; Expire
                        86400 )         ; Minimum TTL

@       IN      NS      ns1.example.com.
@       IN      NS      ns2.example.com.

ns1     IN      A       192.168.1.1
ns2     IN      A       192.168.1.2

@       IN      A       192.168.1.10
www     IN      A       192.168.1.10
api     IN      A       192.168.1.11
```

**API提供状況:**
| 機能 | 単体運用時 | 備考 |
|-----|-----------|------|
| DNSクエリ（UDP） | ◎ | 完全サポート |
| DNSクエリ（TCP） | ◎ | 完全サポート |
| ゾーンファイル管理 | ◎ | ファイルベース |
| AXFR | ◎ | 設定可能 |
| 動的更新 | × | 単体時は非サポート |
| REST API | △ | 読み取りのみ |
| gRPC管理API | × | 単体時は非サポート |
| VPC連携 | × | 統合時のみ |

### 2.3 fiberlb単体運用モード

**提供機能:**
- L4ロードバランシング（TCP/UDP）
- L7ロードバランシング（HTTP/HTTPS）
- ヘルスチェック
- セッション維持

**設定例（TOML）:**
```toml
[photon]
mode = "standalone"
component_id = "fiberlb-01"

[photon.standalone]
config_backend = "file"
dataplane = "iptables"

[standalone.server]
grpc_addr = "0.0.0.0:50052"
admin_api_addr = "0.0.0.0:8080"
metrics_addr = "0.0.0.0:9090"

[standalone.dataplane]
type = "iptables"
# または "ipvs", "ebpf", "userspace"

# ロードバランサー定義
[[standalone.loadbalancers]]
name = "web-lb"
vip = "10.0.0.100"
port = 80
protocol = "tcp"
method = "roundrobin"

[[standalone.loadbalancers.backends]]
name = "web-1"
address = "10.0.0.11"
port = 8080
weight = 100

[[standalone.loadbalancers.backends]]
name = "web-2"
address = "10.0.0.12"
port = 8080
weight = 100

[standalone.loadbalancers.healthcheck]
type = "http"
interval_sec = 10
timeout_sec = 5
path = "/health"

[[standalone.loadbalancers]]
name = "api-lb"
vip = "10.0.0.101"
port = 443
protocol = "tcp"
method = "leastconn"
tls_termination = true

[standalone.loadbalancers.tls]
cert_file = "/etc/fiberlb/certs/api.crt"
key_file = "/etc/fiberlb/certs/api.key"
```

**API提供状況:**
| 機能 | 単体運用時 | 備考 |
|-----|-----------|------|
| L4ロードバランシング | ◎ | 完全サポート |
| L7ロードバランシング | ◎ | 完全サポート |
| ヘルスチェック | ◎ | HTTP/TCPカスタム |
| セッション維持 | ◎ | Cookie/IPベース |
| REST API管理 | ◎ | 完全サポート |
| TLS終端 | ◎ | 証明書ファイル指定 |
| gRPC管理API | ◎ | 基本機能 |
| サービスディスカバリ | × | 統合時のみ |
| 自動スケーリング | × | 統合時のみ |

### 2.4 nightlight単体運用モード

**提供機能:**
- メトリクス収集（Prometheus形式）
- ローカル時系列データベース
- 基本ダッシュボード
- アラート（ローカル実行）

**設定例（TOML）:**
```toml
[photon]
mode = "standalone"
component_id = "nightlight-01"

[photon.standalone]
storage_backend = "local"

[standalone.server]
http_addr = "0.0.0.0:9090"
grpc_addr = "0.0.0.0:9091"

[standalone.storage]
type = "local"
data_dir = "/var/lib/nightlight"
retention_days = 30

[standalone.collection]
scrape_interval_sec = 15
scrape_timeout_sec = 10

[[standalone.scrape_targets]]
name = "local"
static_configs = ["localhost:9090"]

[standalone.alerting]
enabled = true
# 単体時はローカルアラートのみ
local_webhook = "http://localhost:5000/alerts"
```

---

## 3. 単体運用と統合モードの切り替え設計

### 3.1 モード検出メカニズム

各コンポーネントは以下の優先順位で運用モードを検出します：

```rust
enum OperationMode {
    Standalone,
    Integrated,
}

fn detect_mode() -> OperationMode {
    // 1. 環境変数（最優先）
    if let Ok(mode) = env::var("PHOTON_MODE") {
        return match mode.as_str() {
            "integrated" => OperationMode::Integrated,
            _ => OperationMode::Standalone,
        };
    }

    // 2. 設定ファイル
    if let Ok(config) = load_config() {
        return config.photon.mode;
    }

    // 3. 自動検出（統合コントロールプレーンへの接続試行）
    if can_connect_to_control_plane() {
        return OperationMode::Integrated;
    }

    // デフォルト: 単体運用
    OperationMode::Standalone
}
```

### 3.2 設定の違い

**単体運用時の設定構造:**
```toml
[photon]
mode = "standalone"
component_id = "unique-component-id"

[photon.standalone]
# 各コンポーネント固有の単体運用設定
storage_backend = "local"
auth_backend = "local"
config_source = "file"
```

**統合運用時の設定構造:**
```toml
[photon]
mode = "integrated"
component_id = "unique-component-id"
cluster_id = "cluster-identifier"

[photon.integrated]
# 統合基盤への接続設定
control_plane_endpoint = "http://photon-cp:8080"
chainfire_endpoints = ["http://chainfire:2379"]
auth_service_endpoint = "http://photonauth:50051"
event_bus_endpoint = "http://events:4222"

[photon.integrated.registration]
auto_register = true
heartbeat_interval_sec = 30
metadata = { region = "tokyo", zone = "az-1" }
```

### 3.3 段階的統合フロー

```mermaid
graph LR
    A[単体運用開始] --> B{chainfire追加?}
    B -->|Yes| C[chainfire統合]
    B -->|No| A
    C --> D{photonauth追加?}
    D -->|Yes| E[認証統合]
    D -->|No| C
    E --> F{photonnet追加?}
    F -->|Yes| G[ネットワーク統合]
    F -->|No| E
    G --> H{コントロールプレーン追加?}
    H -->|Yes| I[完全統合]
    H -->|No| G
```

### 3.4 統合コントロールプレーンへの接続方法

```rust
// 統合モード初期化フロー
async fn initialize_integrated_mode(config: &IntegratedConfig) -> Result<()> {
    // 1. 統合基盤への接続確認
    let cp_client = ControlPlaneClient::new(&config.control_plane_endpoint);
    cp_client.health_check().await?;

    // 2. chainfire接続
    let chainfire_client = ChainfireClient::new(&config.chainfire_endpoints).await?;

    // 3. 認証サービス接続（必要に応じて）
    let auth_client = if let Some(endpoint) = &config.auth_service_endpoint {
        Some(AuthClient::new(endpoint).await?)
    } else {
        None
    };

    // 4. イベントバス接続
    let event_bus = EventBusClient::new(&config.event_bus_endpoint).await?;

    // 5. コントロールプレーンへの登録
    let registration = ComponentRegistration {
        component_id: config.component_id.clone(),
        component_type: ComponentType::LightningStor,
        endpoint: get_local_endpoint(),
        capabilities: vec![Capability::S3Api, Capability::ObjectStorage],
        metadata: config.metadata.clone(),
    };
    cp_client.register(&registration).await?;

    // 6. ハートビート開始
    start_heartbeat(cp_client.clone(), config.heartbeat_interval_sec);

    Ok(ComponentContext {
        cp_client,
        chainfire_client,
        auth_client,
        event_bus,
    })
}
```

### 3.5 段階的機能有効化

| 機能 | 単体運用 | +chainfire | +photonauth | +コントロールプレーン |
|-----|---------|-----------|-------------|---------------------|
| ローカル認証 | ◎ | ◎ | → 統合認証 | → 統合認証 |
| ローカルメタデータ | ◎ | → 分散メタデータ | → 分散メタデータ | → 分散メタデータ |
| ローカル設定 | ◎ | ◎ | ◎ | → 集中管理 |
| ローカルモニタリング | ◎ | ◎ | ◎ | → 集中モニタリング |
| イベント発行 | × | △（chainfire経由） | △ | ◎（Event Bus） |
| マルチテナント | × | △ | ◎ | ◎ |
| リソーススケジューリング | × | × | × | ◎ |

---

## 4. 最小構成と推奨構成パターン

### 4.1 構成パターンマトリクス

| パターン | コンポーネント | 用途 | データフロー |
|---------|--------------|------|-------------|
| **レベル0** | 単一コンポーネント | 特定機能のみ必要 | 完全独立 |
| **レベル1** | ストレージ + DNS | 静的サイトホスティング | 独立（DNS手動設定） |
| **レベル2** | + LB | Webアプリケーション | 独立（LB→DNS連携あり） |
| **レベル3** | + photonnet + photonauth | マルチテナント | 統合開始 |
| **レベル4** | + コントロールプレーン | プライベートクラウド | 完全統合 |

### 4.2 レベル0: 最小構成（単一コンポーネント）

**用途:** 特定の機能のみが必要な場合

**構成例A: S3互換ストレージのみ**
```yaml
# docker-compose.yml
version: '3'
services:
  lightningstor:
    image: ultracloud/lightningstor:latest
    environment:
      PHOTON_MODE: standalone
    volumes:
      - ./lightningstor.toml:/etc/lightningstor/config.toml
      - lightningstor-data:/var/lib/lightningstor
    ports:
      - "9000:9000"  # S3 API
      - "9001:9001"  # gRPC
```

**構成例B: DNSサーバーのみ**
```yaml
services:
  flashdns:
    image: ultracloud/flashdns:latest
    environment:
      PHOTON_MODE: standalone
    volumes:
      - ./zones:/etc/flashdns/zones
    ports:
      - "53:53/udp"
      - "53:53/tcp"
```

**構成例C: ロードバランサーのみ**
```yaml
services:
  fiberlb:
    image: ultracloud/fiberlb:latest
    environment:
      PHOTON_MODE: standalone
    volumes:
      - ./fiberlb.toml:/etc/fiberlb/config.toml
    network_mode: host  # VIP割り当てに必要
```

### 4.3 レベル1: 基本構成（ストレージ + DNS）

**用途:** 静的サイトホスティング、カスタムドメインでのファイル配信

```yaml
services:
  lightningstor:
    image: ultracloud/lightningstor:latest
    environment:
      PHOTON_MODE: standalone
    volumes:
      - lightningstor-data:/var/lib/lightningstor
    ports:
      - "9000:9000"

  flashdns:
    image: ultracloud/flashdns:latest
    environment:
      PHOTON_MODE: standalone
    volumes:
      - ./zones:/etc/flashdns/zones
    ports:
      - "53:53/udp"
      - "53:53/tcp"
```

**連携方法:**
- DNSゾーンにlightningstorのIPをAレコードとして手動登録
- 例: `assets.example.com → 192.168.1.100`

### 4.4 レベル2: 標準構成（ストレージ + DNS + LB）

**用途:** Webアプリケーション基盤

```yaml
services:
  chainfire:
    image: ultracloud/chainfire:latest
    volumes:
      - chainfire-data:/var/lib/chainfire

  lightningstor:
    image: ultracloud/lightningstor:latest
    environment:
      PHOTON_MODE: standalone
      CHAINFIRE_ENDPOINT: http://chainfire:2379
    depends_on:
      - chainfire

  flashdns:
    image: ultracloud/flashdns:latest
    environment:
      PHOTON_MODE: standalone
      CHAINFIRE_ENDPOINT: http://chainfire:2379
    depends_on:
      - chainfire

  fiberlb:
    image: ultracloud/fiberlb:latest
    environment:
      PHOTON_MODE: standalone
    network_mode: host
```

**連携:**
- chainfireでサービスレジストリを共有
- fiberlbがバックエンド変更時にflashdnsに通知（オプション）

### 4.5 レベル3: 統合構成（+ photonnet + photonauth）

**用途:** マルチテナント環境、統一認証

```yaml
services:
  chainfire:
    image: ultracloud/chainfire:latest
    command: --cluster-mode

  photonauth:
    image: ultracloud/photonauth:latest
    environment:
      PHOTON_MODE: integrated
      CHAINFIRE_ENDPOINTS: http://chainfire:2379

  photonnet:
    image: ultracloud/photonnet:latest
    environment:
      PHOTON_MODE: integrated
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      AUTH_ENDPOINT: http://photonauth:50051

  lightningstor:
    image: ultracloud/lightningstor:latest
    environment:
      PHOTON_MODE: integrated
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      AUTH_ENDPOINT: http://photonauth:50051
```

### 4.6 レベル4: 完全構成（+ コントロールプレーン）

**用途:** プライベートクラウド、マルチテナントクラウド

```yaml
services:
  chainfire:
    image: ultracloud/chainfire:latest
    command: --cluster-mode --bootstrap-cluster

  eventbus:
    image: nats:latest

  photonauth:
    image: ultracloud/photonauth:latest
    environment:
      PHOTON_MODE: integrated
      CHAINFIRE_ENDPOINTS: http://chainfire:2379

  photonnet:
    image: ultracloud/photonnet:latest
    environment:
      PHOTON_MODE: integrated
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      AUTH_ENDPOINT: http://photonauth:50051

  resource-manager:
    image: ultracloud/resource-manager:latest
    environment:
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      EVENT_BUS: http://eventbus:4222

  scheduler:
    image: ultracloud/scheduler:latest
    environment:
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      RESOURCE_MANAGER: http://resource-manager:8080

  api-gateway:
    image: ultracloud/api-gateway:latest
    environment:
      CHAINFIRE_ENDPOINTS: http://chainfire:2379
      AUTH_ENDPOINT: http://photonauth:50051
      RESOURCE_MANAGER: http://resource-manager:8080
    ports:
      - "8080:8080"
```

---

## 5. 設定・構成の標準化

### 5.1 共通設定スキーマ

すべてのコンポーネントは以下の共通設定構造を持ちます：

```toml
[photon]
# 必須: 運用モード
mode = "standalone"  # or "integrated"

# 必須: コンポーネント識別子
component_id = "unique-id"

# オプション: クラスター識別子（統合時）
cluster_id = "cluster-1"

[photon.logging]
level = "info"
format = "json"

[photon.metrics]
enabled = true
endpoint = "0.0.0.0:9090"

[photon.standalone]
# 単体運用時の設定（mode = "standalone"時に有効）

[photon.integrated]
# 統合運用時の設定（mode = "integrated"時に有効）
control_plane_endpoint = "http://cp:8080"
chainfire_endpoints = ["http://cf:2379"]
heartbeat_interval_sec = 30
```

### 5.2 環境変数マッピング

| 環境変数 | 設定パス | 説明 |
|---------|---------|------|
| `PHOTON_MODE` | `photon.mode` | 運用モード |
| `PHOTON_COMPONENT_ID` | `photon.component_id` | コンポーネントID |
| `PHOTON_CLUSTER_ID` | `photon.cluster_id` | クラスターID |
| `PHOTON_LOG_LEVEL` | `photon.logging.level` | ログレベル |
| `PHOTON_CONTROL_PLANE_ENDPOINT` | `photon.integrated.control_plane_endpoint` | CPエンドポイント |
| `PHOTON_CHAINFIRE_ENDPOINTS` | `photon.integrated.chainfire_endpoints` | chainfireエンドポイント（カンマ区切り） |
| `PHOTON_AUTH_ENDPOINT` | `photon.integrated.auth_service_endpoint` | 認証サービスエンドポイント |

### 5.3 設定ロード優先順位

1. コマンドライン引数（最優先）
2. 環境変数
3. 設定ファイル
4. デフォルト値

```rust
pub fn load_config<T: DeserializeOwned>(component_name: &str) -> Result<T> {
    let config = Config::builder()
        // デフォルト
        .set_default("photon.mode", "standalone")?
        // 設定ファイル
        .add_source(File::with_name(&format!("/etc/photon/{}/config", component_name)).required(false))
        .add_source(File::with_name(&format!("{}-config", component_name)).required(false))
        // 環境変数
        .add_source(
            Environment::with_prefix("PHOTON")
                .separator("__")
                .try_parsing(true)
        )
        .build()?;

    config.try_deserialize().map_err(Into::into)
}
```

### 5.4 コンポーネントのモード検出実装例

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum OperationMode {
    Standalone,
    Integrated,
}

pub struct ModeDetector;

impl ModeDetector {
    pub fn detect() -> OperationMode {
        // 環境変数チェック
        if let Ok(mode) = std::env::var("PHOTON_MODE") {
            return match mode.to_lowercase().as_str() {
                "integrated" => OperationMode::Integrated,
                _ => OperationMode::Standalone,
            };
        }

        // 設定ファイルチェック
        if let Ok(config) = Self::load_mode_from_config() {
            return config;
        }

        // 自動検出: 統合基盤への接続を試行
        if Self::can_connect_to_control_plane() {
            log::info!("Control plane detected, switching to integrated mode");
            return OperationMode::Integrated;
        }

        OperationMode::Standalone
    }

    fn can_connect_to_control_plane() -> bool {
        // CP_HEALTH_ENDPOINTが設定されていれば接続試行
        if let Ok(endpoint) = std::env::var("PHOTON_CONTROL_PLANE_ENDPOINT") {
            let health_url = format!("{}/health", endpoint);
            return reqwest::blocking::get(&health_url)
                .map(|r| r.status().is_success())
                .unwrap_or(false);
        }
        false
    }
}
```

---

## 6. データフローの分離設計

### 6.1 単体運用時のデータフロー

```mermaid
graph TB
    Client[Client] -->|API Request| API[Component API]
    API -->|Authenticate| LocalAuth[Local Auth]
    API -->|Process| Logic[Business Logic]
    Logic -->|Read/Write| LocalStorage[Local Storage]
    Logic -->|Emit| LocalMetrics[Local Metrics]

    subgraph Component[Component Container]
        API
        LocalAuth
        Logic
        LocalStorage
        LocalMetrics
    end
```

**特徴:**
- すべての処理がコンポーネント内部で完結
- 外部サービスへの依存なし
- シンプルな設定で即座に動作

### 6.2 統合運用時のデータフロー

```mermaid
graph TB
    Client[Client] -->|API Request| APIGateway[API Gateway]
    APIGateway -->|Authenticate| PhotonAuth[photonauth]
    APIGateway -->|Resource Ops| ResourceManager[Resource Manager]

    ResourceManager -->|Read/Write| Chainfire[chainfire]
    ResourceManager -->|Publish| EventBus[Event Bus]

    EventBus -->|Notify| ComponentAgent[Component Agent]
    ComponentAgent -->|Execute| Component[Component]
    Component -->|Report State| Chainfire
    Component -->|Emit Metrics| Nightlight[nightlight]

    ResourceManager -->|Schedule| Scheduler[Scheduler]
    Scheduler -->|Select Node| ComponentAgent
```

**特徴:**
- コントロールプレーンが中心
- イベント駆動アーキテクチャ
- 状態はchainfireで集中管理
- スケジューラがリソース配置を最適化

### 6.3 切り替えの仕組み

**アダプターパターンによる実装:**

```rust
// ストレージバックエンド抽象化
trait MetadataBackend: Send + Sync {
    async fn get(&self, key: &str) -> Result<Option<Value>>;
    async fn put(&self, key: &str, value: Value) -> Result<()>;
    async fn delete(&self, key: &str) -> Result<()>;
}

// 単体運用時: ローカルRocksDB
struct LocalMetadataBackend {
    db: Arc<rocksdb::DB>,
}

#[async_trait]
impl MetadataBackend for LocalMetadataBackend {
    async fn get(&self, key: &str) -> Result<Option<Value>> {
        Ok(self.db.get(key)?.map(|v| serde_json::from_slice(&v)).transpose()?)
    }
    // ...
}

// 統合運用時: chainfire
struct ChainfireMetadataBackend {
    client: ChainfireClient,
}

#[async_trait]
impl MetadataBackend for ChainfireMetadataBackend {
    async fn get(&self, key: &str) -> Result<Option<Value>> {
        Ok(self.client.get(key).await?)
    }
    // ...
}

// ファクトリー
fn create_metadata_backend(mode: OperationMode, config: &Config) -> Box<dyn MetadataBackend> {
    match mode {
        OperationMode::Standalone => Box::new(LocalMetadataBackend::new(&config.local.db_path)),
        OperationMode::Integrated => Box::new(ChainfireMetadataBackend::new(&config.integrated.chainfire)),
    }
}
```

### 6.4 ハイブリッドモード

一部の機能のみ統合する「ハイブリッドモード」もサポート：

```toml
[photon]
mode = "hybrid"

[photon.hybrid]
# 認証のみ統合
auth_backend = "integrated"
auth_endpoint = "http://photonauth:50051"

# メタデータはローカル
metadata_backend = "local"

# イベント発行は統合
events_backend = "integrated"
event_bus_endpoint = "http://events:4222"
```

---

## 7. 実装上の注意点と落とし穴

### 7.1 よくある落とし穴

| 問題 | 原因 | 対策 |
|-----|------|------|
| **認証の不整合** | 単体運用時のローカル認証と統合時のIAM認証の互換性なし | アクセスキー形式を統一。移行ツールを提供 |
| **データ移行の失敗** | メタデータのスキーマ違い | マイグレーションスクリプトを用意。バックアップ必須 |
| **ネットワーク分離** | 統合時のサービス間通信設定ミス | ヘルスチェックエンドポイントを統一。接続テストツール提供 |
| **状態の二重管理** | 単体→統合移行時の状態同期漏れ | 移行ガイドに明確な手順を記載。検証スクリプト提供 |
| **パフォーマンス低下** | 統合時のネットワーク遅延 | キャッシュ戦略を実装。非同期処理を徹底 |

### 7.2 ベストプラクティス

**1. 段階的移行の推奨**
```
単体運用 → chainfire追加 → photonauth追加 → コントロールプレーン追加
```

**2. 設定バージョニング**
```toml
[photon]
config_version = "1.0"
mode = "integrated"
```

**3. ヘルスチェックの統一**
すべてのコンポーネントは `/health` エンドポイントを提供：
```json
{
  "status": "healthy",
  "mode": "standalone",
  "component": "lightningstor",
  "version": "0.1.0",
  "checks": {
    "storage": "ok",
    "metadata": "ok"
  }
}
```

**4. グレースフルデグラデーション**
統合コンポーネントへの接続失敗時は、自動的に単体モードにフォールバック（設定可能）：
```toml
[photon.integrated]
fallback_to_standalone = true
fallback_timeout_sec = 30
```

### 7.3 デバッグとトラブルシューティング

**モード検出の確認:**
```bash
# 環境変数の確認
curl http://localhost:8080/health | jq '.mode'

# ログでの確認
tail -f /var/log/lightningstor.log | grep "operation_mode"
```

**統合状態の確認:**
```bash
# 統合基盤への接続テスト
photonctl check-connection --endpoint http://chainfire:2379

# 全コンポーネントの状態確認
photonctl status
```

---

## 8. まとめ

### 8.1 設計の核心

本設計の核心は「**選択肢を与える**」ことです：

1. **単体で動かしたい** → 単体運用モード
2. **段階的に統合したい** → 段階的統合パス
3. **完全なクラウド基盤が欲しい** → 完全統合モード

### 8.2 主要な設計決定

| 項目 | 決定事項 |
|-----|---------|
| モード検出 | 環境変数 > 設定ファイル > 自動検出 |
| 状態管理 | 単体: ローカル、統合: chainfire |
| 認証 | 単体: ローカル、統合: photonauth |
| 設定形式 | TOML（共通スキーマ） |
| データフロー | アダプターパターンで抽象化 |

### 8.3 移行パス図

```mermaid
graph LR
    A[レベル0: 単体] -->|+chainfire| B[レベル1: 状態共有]
    B -->|+photonauth| C[レベル2: 認証統合]
    C -->|+photonnet| D[レベル3: ネットワーク統合]
    D -->|+コントロールプレーン| E[レベル4: 完全統合]

    style A fill:#90EE90
    style B fill:#FFD700
    style C fill:#FFD700
    style D fill:#FFA500
    style E fill:#FF6347
```

### 8.4 次のステップ

1. **共通設定ライブラリの実装**: `photon-config`クレートの作成
2. **モード検出ロジックの実装**: 各コンポーネントへの統合
3. **移行ツールの開発**: 単体→統合のデータ移行スクリプト
4. **ドキュメント整備**: 各構成パターンのデプロイガイド

---

*本設計書はUltraCloudアーキテクチャの「単体運用と統合のバランス」について定義したものです。実装時には本設計に従いつつ、実際のユースケースに応じた調整を行ってください。*
