Databricks APX Application

Build full-stack Databricks applications using APX framework (FastAPI + React).

Trigger Conditions

Invoke when user requests:

"Databricks app" or "Databricks application"
Full-stack app for Databricks without specifying framework
Mentions APX framework

Do NOT invoke if user specifies: Streamlit, Dash, Node.js, Shiny, Gradio, Flask, or other frameworks.

Prerequisites Check

Option A) Repository configured for use with APX. 1.. Verify APX MCP available:

mcp-cli tools | grep apx

2. Verify shadcn MCP available:

mcp-cli tools | grep shadcn

3. Confirm APX project (check

pyproject.toml

)

Option B) Install APX

Verify uv available or prompt for install. On Mac, suggest:
```
brew install uv
```
.
Verify bun available or prompt for install. On Mac, suggest:

brew tap oven-sh/bun
brew install bun

Verify git available or prompt for install.
Run APX setup commands:

uvx --from git+https://github.com/databricks-solutions/apx.git apx init

Workflow Overview

Total time: 55-70 minutes

Initialize (5 min) - Start servers, create todos
Backend (15-20 min) - Models + routes with mock data
Frontend (20-25 min) - Components + pages
Test (5-10 min) - Type check + manual verification
Document (10 min) - README + code structure guide

Phase 1: Initialize

bash

# Start APX development server
mcp-cli call apx/start '{}'
mcp-cli call apx/status '{}'

Create TodoWrite with tasks:

Start servers ✓
Design models
Create API routes
Add UI components
Create pages
Test & document

Phase 2: Backend Development

Create Pydantic Models

src/{app_name}/backend/models.py

Follow 3-model pattern:

```
EntityIn
```
- Input validation
```
EntityOut
```
- Complete output with computed fields
```
EntityListOut
```
- Performance-optimized summary

See backend-patterns.md for complete code templates.

Create API Routes

src/{app_name}/backend/router.py

Critical requirements:

Always include
```
response_model
```
(enables OpenAPI generation)
Always include
```
operation_id
```
(becomes frontend hook name)
Use naming pattern:
```
listX
```
,
```
getX
```
,
```
createX
```
,
```
updateX
```
,
```
deleteX
```
Initialize 3-4 mock data samples for testing

See backend-patterns.md for complete CRUD templates.

Type Check

bash

mcp-cli call apx/dev_check '{}'

Fix any Python type errors reported by basedpyright.

Phase 3: Frontend Development

Wait 5-10 seconds after backend changes for OpenAPI client regeneration.

Add UI Components

bash

# Get shadcn add command
mcp-cli call shadcn/get_add_command_for_items '{
  "items": ["@shadcn/button", "@shadcn/card", "@shadcn/table",
            "@shadcn/badge", "@shadcn/select", "@shadcn/skeleton"]
}'

Run the command from project root with

--yes

flag.

Create Pages

List page:

src/{app_name}/ui/routes/_sidebar/{entity}.tsx

Table view with all entities
Suspense boundaries with skeleton fallback
Formatted data (currency, dates, status colors)

Detail page:

src/{app_name}/ui/routes/_sidebar/{entity}.$id.tsx

Complete entity view with cards
Update/delete mutations
Back navigation

See frontend-patterns.md for complete page templates.

Update Navigation

src/{app_name}/ui/routes/_sidebar/route.tsx

, add new item to

navItems

array.

Phase 4: Testing

bash

# Type check both backend and frontend
mcp-cli call apx/dev_check '{}'

# Test API endpoints
curl http://localhost:8000/api/{entities} | jq .
curl http://localhost:8000/api/{entities}/{id} | jq .

# Get frontend URL
mcp-cli call apx/get_frontend_url '{}'

Manually verify in browser:

List page displays data
Detail page shows complete info
Mutations work (update, delete)
Loading states work (skeletons)
Browser console errors are automatically captured in APX dev logs

Phase 5: Deployment & Monitoring

Deploy to Databricks

Use DABs to deploy your APX application to Databricks. See the

asset-bundles

skill for complete deployment guidance.

Monitor Application Logs

Automated log checking with APX MCP:

The APX MCP server can automatically check deployed application logs. Simply ask: "Please check the deployed app logs for <app-name>"

The APX MCP will retrieve logs and identify issues automatically, including:

Deployment status and errors
Runtime exceptions and stack traces
Both
```
[SYSTEM]
```
(deployment) and
```
[APP]
```
(application) logs
Browser console errors (now included in APX dev logs)

Manual log checking (reference):

For direct CLI access:

bash

databricks apps logs <app-name> --profile <profile-name>

Key patterns to look for:

✅
```
Deployment successful
```
- App deployed correctly
✅
```
App started successfully
```
- Application is running
❌
```
Error:
```
- Check stack traces for issues

Phase 6: Documentation

Create two markdown files:

README.md:

Features overview
Technology stack
How app was created (AI tools + MCP servers used)
Application architecture
Getting started instructions
API documentation
Development workflow

CODE_STRUCTURE.md:

Directory structure explanation
Backend structure (models, routes, patterns)
Frontend structure (routes, components, hooks)
Auto-generated files warnings
Guide for adding new features
Best practices
Common patterns
Troubleshooting guide

Key Patterns

Backend

3-model pattern: Separate In, Out, and ListOut models
operation_id naming:
```
listEntities
```
→
```
useListEntities()
```
Type hints everywhere: Enable validation and IDE support

Frontend

Suspense hooks:
```
useXSuspense(selector())
```
Suspense boundaries: Always provide skeleton fallback
Formatters: Currency, dates, status colors
Never edit:
```
lib/api.ts
```
or
```
types/routeTree.gen.ts
```

Success Criteria

Type checking passes (
```
apx dev check
```
succeeds)
API endpoints return correct data (curl verification)
Frontend displays and mutates data correctly
Loading states work (skeletons display)
Documentation complete

Common Issues

Deployed app not working: Ask to check deployed app logs (APX MCP will automatically retrieve and analyze them) or manually use

databricks apps logs <app-name>

Python type errors: Use explicit casting for dict access, check Optional fields TypeScript errors: Wait for OpenAPI regen, verify hook names match operation_ids OpenAPI not updating: Check watcher status with

apx dev status

, restart if needed Components not added: Run shadcn from project root with

--yes

flag

Reference Materials

backend-patterns.md - Complete backend code templates
frontend-patterns.md - Complete frontend page templates
best-practices.md - Best practices, anti-patterns, debugging

Read these files only when actively writing that type of code or debugging issues.

databricks-app-apx

NPX Install

Tags

SKILL.md Content

Databricks APX Application

Trigger Conditions

Prerequisites Check

Workflow Overview

Phase 1: Initialize

Phase 2: Backend Development

Create Pydantic Models

Create API Routes

Type Check

Phase 3: Frontend Development

Add UI Components

Create Pages

Update Navigation

Phase 4: Testing

Phase 5: Deployment & Monitoring

Deploy to Databricks

Monitor Application Logs

Phase 6: Documentation

Key Patterns

Backend

Frontend

Success Criteria

Common Issues

Reference Materials