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

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

In 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

In 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

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

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

In src/{app_name}/ui/routes/_sidebar/route.tsx , add new item to navItems array.

Phase 4: Testing

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 databricks-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 "

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:

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.

Related Skills

• databricks-app-python - for Streamlit, Dash, Gradio, or Flask apps

• databricks-asset-bundles - deploying APX apps via DABs

• databricks-python-sdk - backend SDK integration

• databricks-lakebase-provisioned - adding persistent PostgreSQL state to apps