---
name: pure TypeScript engine が backend API thin wrapper に隠れる過剰 architecture を avoid
description: ★★★★ 2026-05-03 site auto-update 化作業で 4 件 (/expression /radar /mystery /dashboard-v2) 同時発覚。 backend は API endpoint だけで、 engine 自体は Node 依存無しの pure TS だった = browser に直接 import すれば API 不要だった
type: feedback
originSessionId: 50069f57-0fc9-49bd-bad5-cf25148241c7
---
# Pure TypeScript engine が backend API に隠れる過剰 architecture を avoid

新規 component や engine を設計する時、 もし **backend API が thin wrapper だけ** (engine 内部に Node 依存なし) なら、 **browser-side で直接 import する方が単純** で、 API server 起動不要・ローカル開発と Web 公開で同一動作 になる。

**Why**: 2026-05-03 サイト全 route 自動更新化作業で、 以下 4 component が同じ structure で見つかった:
- `/expression` (PhilosophyExpressionEngine + AdvancedExpressionEngine)
- `/radar` (InformationRadarEngine + TheoryAutoGenerator)
- `/mystery` (AncientMysteryAnalyzer + MYSTERY_DATABASE + Theory564/565)
- `/dashboard-v2` (上記 4 engine 複合)

全て engine は **Node 依存ゼロの pure TypeScript** で、 backend API (`src/aios/api/*-api.ts`) は単に method を HTTP endpoint に wrap しているだけ。 過去の設計で SQLite/fs を想定したが実際は不要だった結果。 これら 4 件は今回 fix で **engine を直接 import** して API 削除 → CF Pages で完全動作に。

**How to apply**: 
- 新 component で「engine が必要」 と思った時、 まず engine の `import` 行を確認 — `from 'fs'` `from 'better-sqlite3'` `from 'node:'` 等が無ければ **browser に直接 import 可能**。
- 新 backend API を作る前に、 「これは engine の thin wrapper になりそうか?」 を問う。 そうなら **API を作らず、 engine を browser に直接 import する**選択を優先。
- 既存 component で `import { API_BASE } from '../../api-config'` を見たら、 component が依存している engine 全部 (e.g. `src/aios/expression/*.ts`) の Node 依存を grep し、 無ければ **engine 直接 import で API 不要化**を検討 (この pattern は Option C-static と呼ぶ、 cf. /expression /radar /mystery で適用済)。

cf. memory `feedback_index_html_bundle_sync.md` (vite build の bundle sync) と並ぶ「**過去の architecture 仮定が今は不要**」 系の load-bearing 観察。 同じ symptoms (CF Pages で動かない / API server 必要) を見たら、 まずこの可能性を疑う。