FireCrawl アーキテクチャバリアント

概要

FireCrawl インテグレーション用の3つの検証済みアーキテクチャブループリント

前提条件

• チームサイズおよび DAU 要件の理解
• デプロイメントインフラストラクチャの知識
• 明確な SLA 要件
• 成長予測の入手可能性

バリアント A: モノリス（シンプル）

最適な用途: MVP、小規模チーム、DAU < 10K

my-app/
├── src/
│   ├── firecrawl/
│   │   ├── client.ts          # Singleton client
│   │   ├── types.ts           # Types
│   │   └── middleware.ts      # Express middleware
│   ├── routes/
│   │   └── api/
│   │       └── firecrawl.ts    # API routes
│   └── index.ts
├── tests/
│   └── firecrawl.test.ts
└── package.json

主な特徴

• 単一のデプロイメントユニット
• リクエストパス内での同期的な FireCrawl 呼び出し
• インメモリキャッシング
• シンプルなエラーハンドリング

コードパターン

// ルートハンドラ内での直接インテグレーション
app.post('/api/create', async (req, res) => {
  try {
    const result = await firecrawlClient.create(req.body);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

---

バリアント B: サービスレイヤー（中程度）

最適な用途: 成長中のスタートアップ、DAU 10K～100K、複数のインテグレーション

my-app/
├── src/
│   ├── services/
│   │   ├── firecrawl/
│   │   │   ├── client.ts      # Client wrapper
│   │   │   ├── service.ts     # Business logic
│   │   │   ├── repository.ts  # Data access
│   │   │   └── types.ts
│   │   └── index.ts           # Service exports
│   ├── controllers/
│   │   └── firecrawl.ts
│   ├── routes/
│   ├── middleware/
│   ├── queue/
│   │   └── firecrawl-processor.ts  # Async processing
│   └── index.ts
├── config/
│   └── firecrawl/
└── package.json

主な特徴

• 関心の分離
• バックグラウンドジョブ処理
• Redis キャッシング
• サーキットブレーカーパターン
• 構造化されたエラーハンドリング

コードパターン

// サービスレイヤーの抽象化
class FireCrawlService {
  constructor(
    private client: FireCrawlClient,
    private cache: CacheService,
    private queue: QueueService
  ) {}

  async createResource(data: CreateInput): Promise<Resource> {
    // API 呼び出し前のビジネスロジック
    const validated = this.validate(data);

    // キャッシュを確認
    const cached = await this.cache.get(cacheKey);
    if (cached) return cached;

    // リトライ付きの API 呼び出し
    const result = await this.withRetry(() =>
      this.client.create(validated)
    );

    // 結果をキャッシュ
    await this.cache.set(cacheKey, result, 300);

    // 非同期フォローアップ
    await this.queue.enqueue('firecrawl.post-create', result);

    return result;
  }
}

---

バリアント C: マイクロサービス（複雑）

最適な用途: エンタープライズ、DAU 100K+、厳格な SLA

firecrawl-service/              # 専用マイクロサービス
├── src/
│   ├── api/
│   │   ├── grpc/
│   │   │   └── firecrawl.proto
│   │   └── rest/
│   │       └── routes.ts
│   ├── domain/
│   │   ├── entities/
│   │   ├── events/
│   │   └── services/
│   ├── infrastructure/
│   │   ├── firecrawl/
│   │   │   ├── client.ts
│   │   │   ├── mapper.ts
│   │   │   └── circuit-breaker.ts
│   │   ├── cache/
│   │   ├── queue/
│   │   └── database/
│   └── index.ts
├── config/
├── k8s/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── hpa.yaml
└── package.json

other-services/
├── order-service/       # firecrawl-service を呼び出し
├── payment-service/
└── notification-service/

主な特徴

• 専用の FireCrawl マイクロサービス
• 内部通信用の gRPC
• イベント駆動アーキテクチャ
• サービスごとのデータベース
• Kubernetes オートスケーリング
• 分散トレーシング
• サービスごとのサーキットブレーカー

コードパターン

// ドメイン分離を伴うイベント駆動
class FireCrawlAggregate {
  private events: DomainEvent[] = [];

  process(command: FireCrawlCommand): void {
    // ドメインロジック
    const result = this.execute(command);

    // ドメインイベントを発行
    this.events.push(new FireCrawlProcessedEvent(result));
  }

  getUncommittedEvents(): DomainEvent[] {
    return [...this.events];
  }
}

// イベントハンドラ
@EventHandler(FireCrawlProcessedEvent)
class FireCrawlEventHandler {
  async handle(event: FireCrawlProcessedEvent): Promise<void> {
    // Saga オーケストレーション
    await this.sagaOrchestrator.continue(event);
  }
}

---

決定マトリックス

要因	モノリス	サービスレイヤー	マイクロサービス
チームサイズ	1～5	5～20	20+
DAU	< 10K	10K～100K	100K+
デプロイメント頻度	週次	日次	継続的
障害隔離	なし	部分的	完全
運用の複雑性	低	中	高
市場投入時間	最速	中程度	最遅

マイグレーションパス

モノリス → サービスレイヤー:
1. FireCrawl コードを service/ に抽出
2. キャッシングレイヤーを追加
3. バックグラウンド処理を追加

サービスレイヤー → マイクロサービス:
1. 専用の firecrawl-service リポジトリを作成
2. gRPC コントラクトを定義
3. イベントバスを追加
4. Kubernetes にデプロイ
5. トラフィックを段階的にマイグレーション

手順

ステップ 1: 要件を評価

決定マトリックスを使用して適切なバリアントを特定します。

ステップ 2: アーキテクチャを選択

ニーズに基づいて、モノリス、サービスレイヤー、またはマイクロサービスを選択します。

ステップ 3: 構造を実装

選択したブループリントに従ってプロジェクトレイアウトをセットアップします。

ステップ 4: マイグレーションパスを計画

将来のスケーリング時のアップグレードパスを文書化します。

出力

• 選択されたアーキテクチャバリアント
• 実装されたプロジェクト構造
• 文書化されたマイグレーションパス
• 適切なパターンの適用

エラーハンドリング

問題	原因	解決策
過度な設計	誤ったバリアント選択	よりシンプルな構成から開始
パフォーマンス問題	不適切なレイヤー選択	キャッシング/非同期処理を追加
チーム間の衝突	複雑なアーキテクチャ	シンプル化またはトレーニング
デプロイメント複雑性	マイクロサービスのオーバーヘッド	サービスレイヤーを検討

例

クイックバリアント確認

# チームサイズと DAU をカウントしてバリアントを選択
echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
echo "DAU: Check analytics dashboard"

リソース

• Monolith First
• Microservices Guide
• FireCrawl Architecture Guide

次のステップ

よくあるアンチパターンについては、firecrawl-known-pitfalls を参照してください。