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 initWorkflow 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 validationEntityOut- Complete output with computed fieldsEntityListOut- 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.tsortypes/routeTree.gen.ts
Success Criteria
- Type checking passes (
apx dev checksucceeds) - 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