Databricks APX Application

Trigger Conditions

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

Prerequisites Check

mcp-cli tools | grep apx

mcp-cli tools | grep shadcn

pyproject.toml

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

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

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

Workflow Overview

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 '{}'

• 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

• EntityIn

  - Input validation

• EntityOut

  - Complete output with computed fields

• EntityListOut

  - Performance-optimized summary

Create API Routes

src/{app_name}/backend/router.py

• 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

Type Check

mcp-cli call apx/dev_check '{}'

Phase 3: Frontend Development

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"]
}'

--yes

Create Pages

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

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

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

• Complete entity view with cards
• Update/delete mutations
• Back navigation

Update Navigation

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

navItems

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 '{}'

• 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

asset-bundles

Monitor Application Logs

• 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)

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

• ✅

  Deployment successful

  - App deployed correctly
• ✅

  App started successfully

  - Application is running
• ❌

  Error:

  - Check stack traces for issues

Phase 6: Documentation

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

• 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

databricks apps logs <app-name>

apx dev status

--yes

Reference Materials

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