Directory Architecture

databricks-apps-survey-analysis/
├── .github/workflows/deploy.yml   # Deploys on push to main/stg/prd
├── .husky/pre-commit              # format:check + lint (the hook that actually runs)
├── README.md                      # Setup and troubleshooting
└── nodejs-fastapi-hello-world-app/   # The app itself (run every command here)
    ├── backend/
    │   ├── main.py                # Router registration + SPA catch-all
    │   ├── settings.py            # Resolves env vars from .env / yaml
    │   ├── databricks_workspace.py  # Builds the WorkspaceClient
    │   ├── generate_models_from_databricks.py  # Generates Pydantic models from UC schemas
    │   ├── models/                # Pydantic models
    │   ├── routes/                # FastAPI routers (thin layer)
    │   ├── sql/                   # SQL queries and Databricks connection
    │   └── static/                # Built frontend (tracked in git)
    ├── frontend/
    │   ├── vite.config.ts         # outDir=backend/static, proxies /api to :8000
    │   └── src/
    │       ├── api/generated/     # orval-generated client (never hand-edit)
    │       ├── components/        # <category>/<Name>/index.tsx + index.scss
    │       ├── pages/             # <Name>/index.tsx + index.scss
    │       └── constants/         # dwh.ts (fixed catalog/schema), navigation.ts
    ├── scripts/
    │   ├── generate_openapi.py    # Dumps openapi.yaml from the FastAPI app
    │   └── setup-husky.mjs        # Points husky's install target at the repo root
    ├── _templates/component/new/  # hygen component scaffolds
    ├── app.yaml                   # Databricks Apps config (DATABRICKS_HTTP_PATH)
    ├── databricks.yml             # Asset Bundle config (workspace.host)
    ├── package.json
    └── requirements.txt

Directory Descriptions

Directory	Description
`backend/routes/`	FastAPI routers. A thin layer that calls the synchronous SQL layer via `asyncio.to_thread` and maps exceptions to HTTP status codes
`backend/sql/`	The actual queries. `databricks_client.run_query` is the only entry point to the SQL Warehouse
`backend/models/`	Pydantic models. `api.py` is hand-written; per-table models are auto-generated
`backend/static/`	Output of `npm run build`. Tracked and committed in git
`frontend/src/api/generated/`	orval output. Never hand-edit it, nor `openapi.yaml`
`frontend/src/components/`	Structured as `<category>/<Name>/index.tsx` + `index.scss`
`frontend/src/pages/`	Route-backed pages, as `<Name>/index.tsx` + `index.scss`
`frontend/src/constants/`	`dwh.ts` (catalog `cs` / schema `cs_dm`), `navigation.ts` (sidebar items)
`scripts/`	Utilities for OpenAPI output and husky setup

Where to Add New Files

UI component → npm run generate:component (hygen creates frontend/src/components/<category>/<Name>/)
Page → create frontend/src/pages/<Name>/index.tsx, add a Route in App.tsx, and add a sidebar entry in constants/navigation.ts
API endpoint → add the query in backend/sql/, the model in backend/models/, and the router in backend/routes/, then register it in routers in backend/routes/__init__.py. Regenerate types with npm run generate:client
API client → never hand-write it; use the output of npm run generate:client

Do not forget to commit build output

What gets deployed is exactly what is in git, including backend/static/. After changing the frontend, the npm run build output must be committed or production will not reflect it.

A dead pre-commit hook

nodejs-fastapi-hello-world-app/.husky/pre-commit is unused. The hook that actually runs is .husky/pre-commit at the repository root; npm run prepare → scripts/setup-husky.mjs switches husky's install target to the root.