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

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

brew tap oven-sh/bun
brew install bun

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

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

Workflow Overview

Total time: 55-70 minutes

1. Initialize (5 min) - Start servers, create todos
2. Backend (15-20 min) - Models + routes with mock data
3. Frontend (20-25 min) - Components + pages
4. Test (5-10 min) - Type check + manual verification
5. 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