software-architecture

ソフトウェアアーキテクチャ

Clean ArchitectureとDDD（ドメイン駆動設計）の原則に基づく、対象プロジェクトの設計ガイドライン。

Domain層の実装パターン

本セクションのコード例は Next.js + Supabase + TypeScript スタックでの一例。Clean Architecture / DDD のレイヤ責務（Entity / Repository / Service の分離、Interface によるモック差し替え）は スタック非依存の普遍的な原則であり、構文・生成ファイル名・ハンドラ種別は採用スタックに読み替えること。 実際のレイヤ規約は common ARCHITECTURE.md を SSoT とする。

データフローの一例（4層構造）:

DB型（database.types.ts） → Entity型（models/） → Service（service/） → Server Actions（app/*/actions.ts）
                              ↓
                         Repository（repository/）

1. Entity層（models/）

型定義とクラスの併用パターン: 型で構造定義、クラスでビジネスロジックを実装する。

// domain/models/opportunity/index.ts

// 構造定義（Type）
export type OpportunityEntity = {
  id: string;
  title: string;
  salary_min: number;
  salary_max: number | null;
  deleted_at: string | null;
};

// ロジック実装（Class）
export class Opportunity {
  public readonly id: string;
  public readonly salaryMin: number;

  constructor(entity: OpportunityEntity) {
    this.id = entity.id;
    this.salaryMin = entity.salary_min;
  }

  isHighPay(): boolean {
    return this.salaryMin >= 1000000;
  }

  isDeleted(): boolean {
    return this.deletedAt !== null;
  }

  // Entity型 → UI型への変換
  toJob(): Job {
    return {
      id: this.id,
      salary: this.formatSalary(),
      highPay: this.isHighPay(),
    };
  }
}

判断基準: ビジネスルールが含まれる場合はClass、単純なデータ構造ならTypeのみで十分。

2. Repository層（repository/）

Interface + 実装クラスパターン: テスト時のモック差し替えを可能にする。

// domain/repository/saved-agent/index.ts

export interface ISavedAgentRepository {
  create(userId: string, agentId: string): Promise<SavedAgent>;
  findByUserAndAgent(
    userId: string,
    agentId: string,
  ): Promise<SavedAgent | null>;
  softDeleteByUserAndAgent(
    userId: string,
    agentId: string,
  ): Promise<SavedAgent | null>;
}

export class SavedAgentRepository implements ISavedAgentRepository {
  private admin = createSupabaseAdmin();

  async create(userId: string, agentId: string): Promise<SavedAgent> {
    const { data, error } = await this.admin
      .from('saved_agents')
      .insert({ user_id: userId, agent_id: agentId })
      .select()
      .single();

    if (error?.code === '23505') {
      throw new Error('既に保存済みです');
    }
    if (error) throw error;
    return SavedAgent.fromDatabase(data);
  }
}