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

概要

PostHog インテグレーションのためのプロダクションレディなアーキテクチャパターン。

前提条件

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

プロジェクト構成

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

レイヤーアーキテクチャ

┌─────────────────────────────────────────┐
│             API レイヤー                  │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│          サービス レイヤー                │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│         PostHog レイヤー                  │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│      インフラストラクチャ レイヤー         │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

主要コンポーネント

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

// src/posthog/client.ts
export class PostHogService {
  private client: PostHogClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: PostHogConfig) {
    this.client = new PostHogClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('posthog');
  }

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

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

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

export function wrapPostHogError(error: unknown): PostHogServiceError {
  // Transform SDK errors to application errors
}

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

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

データフロー図

ユーザーリクエスト
     │
     ▼
┌─────────────┐
│   API       │
│   Gateway   │
└──────┬──────┘
       │
       ▼
┌─────────────┐    ┌─────────────┐
│   Service   │───▶│   Cache     │
│   Layer     │    │   (Redis)   │
└──────┬──────┘    └─────────────┘
       │
       ▼
┌─────────────┐
│ PostHog    │
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PostHog    │
│   API       │
└─────────────┘

設定管理

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

export function loadPostHogConfig(): PostHogConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./posthog.${env}.json`);
}

手順

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

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

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

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

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

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

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

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

出力

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

エラーハンドリング

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

例

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

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

リソース

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

フラッグシップスキル

複数環境のセットアップについては、posthog-multi-env-setup を参照してください。