elysia-architecture

Elysia アーキテクチャ

Elysia HTTP アプリ向けの、移植可能な標準スタイルです。このスキル単独で使用でき、他のスキルには依存しません。

役割： コードの配置場所、フォルダーやファイルの命名方法、責務の境界を定めます。

このスキルの対象外： Elysia API の細かな仕様、プラグインのライフサイクルの詳細、Eden、アダプター、最新のフレームワークドキュメントです。これらについては、最新の Elysia ドキュメントを優先してください。

対象リポジトリにすでにアーキテクチャの説明（例：AGENTS.md）があり、この内容と矛盾する場合は、ユーザーがこのスキルに合わせた移行を求めない限り、リポジトリの方針を優先します。

スタックのデフォルト設定（コア）

項目	デフォルト
ランタイム	Bun（アプリがすでに使用している場合は Node／アダプターも可）
HTTP	src/modules/<feature>/ 配下の Elysia 機能プラグイン
バージョン	Elysia 1.4 の ≥ 1.4.30（セキュリティ上の最低要件。信頼できない入力からルートスキーマを決して構築しないでください）。Elysia 2 はベータ版です。安定版がリリースされるまでは、標準スタイルのコードでは 1.4 を使用してください
モジュール構成	routes/ + schema/ + ドメインロジックのフォルダー
テスト	リポジトリで Vitest を使用している場合は、tests/ 配下に Vitest（ユニット／インテグレーションのプロジェクト）

ドメインロジックは、通常の TypeScript モジュールにしてもかまいません。該当するスタックがある場合は、対応する with-* 拡張を読み込んでください（以下を参照）。

モード

1. スキャフォールド — checklist.md と tree.md を使って、新しい機能モジュールを作成します。
2. 適用 — 新しいエンドポイント／スキーマ／サービスを標準の配置場所に置きます。
3. レビュー — ツリーを rules.md と照合し、移動案を提示します。並行する別の構成を作らないでください。

厳守するルール（コア）

1. 機能 = src/modules/<feature>/。 アプリのルートではなく、ドメイン（billing、users）ごとにまとめます。
2. 1 つのルートファイル = 安定した name を持つ、エクスポートされた Elysia プラグインの const 1 つで、通常は HTTP メソッド 1 つ（または密接に関連するグループ）を扱います。無関係なメソッドを 1 つのファイルに詰め込まないでください。export function makeXRoutes(...) は使用しないでください。
3. routes/index.ts はマウントテーブル専用です — .use(child)（＋prefix）のみを置きます。ハンドラー、ドメインロジック、共有マッパーは置かないでください。
4. スキーマは schema/ 配下に置きます（必要に応じて body、response、query、params）。DTO をルートファイルに詰め込んだり、スキーマですでに契約を定義しているのに、別途手書きのレスポンスインターフェースを作ったりしないでください。
5. ルートは薄く保ちます。 HTTP に関する処理（認証ガード、ステータスのマッピング、リクエスト／レスポンス）はルートファイルに置き、ビジネスルールはサービス（または通常のドメインモジュール）に置きます。
6. ルートファクトリー／共有 HTTP ラッパーは禁止です。 ハンドラーをラップする makeSyncGet、mapXToHttp、utils/*-http.ts などを作らないでください。各ルートファイルに境界処理を直接記述します。
7. プロセスのリソースはインポートします。注入しません。 データベース、Effect ランタイム、環境変数、キューは、import { db } from "…"、import { runtime } from "…" のようにインポートします。禁止事項：export function cmsRoutes(db: Db)、機能ルートでの .decorate("db", db)／.decorate("runtime", runtime)、またはマウントテーブルの引数を介したこれらの値の受け渡し。共有パッケージのプラグインはオプション（オリジン、プレフィックス）を受け取ってもかまいませんが、アプリ側では引き続き独自のシングルトンをインポートします。
8. 失敗のマッピングは HTTP 境界でのみ行います。 公開する本文は小さく保ちます（例：{ error: string } ＋ステータス）。内部の原因を漏らさないでください。
9. HTTP のために utils/ を増やさないでください。 schema/、サービス／ドメイン、またはルート境界へのインライン記述を優先します。
10. 命名： フォルダー名は名詞／ドメイン、ファイル名はアクションまたは側面（create.ts、status.ts）にします。末端の名前に親フォルダー名を繰り返さないでください（billing/billing-status.ts → billing/routes/status.ts）。
11. インポートの方向： routes → schema + services。services から routes をインポートしてはいけません。機能をまたぐ依存関係には services／共有パッケージを使用し、route→route のインポートは避けます。
12. マウント — アプリのエントリーポイント（または親機能のマウントテーブル）から機能ツリーをマウントします。

詳細、アンチパターン、例：rules.md、tree.md、examples.md。

段階的な情報開示

必要な情報	参照先
正規のツリー構造と命名	references/tree.md
ルールとアンチパターンの適用	references/rules.md
足場作成／レビュー用チェックリスト	references/checklist.md
良いレイアウトと悪いレイアウト	references/examples.md
オプションのスタックオーバーレイ	以下のExtensions

拡張機能

該当するスタックが存在する場合（またはユーザーから求められた場合）に限り、拡張機能を読み込みます。 拡張機能はルールを追加します。コアツリーを置き換えるものではありません。

条件	拡張機能
Effect サービス／Layers／タグ付きエラー	with-effect.md
T3 Env／パッケージでprocess.envを読み取らない	with-env.md
セッション認証マウント＋{ auth: true }マクロ	with-session-auth.md
ケイパビリティ／権限付与／ID 権限	with-capability-authz.md
jobs／公開 API での Bearer API キー	with-api-key-auth.md
Drizzle スキーマパッケージ＋サービス内の DB	with-drizzle.md
ルートスキーマから導出する OpenAPI	with-openapi.md
リクエストログ＋OTEL＋Effect トレーサー	with-observability.md
安定した公開エラーボディ＋エッジマッピング	with-http-errors.md
packages/*内のドメイン、アプリモジュール内の HTTP	with-domain-packages.md
共有 Elysia プラグインとアプリローカル Elysia プラグイン	with-shared-plugins.md
プロセス内 cron ティック	with-cron.md
プロバイダーの Webhook	with-webhooks.md
内部共有シークレットルート	with-service-auth.md
Vitest — Eden treaty(app)／テスト対象	with-vitest.md