[Architecture] API契約とClean Architectureの依存境界を整理する

[hmjn023]

概要

indexionで依存グラフを確認したところ、パッケージ単位では循環依存はありませんでしたが、server内部の層境界とAPI契約のSource of Truthに不整合があります。

確認できた問題

1. API契約が二重化している

共有契約は packages/core/src/domain/contract/index.ts:37 の appContract に定義されています。一方、serverは apps/server/src/domain/shared/api-contract.ts:1 でinfrastructure routerを集約した別の appRouter を定義しています。

• Tauri/xtracterは AppContract を使用
• server内部clientは typeof appRouter を使用
• server routerは共有契約を実装にバインドせず、各routerで os を個別定義
• domain/shared/api-contract.ts がdomain配下からinfrastructure routerを17本参照

契約変更時にserver実装との不一致をコンパイル時に保証できず、API契約が二つのSource of Truthになっています。

2. application層からinfrastructureへ逆依存している

indexionでは apps/server/src/application から infrastructure への依存が23辺ありました。

具体例:

• apps/server/src/application/registry.ts:16 がinfrastructureの JobWorker 型を参照
• apps/server/src/application/services/ccip-vector-service.ts:5 が PostgresCcipVectorStore を生成
• apps/server/src/application/services/directory-sync-service.ts:7 以降がrepository、job、event bus、loggerを直接参照

server固有のcomposition/wiringとapplication serviceの責務が混在しています。

3. 実行時依存の宣言と実際のimportが不一致

packages/ui/package.json:33 では @solid-imager/core がdevDependenciesですが、以下のように実行時importがあります。

• packages/ui/src/v2-source-form-modal.tsx:5
• packages/ui/src/search-control-panel.tsx:5
• packages/ui/src/v2-upload-media-modal.tsx:1

単独ビルド・公開・インストール時に依存解決できない可能性があります。

4. infrastructureがUI所有の契約に依存している

apps/server/src/infrastructure/api/clients/preset-client.ts:1 が、packages/ui/src/preset-client.ts:6 の PresetOrpcLike を参照しています。

API adapterの契約がUI packageに置かれているため、infrastructure → UIという逆方向の依存になっています。

5. 不要または古いserver依存が残っている

• apps/cli/package.json:20 の @solid-imager/server はCLI実装から使用されていない。CLIは @solid-imager/client を使用している。
• apps/xtracter/vite.config.ts:23 と apps/xtracter/tsconfig.json:20 にserver実装へのaliasが残っているが、xtracter/srcからの利用は確認できない。
• apps/xtracter/package.json:17 の @orpc/server もsrcからの利用が確認できない。

対応方針

• 共有 appContract をAPI契約のSource of Truthに統一し、server実装との型検証を行う
• serverのrouter集約をdomain配下から適切なpresentation/infrastructure境界へ移す
• application serviceから具体的なinfrastructure実装を分離し、composition rootでDIする
• ServiceRegistry の配置とservice locator依存を見直す
• PresetOrpcLike をUI以外の適切なshared contract層へ移す
• packages/ui の @solid-imager/core をruntime dependencyへ移す
• 不要なserver依存・alias・@orpc/server を削除し、各build/typecheckで確認する
• 既存のAPI/E2Eテストで契約互換性を検証する

参考

indexionのパッケージ集約結果:

• 循環依存: 0件
• workspace間の依存辺: 443件
• packages/ui → packages/core: 97辺
• apps/server/src/application → infrastructure: 23辺
• apps/server/src/domain → infrastructure: 17辺

依存グラフ:

• docs/architecture/indexion-dependency-graph.md
• docs/architecture/package-dependency-graph.md