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

概要

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

前提条件

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

プロジェクト構造

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

レイヤーアーキテクチャ

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

主要コンポーネント

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

// src/firecrawl/client.ts
export class FireCrawlService {
  private client: FireCrawlClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: FireCrawlConfig) {
    this.client = new FireCrawlClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('firecrawl');
  }

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

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

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

export function wrapFireCrawlError(error: unknown): FireCrawlServiceError {
  // Transform SDK errors to application errors
}

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

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

データフロー図

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

設定管理

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

export function loadFireCrawlConfig(): FireCrawlConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./firecrawl.${env}.json`);
}

手順

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

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

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

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

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

FireCrawl操作のためのカスタムエラークラスを実装します。

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

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

出力

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

エラーハンドリング

問題	原因	解決策
循環依存	不正なレイヤリング	レイヤー別に関心事を分離する
設定が読み込まれない	パスが正しくない	設定ファイルの場所を確認する
型エラー	型が不足している	FireCrawl型を追加する
テスト分離	状態共有	依存性の注入を使用する

例

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

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

リソース

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

フラッグシップスキル

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