Skip to main content

Quick Start Guide - React + FastAPI Databricks App

🚀 Deploy to Databricks Apps (5 minutes)​

Prerequisites​

  • Databricks workspace with Apps enabled
  • OpenAI API key

Steps​

# 1. Set environment variables
export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_TOKEN=dapi1234567890abcdef
export OPENAI_API_KEY=sk-...

# 2. Deploy!
./scripts/deploy-databricks-app.sh

# 3. Access your app
# https://your-workspace.cloud.databricks.com/apps/open-navigator

That's it! 🎉

💻 Local Development (10 minutes)​

# Terminal 1 - Backend
source venv/bin/activate
uvicorn api.app:app --reload
# http://localhost:8000

# Terminal 2 - Frontend (hot reload!)
cd frontend
npm install
npm run dev
# http://localhost:3000

Option B: Production Mode (Test full build)​

# Build frontend
cd frontend
npm install
npm run build
cd ..

# Run app
source venv/bin/activate
python scripts/test-app.py
# http://localhost:8000

📁 Project Structure​

open-navigator/
├── frontend/                 # React app
│   ├── src/
│   │   ├── pages/           # Dashboard, Heatmap, etc.
│   │   └── components/      # Layout, etc.
│   └── package.json
│
├── api/
│   ├── app.py              # NEW: FastAPI for Databricks App
│   └── main.py             # LEGACY: Original CLI API
│
├── scripts/
│   ├── deploy-databricks-app.sh   # Deploy to cloud
│   ├── setup-local.sh             # Setup dev environment
│   └── test-app.py                # Test production build
│
├── app.yaml                # Databricks App config
└── Dockerfile.app          # Container image

🎯 Common Tasks​

Deploy to Databricks​

./scripts/deploy-databricks-app.sh

View App Logs​

databricks apps logs open-navigator --follow

Update Frontend​

cd frontend
# Make changes...
npm run build
cd ..
./scripts/deploy-databricks-app.sh

Run Tests​

source venv/bin/activate
pytest tests/

Check Agent Status​

curl http://localhost:8000/api/agents/status

📊 Frontend Pages​

PageRouteDescription
Dashboard/Stats, charts, recent activity
Heatmap/heatmapInteractive map of opportunities
Documents/documentsBrowse analyzed documents
Opportunities/opportunitiesManage advocacy opportunities
Settings/settingsConfigure system

🔧 Configuration​

Environment Variables​

VariableRequiredDescription
DATABRICKS_HOSTYesWorkspace URL
DATABRICKS_TOKENYesAccess token
OPENAI_API_KEYYesOpenAI API key
DATABRICKS_WAREHOUSE_IDYesSQL warehouse

Databricks Secrets​

# Create secrets scope
databricks secrets create-scope --scope oral-health-app

# Add secrets
databricks secrets put --scope oral-health-app --key host --string-value "$DATABRICKS_HOST"
databricks secrets put --scope oral-health-app --key token --string-value "$DATABRICKS_TOKEN"
databricks secrets put --scope oral-health-app --key openai_key --string-value "$OPENAI_API_KEY"

🐛 Troubleshooting​

"Frontend not built"​

cd frontend && npm install && npm run build

"Module not found"​

source venv/bin/activate
pip install -r requirements-cpu.txt

"Databricks CLI not found"​

pip install databricks-cli

"Can't connect to backend"​

Check that backend is running on :8000 and frontend proxies to it.

📚 Documentation​

  • Full Deployment Guide: DATABRICKS_APP_GUIDE.md
  • Refactoring Details: REACT_REFACTORING.md
  • Agent Bricks Info: databricks/README.md
  • Main README: README.md

🆘 Need Help?​

  1. Check logs: databricks apps logs open-navigator
  2. Review docs in the /docs folder
  3. Open an issue on GitHub

⚡ Pro Tips​

  • Use npm run dev for instant hot reload during UI development
  • Deploy often - deployment takes ~2 minutes
  • Monitor with databricks apps get open-navigator
  • Scale to zero saves costs when idle
  • Use Chrome DevTools to debug React components

Happy Advocating! 🦷✨