ディレクトリ構成

databricks-apps-survey-analysis/
├── .github/workflows/deploy.yml   # main/stg/prd への push でデプロイ
├── .husky/pre-commit              # format:check + lint（実際に動く hook）
├── README.md                      # セットアップ・トラブルシューティング
└── nodejs-fastapi-hello-world-app/   # アプリ本体（すべてのコマンドはここで実行）
    ├── backend/
    │   ├── main.py                # router 登録 + SPA catch-all
    │   ├── settings.py            # .env / yaml から環境変数を解決
    │   ├── databricks_workspace.py  # WorkspaceClient の生成
    │   ├── generate_models_from_databricks.py  # UC スキーマから Pydantic モデル生成
    │   ├── models/                # Pydantic モデル
    │   ├── routes/                # FastAPI router（薄い層）
    │   ├── sql/                   # SQL クエリと Databricks 接続
    │   └── static/                # ビルド済みフロントエンド（git 管理下）
    ├── frontend/
    │   ├── vite.config.ts         # outDir=backend/static、/api を :8000 へプロキシ
    │   └── src/
    │       ├── api/generated/     # orval が生成するクライアント（手で編集しない）
    │       ├── components/        # <カテゴリ>/<Name>/index.tsx + index.scss
    │       ├── pages/             # <Name>/index.tsx + index.scss
    │       └── constants/         # dwh.ts（カタログ/スキーマ固定値）、navigation.ts
    ├── scripts/
    │   ├── generate_openapi.py    # FastAPI app から openapi.yaml を出力
    │   └── setup-husky.mjs        # husky のインストール先をリポジトリルートへ切り替える
    ├── _templates/component/new/  # hygen のコンポーネント雛形
    ├── app.yaml                   # Databricks Apps 設定（DATABRICKS_HTTP_PATH）
    ├── databricks.yml             # Asset Bundle 設定（workspace.host）
    ├── package.json
    └── requirements.txt

各ディレクトリの説明

ディレクトリ	説明
`backend/routes/`	FastAPI の router。`asyncio.to_thread` で同期の SQL 層を呼び、例外を HTTP ステータスにマップするだけの薄い層
`backend/sql/`	実際のクエリ。`databricks_client.run_query` が SQL Warehouse への唯一の入口
`backend/models/`	Pydantic モデル。`api.py` は手書き、テーブル別モデルは自動生成
`backend/static/`	`npm run build` の出力先。git 管理下でコミットされている
`frontend/src/api/generated/`	orval の生成物。`openapi.yaml` とあわせて手で編集しない
`frontend/src/components/`	`<カテゴリ>/<Name>/index.tsx` + `index.scss` の構成
`frontend/src/pages/`	ルーティングに対応するページ。`<Name>/index.tsx` + `index.scss`
`frontend/src/constants/`	`dwh.ts`（カタログ `cs` / スキーマ `cs_dm`）、`navigation.ts`（サイドバー項目）
`scripts/`	OpenAPI 出力と husky セットアップのユーティリティ

新ファイルを追加するとき

UI コンポーネント → npm run generate:component（hygen が frontend/src/components/<カテゴリ>/<Name>/ を作る）
ページ → frontend/src/pages/<Name>/index.tsx を作り、App.tsx に Route を追加、constants/navigation.ts にサイドバー項目を追加
API エンドポイント → backend/sql/ にクエリ、backend/models/ にモデル、backend/routes/ に router を追加し、backend/routes/__init__.py の routers に登録する。そのあと npm run generate:client で型を再生成する
API クライアント → 手で書かない。npm run generate:client の生成物を使う

ビルド成果物のコミットを忘れない

デプロイされるのは git に入っているファイルそのもの（backend/static/ を含む）。フロントエンドを変更したら npm run build の出力もコミットしないと本番に反映されない。

死んでいる pre-commit

nodejs-fastapi-hello-world-app/.husky/pre-commit は使われていない。実際に動くのはリポジトリルートの .husky/pre-commit で、npm run prepare → scripts/setup-husky.mjs が husky のインストール先をルートに切り替えている。