Clay リファレンスアーキテクチャ

概要

Clay統合のための本番環境対応のアーキテクチャパターン。

前提条件

• レイヤードアーキテクチャの理解
• Clay SDK の知識
• TypeScript プロジェクトのセットアップ
• テストフレームワークの構成

プロジェクト構成

my-clay-project/
├── src/
│   ├── clay/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── clay/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── clay/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── clay/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── clay/
│   └── integration/
│       └── clay/
├── config/
│   ├── clay.development.json
│   ├── clay.staging.json
│   └── clay.production.json
└── docs/
    └── clay/
        ├── SETUP.md
        └── RUNBOOK.md

レイヤーアーキテクチャ

┌─────────────────────────────────────────┐
│             APIレイヤー                  │
│  (コントローラー、ルート、ウェブフック) │
├─────────────────────────────────────────┤
│          サービスレイヤー                │
│  (ビジネスロジック、オーケストレーション)│
├─────────────────────────────────────────┤
│          Clay レイヤー                   │
│  (クライアント、型、エラーハンドリング) │
├─────────────────────────────────────────┤
│       インフラストラクチャレイヤー       │
│   (キャッシュ、キュー、監視)             │
└─────────────────────────────────────────┘

主要コンポーネント

ステップ 1: クライアントラッパー

// src/clay/client.ts
export class ClayService {
  private client: ClayClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: ClayConfig) {
    this.client = new ClayClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('clay');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

ステップ 2: エラーバウンダリー

// src/clay/errors.ts
export class ClayServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'ClayServiceError';
  }
}

export function wrapClayError(error: unknown): ClayServiceError {
  // Transform SDK errors to application errors
}

ステップ 3: ヘルスチェック

// src/clay/health.ts
export async function checkClayHealth(): Promise<HealthStatus> {
  try {
    const start = Date.now();
    await clayClient.ping();
    return {
      status: 'healthy',
      latencyMs: Date.now() - start,
    };
  } catch (error) {
    return { status: 'unhealthy', error: error.message };
  }
}

データフロー図

ユーザーリクエスト
     │
     ▼
┌─────────────┐
│   API       │
│  ゲートウェイ│
└──────┬──────┘
       │
       ▼
┌─────────────┐    ┌─────────────┐
│  サービス   │───▶│  キャッシュ  │
│   レイヤー  │    │ (Redis)     │
└──────┬──────┘    └─────────────┘
       │
       ▼
┌─────────────┐
│  Clay       │
│  クライアント│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Clay       │
│   API       │
└─────────────┘

設定管理

// config/clay.ts
export interface ClayConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  timeout: number;
  retries: number;
  cache: {
    enabled: boolean;
    ttlSeconds: number;
  };
}

export function loadClayConfig(): ClayConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./clay.${env}.json`);
}

手順

ステップ 1: ディレクトリ構造を作成する

上記のリファレンス構造に従ってプロジェクトレイアウトをセットアップします。

ステップ 2: クライアントラッパーを実装する

キャッシングと監視を備えたシングルトンクライアントを作成します。

ステップ 3: エラーハンドリングを追加する

Clay操作用のカスタムエラークラスを実装します。

ステップ 4: ヘルスチェックを設定する

Clay接続性のためのヘルスチェックエンドポイントを追加します。

成果物

• 構造化されたプロジェクトレイアウト
• キャッシング機能付きのクライアントラッパー
• 実装されたエラーバウンダリー
• 設定済みのヘルスチェック

エラーハンドリング

問題	原因	解決策
循環依存	レイヤー構成が不適切	レイヤーごとに関心を分離する
設定が読み込まれない	パスが不正	設定ファイルの場所を確認する
型エラー	型が欠落	Clay型を追加する
テストの分離	状態の共有	依存関係の注入を使用する

例

クイックセットアップスクリプト

# Create reference structure
mkdir -p src/clay/{handlers} src/services/clay src/api/clay
touch src/clay/{client,config,types,errors}.ts
touch src/services/clay/{index,sync,cache}.ts

リソース

• Clay SDK Documentation
• Clay Best Practices

関連スキル

マルチ環境セットアップについては、clay-multi-env-setup を参照してください。