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

概要

Groq統合向けのプロダクションレディなアーキテクチャパターン。

前提条件

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

プロジェクト構成

my-groq-project/
├── src/
│   ├── groq/
│   │   ├── 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/
│   │   └── groq/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── groq/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── groq/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── groq/
│   └── integration/
│       └── groq/
├── config/
│   ├── groq.development.json
│   ├── groq.staging.json
│   └── groq.production.json
└── docs/
    └── groq/
        ├── SETUP.md
        └── RUNBOOK.md

レイヤーアーキテクチャ

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

主要コンポーネント

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

// src/groq/client.ts
export class GroqService {
  private client: GroqClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: GroqConfig) {
    this.client = new GroqClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('groq');
  }

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

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

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

export function wrapGroqError(error: unknown): GroqServiceError {
  // Transform SDK errors to application errors
}

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

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

データフロー図

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

設定管理

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

export function loadGroqConfig(): GroqConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./groq.${env}.json`);
}

手順

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

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

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

キャッシング とモニタリングを備えた シングルトン クライアントを作成します。

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

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

ステップ 4: ヘルスチェックの設定

Groq接続向けのヘルスチェック エンドポイントを追加します。

出力

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

エラーハンドリング

問題	原因	解決方法
循環依存	レイヤリングが不正	関心事をレイヤーで分離
設定の読み込み失敗	パスが不正	設定ファイルの場所を確認
型エラー	型が不足	Groq型を追加
テスト分離の問題	共有状態	依存性注入を使用

例

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

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

リソース

• Groq SDK ドキュメント
• Groq ベストプラクティス

フラッグシップスキル

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