1. ドメイン型

src/domain.ts は、プロジェクト内で唯一、内部 import を持たないファイルです。アプリの残り全部が共有する語彙です。

ここに置くもの

src/domain.ts

export type Brain = {
  id: string;
  name: string;
  folderPath: string;
  workspace: string;
  status: "indexing" | "indexed" | "error";
  fileCount: number;
  chunkCount: number;
  createdAt: string;
  updatedAt: string;
  lastIndexedAt?: string;
  lastError?: string;
};

export type LocalDocument = {
  relativePath: string;
  content: string;
  checksum: string;
  bytes: number;
};

export type BrowserDocumentInput = {
  relativePath: string;
  content: string;
  bytes: number;
};

export type TextChunk = {
  id: string;
  brainId: string;
  relativePath: string;
  chunkIndex: number;
  content: string;
  checksum: string;
};

export type ChatMessage = {
  role: "user" | "assistant" | "system";
  content: string;
};

export type Citation = {
  id: string;
  relativePath: string;
  chunkIndex: number;
  score?: number;
};

export type SearchHit = Citation & { content: string };
export type ChatAnswer = { answer: string; citations: Citation[] };

export type CreateBrainFromFilesInput = {
  name: string;
  folderName: string;
  documents: BrowserDocumentInput[];
};

export type CreateBrainFromFolderInput = {
  name: string;
  folderPath: string;
};

export class AppError extends Error {
  constructor(
    message: string,
    readonly status = 400,
  ) {
    super(message);
    this.name = "AppError";
  }
}

このファイルが存在する理由

理由は 2 つです。

モジュール間で動くデータの形を 1 か所に固定する。 Brain、 TextChunk、SearchHit、ChatAnswer は他のすべてのファイルが触ります。それらを 1 か所に置くことで、3 つのモジュールがそれぞれ少しずつ違う TextChunk のイメージを持つような事態を防げます。
AppError を再利用可能にする。 どのモジュールからも HTTP スタイルのステータス付き AppError を投げることができ、サーバーはそれをそのままレスポンスにマップできます。これがないと、各レイヤーに独自のエラー型が増えていきます。