@@ -455,7 +455,46 @@ Output format varies by AppKit version. Look for confirmation that the server is
455455
456456**Architecture — Local Development:**
457457
458- Browser (localhost:8000) -> Vite Dev Server (HMR + Proxy) -> AppKit Backend (Node.js/Express) -> SQL Warehouse (Databricks)
458+ ```mermaid
459+ graph LR
460+ Browser["Browser<br/>localhost:8000"] --> Vite["Vite Dev Server<br/>(HMR + Proxy)"]
461+ Vite --> AppKit["AppKit Backend<br/>(Node.js/Express)"]
462+ AppKit --> SQLWarehouse["SQL Warehouse<br/>(Databricks)"]
463+
464+ subgraph local [Local Machine]
465+ Browser
466+ Vite
467+ AppKit
468+ end
469+
470+ subgraph cloud [Databricks Cloud]
471+ SQLWarehouse
472+ end
473+ ```
474+
475+ **What you should see in the browser:**
476+
477+ ```
478+ ┌─────────────────────────────────────────────────────────────┐
479+ │ My App Dashboard | Details│
480+ ├─────────────────────────────────────────────────────────────┤
481+ │ │
482+ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
483+ │ │ Total │ │ Active │ │ Revenue │ │ Growth │ │
484+ │ │ Orders │ │ Users │ │ $12,450 │ │ +15.3% │ │
485+ │ │ 1,247 │ │ 342 │ │ │ │ │ │
486+ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
487+ │ │
488+ │ ┌─────────────────────────────┐ ┌────────────────────┐ │
489+ │ │ Orders by Status │ │ Recent Activity │ │
490+ │ │ ████████████ Completed 72% │ │ Order #1247 ... │ │
491+ │ │ ██████ Pending 20% │ │ Order #1246 ... │ │
492+ │ │ ███ Cancelled 8% │ │ Order #1245 ... │ │
493+ │ │ │ │ Order #1244 ... │ │
494+ │ └─────────────────────────────┘ └────────────────────┘ │
495+ │ │
496+ └─────────────────────────────────────────────────────────────┘
497+ ```
459498
460499**Verification — curl test:**
461500
@@ -814,7 +853,7 @@ This prompt is returned as-is for direct use in Cursor/Copilot. No LLM processin
814853
815854**Full API test battery:**
816855
817- ```
856+ ```json
818857$ curl -s "$APP_URL/api/health/lakebase" | jq .
819858{
820859 "status": "connected",
@@ -834,39 +873,62 @@ $ curl -s "$APP_URL/api/orders" | jq .
834873
835874**App logs — healthy Lakebase connections:**
836875
837- Log format varies by AppKit version. Check for: Analytics and Lakebase plugins loaded, ConnectionPool initialized, DDL executed, server listening on port 8000, and [Lakebase]-prefixed query logs. Absence of ERROR-level messages indicates a healthy startup.
876+ Log format varies by AppKit version. Check `databricks apps logs $APP_NAME --tail-lines 30 --profile $PROFILE` for: Analytics and Lakebase plugins loaded, ConnectionPool initialized, DDL executed, server listening on port 8000, and [Lakebase]-prefixed query logs. Absence of ERROR-level messages indicates a healthy startup.
838877
839878**Idle connection test timeline:**
840879
841880```
842- T+0:00 All endpoints return "source": "live"
843- T+3:00 Lakebase may scale to zero (idle)
844- T+5:00 Reload browser + re-test
845- curl /api/health/lakebase -> { "status": "connected", "source": "live" }
881+ T+0:00 ───── All endpoints return "source": "live" ✓
882+ │
883+ │ (no interaction — app idle)
884+ │
885+ T+3:00 ───── Lakebase may scale to zero
886+ │
887+ T+5:00 ───── Reload browser + re-test
888+ │
889+ ▼
890+ curl /api/health/lakebase → { "status": "connected", "source": "live" } ✓
846891 ConnectionPool auto-recovered after cold start
847892```
848893
849894**Architecture — Final Production State:**
850895
851- User Browser (HTTPS) -> Databricks Apps (Managed Hosting) -> AppKit Server (Node.js)
852- -> Analytics queries -> SQL Warehouse
853- -> CRUD operations -> Lakebase PostgreSQL
854- -> OAuth token refresh (automatic, every 58min) -> Databricks Auth
896+ ```mermaid
897+ graph LR
898+ User["User Browser<br/>(HTTPS)"] --> DatabricksApps["Databricks Apps<br/>(Managed Hosting)"]
899+ DatabricksApps --> AppKit["AppKit Server<br/>(Node.js)"]
900+ AppKit -->|"Analytics queries"| SQLWarehouse["SQL Warehouse"]
901+ AppKit -->|"CRUD operations"| Lakebase["Lakebase PostgreSQL"]
902+ AppKit -.->|"OAuth token refresh<br/>(automatic, every 58min)"| TokenService["Databricks Auth"]
903+
904+ subgraph cloud [Databricks Cloud]
905+ DatabricksApps
906+ AppKit
907+ SQLWarehouse
908+ Lakebase
909+ TokenService
910+ end
911+ ```
855912
856913**Final verification dashboard:**
857914
858915```
859- E2E Verification Results
860- Test Status Details
861- App deployed & RUNNING PASS State: RUNNING
862- UI loads in browser PASS React app rendered
863- /api/health/lakebase PASS source: live
864- /api/orders PASS 3 rows, source: live
865- App logs - no errors PASS ConnectionPool OK
866- SQL warehouse queries PASS Analytics data loaded
867- Idle test (5 min) PASS Auto-recovered
868- ConnectionStatus UI PASS Shows "Live Data"
869- TOTAL 8/8 All tests passed
916+ ┌──────────────────────────────────────────────────────────────────┐
917+ │ E2E Verification Results │
918+ ├──────────────────────────────┬──────────┬────────────────────────┤
919+ │ Test │ Status │ Details │
920+ ├──────────────────────────────┼──────────┼────────────────────────┤
921+ │ App deployed & RUNNING │ PASS ✓ │ State: RUNNING │
922+ │ UI loads in browser │ PASS ✓ │ React app rendered │
923+ │ /api/health/lakebase │ PASS ✓ │ source: live │
924+ │ /api/orders │ PASS ✓ │ 3 rows, source: live │
925+ │ App logs — no errors │ PASS ✓ │ ConnectionPool OK │
926+ │ SQL warehouse queries │ PASS ✓ │ Analytics data loaded │
927+ │ Idle test (5 min) │ PASS ✓ │ Auto-recovered │
928+ │ ConnectionStatus UI │ PASS ✓ │ Shows "Live Data" │
929+ ├──────────────────────────────┼──────────┼────────────────────────┤
930+ │ TOTAL │ 8/8 ✓ │ All tests passed │
931+ └──────────────────────────────┴──────────┴────────────────────────┘
870932```' ,
871933
872934TRUE,
@@ -5953,13 +6015,26 @@ This prompt is returned as-is for direct use in Cursor/Copilot. No LLM processin
59536015
59546016**Architecture — Dual Data Sources:**
59556017
5956- Browser (localhost:8000) -> AppKit Backend (Node.js/Express)
5957- -> useAnalyticsQuery() -> SQL Warehouse (Analytics reads)
5958- -> AppKit.lakebase.query() -> Lakebase (CRUD writes)
6018+ ```mermaid
6019+ graph LR
6020+ Browser["Browser<br/>localhost:8000"] --> AppKit["AppKit Backend<br/>(Node.js/Express)"]
6021+ AppKit -->|"useAnalyticsQuery()"| SQLWarehouse["SQL Warehouse<br/>(Analytics reads)"]
6022+ AppKit -->|"AppKit.lakebase.query()"| Lakebase["Lakebase<br/>(CRUD writes)"]
59596023
5960- **API health check — Lakebase connected:**
6024+ subgraph local [Local Machine]
6025+ Browser
6026+ AppKit
6027+ end
59616028
6029+ subgraph cloud [Databricks Cloud]
6030+ SQLWarehouse
6031+ Lakebase
6032+ end
59626033```
6034+
6035+ **API health check — Lakebase connected:**
6036+
6037+ ```json
59636038$ curl -s http://localhost:8000/api/health/lakebase | jq .
59646039{
59656040 "status": "connected",
@@ -5969,7 +6044,7 @@ $ curl -s http://localhost:8000/api/health/lakebase | jq .
59696044
59706045**API data endpoint — live data:**
59716046
5972- ```
6047+ ```json
59736048$ curl -s http://localhost:8000/api/orders | jq .
59746049{
59756050 "data": [
@@ -5987,12 +6062,23 @@ $ curl -s http://localhost:8000/api/orders | jq .
59876062
59886063**Before/After — The Phase 1 to Phase 4 Switch:**
59896064
5990- BEFORE (Phase 1): Static demo data arrays, Mock Data indicator
5991- AFTER (Phase 4): Live Lakebase data, Live Data indicator, real rows from database
6065+ ```
6066+ BEFORE (Phase 1 — static demo data): AFTER (Phase 4 — live Lakebase data):
6067+ ┌────────────────────────────────┐ ┌────────────────────────────────┐
6068+ │ ⚠ Mock Data — orders │ │ ✓ Live Data — orders │
6069+ │ │ │ │
6070+ │ id │ user │ amount │ status │ │ id │ user │ amount │ status │
6071+ │ ───┼────────┼────────┼────────│ │ ───┼────────┼────────┼────────│
6072+ │ 1 │ demo │ $99.99 │ mock │ │ 1 │ demo- │ $99.99 │ compl- │
6073+ │ │ │ │ │ │ 2 │ user │ $45.00 │ eted │
6074+ │ (hardcoded static array) │ │ 3 │ alice │ $72.50 │ pend- │
6075+ │ │ │ (live from Lakebase) │ ing │
6076+ └────────────────────────────────┘ └────────────────────────────────┘
6077+ ```
59926078
59936079**Terminal output — npm run dev with Lakebase:**
59946080
5995- Server running on port 8000, analytics and Lakebase plugins loaded, ConnectionPool initialized, DDL executed, [Lakebase]-prefixed query logs with row counts.' ,
6081+ Output format varies by AppKit version. Look for confirmation that the server is running on port 8000, both the analytics and Lakebase plugins loaded, and the ConnectionPool initialized. You should see your DDL statements executing successfully and [Lakebase]-prefixed query logs with row counts.' ,
59966082
59976083TRUE,
599860841 , TRUE, current_timestamp (), current_timestamp (), current_user ());
@@ -6126,11 +6212,22 @@ App deployed successfully!
61266212
61276213**Architecture — Deployed on Databricks:**
61286214
6129- User Browser (HTTPS) -> Databricks Apps (Managed Hosting) -> AppKit Server (Node.js) -> SQL Warehouse
6215+ ```mermaid
6216+ graph LR
6217+ User["User Browser<br/>(HTTPS)"] --> DatabricksApps["Databricks Apps<br/>(Managed Hosting)"]
6218+ DatabricksApps --> AppKit["AppKit Server<br/>(Node.js)"]
6219+ AppKit --> SQLWarehouse["SQL Warehouse"]
6220+
6221+ subgraph cloud [Databricks Cloud]
6222+ DatabricksApps
6223+ AppKit
6224+ SQLWarehouse
6225+ end
6226+ ```
61306227
61316228**App status — databricks apps get:**
61326229
6133- ```
6230+ ```json
61346231{
61356232 "name": "prashanth-s-bookings",
61366233 "url": "https://prashanth-s-bookings.cloud.databricks.com",
@@ -7965,4 +8062,4 @@ databricks bundle destroy --auto-approve
79658062- [ ] Catalog Explorer shows no workshop schemas
79668063- [ ] Lakebase Projects page shows no workshop project
79678064- [ ] Jobs page shows no workshop jobs' ,
7968- true, 1 , true, current_timestamp (), current_timestamp (), current_user ());
8065+ true, 1 , true, current_timestamp (), current_timestamp (), current_user ());
0 commit comments