docs: describe development flow and app management (#55)

pkosiec · web-flow · commit 5284177beba1 · 2026-01-15T11:06:19.000+01:00
* docs: describe development flow and app management

* chore: improve docs after review
diff --git a/docs/docs/_prerequisites.mdx b/docs/docs/_prerequisites.mdx
@@ -0,0 +1,4 @@
+## Prerequisites
+
+- [Node.js](https://nodejs.org) environment
+- Databricks CLI: install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
diff --git a/docs/docs/app-management.mdx b/docs/docs/app-management.mdx
@@ -0,0 +1,157 @@
+---
+sidebar_position: 3
+---
+
+import Prerequisites from './_prerequisites.mdx';
+
+# App management
+
+Manage your AppKit application throughout its lifecycle using the Databricks CLI. This guide covers deploying, starting, stopping, monitoring, and deleting apps.
+
+<Prerequisites />
+
+## Create app
+
+See the [Quick start](./index.md#quick-start-options) section to create a new Databricks app with AppKit installed.
+
+## Configuration
+
+Before deploying your app, configure it according to your needs. See the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation for details on:
+
+- App configuration file (`app.yaml`)
+- Environment variables
+- Authorization and permissions
+- Networking configuration
+
+## Deploy app
+
+Deploy your AppKit application using the automated deployment pipeline:
+
+```bash
+databricks apps deploy
+```
+
+This command runs a complete deployment pipeline:
+1. Builds the frontend (`npm run build`)
+2. Deploys the bundle to the workspace
+3. Runs the app
+
+:::note
+
+For all available options, run:
+```bash
+databricks apps deploy --help
+```
+:::
+
+### Examples
+
+- Deploy to a specific target:
+
+    ```bash
+    databricks apps deploy --target prod
+    ```
+
+- Deploy with custom variables:
+
+    ```bash
+    databricks apps deploy --var="warehouse_id=abc123"
+    ```
+
+- Skip the build step for faster iteration:
+
+    ```bash
+    databricks apps deploy --skip-build
+    ```
+
+- Force deploy (override Git branch validation):
+
+    ```bash
+    databricks apps deploy --force
+    ```
+
+## Start app
+
+To start a stopped app, run:
+
+```bash
+databricks apps start {name}
+```
+
+## Stop app
+
+Stop a running app without deleting it:
+
+```bash
+databricks apps stop {name}
+```
+
+## List all apps
+
+```bash
+databricks apps list
+```
+
+## Get detailed app information
+
+```bash
+databricks apps get {name}
+```
+
+## Stream app Logs
+
+Stream application logs in real-time:
+
+```bash
+databricks apps logs {name}
+```
+
+By default, this shows the most recent 200 log lines and exits.
+
+> **Note:** For all available options, run `databricks apps logs --help`
+
+### Examples
+
+- Show the last 50 log lines:
+
+    ```bash
+    databricks apps logs my-app --tail-lines 50
+    ```
+
+- Follow logs with a search filter:
+
+    ```bash
+    databricks apps logs my-app --follow --search ERROR
+    ```
+
+- Filter logs by source:
+
+    ```bash
+    databricks apps logs my-app --follow --source APP
+    ```
+
+- Save logs to a file:
+
+    ```bash
+    databricks apps logs my-app --follow --output-file app.log
+    ```
+
+- Stream logs for 5 minutes:
+
+    ```bash
+    databricks apps logs my-app --follow --timeout 5m
+    ```
+
+## Delete app
+
+Permanently delete an app:
+
+```bash
+databricks apps delete {name}
+```
+
+**⚠️ Warning:** This action cannot be undone. All app data and configurations will be removed.
+
+## See also
+
+For more information about Databricks Apps, including platform architecture, use cases, security, and advanced features, see the [Databricks Apps documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/).
diff --git a/docs/docs/core-concepts/_category_.json b/docs/docs/core-concepts/_category_.json
diff --git a/docs/docs/core-principles.md b/docs/docs/core-principles.md
@@ -1,4 +1,4 @@
-# Principles
+# Core Principles
 
 Learn about the fundamental concepts and principles behind AppKit.
 
diff --git a/docs/docs/development/_prerequisites_app.mdx b/docs/docs/development/_prerequisites_app.mdx
@@ -0,0 +1,5 @@
+## Prerequisites
+
+- [Node.js](https://nodejs.org) environment
+- Databricks CLI: install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+- A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](../index.md#quick-start-options) for more details.
diff --git a/docs/docs/development/ai-assisted-development.mdx b/docs/docs/development/ai-assisted-development.mdx
@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+---
+
+import Prerequisites from './_prerequisites_app.mdx';
+
+# AI-Assisted development
+
+<Prerequisites />
+
+AppKit integrates with AI coding assistants through the Model Context Protocol (MCP).
+
+## Installing MCP server
+
+To install the Databricks MCP server for your preferred AI assistant, run:
+
+```bash
+databricks experimental apps-mcp install
+```
+
+## MCP capabilities
+
+The MCP server exposes the following capabilities for AI assistants:
+
+- **Data exploration**: Query catalogs, schemas, tables, and execute SQL
+- **CLI command execution**: Deploy and manage apps, and run other workspace operations
+- **Workspace resource discovery**: Inspect and navigate workspace resources
+
+## Example prompts
+
+Here are some basic examples you can use to explore your app and workspace:
+
+1. Creating a new basic app
+  ```
+  Create a new Databricks app that displays a dashboard of the users table in main.default.
+  ```
+1. Introspecting a table schema
+  ```
+  Show me the schema of the users table in main.default.
+  ```
+1. Creating a new query
+  ```
+  Create a new query to find users created in the last 7 days.
+  ```
+1. Deploying an app
+  ```
+  Deploy the app to Databricks with the name "my-app".
+  ```
+
+Possibilities are virtually endless. Ask your AI assistant to help you with your app and workspace.
+
+## LLM resources
+
+AppKit provides specialized guidance files to help AI coding assistants work more effectively with the projects.
+
+If you're building applications using AppKit packages, reference the **[llms.txt](https://github.com/databricks/appkit/blob/main/llms.txt)** file.
diff --git a/docs/docs/development/index.mdx b/docs/docs/development/index.mdx
@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+import Prerequisites from './_prerequisites_app.mdx';
+
+# Development
+
+AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with MCP, and remote tunneling to deployed backends.
+
+<Prerequisites />
+
+## Development flows
+
+There are multiple supported development flows available with AppKit:
+
+1. **[Local development](./local-development.mdx)**: Run the development server with hot reload for both UI and backend code. This is the default development flow and is suitable for most use cases.
+2. **[AI-assisted development](./ai-assisted-development.mdx)**: Use an AI coding assistant connected via the Databricks MCP server to explore data, run CLI commands, and scaffold your app interactively.
+3. **[Remote bridge](./remote-bridge.mdx)**: Create a remote bridge to a deployed backend while keeping your queries and UI local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
+
+## See also
+ 
+- [App Management](../app-management.mdx): Manage your AppKit application throughout its lifecycle using the Databricks CLI
diff --git a/docs/docs/development/local-development.mdx b/docs/docs/development/local-development.mdx
@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+---
+
+import Prerequisites from './_prerequisites_app.mdx';
+
+# Local development
+
+<Prerequisites />
+
+Once your app is bootstrapped according to the [Manual quick start](../index.md#manual-quick-start) guide, you can start the development server with hot reload for both UI and backend code.
+
+In the application root directory, run the following command to start the development server:
+
+```bash
+npm run dev
+```
+
+This command will start the development server with hot reload for both UI and backend code. Open the displayed URL in your browser to see the app. Modify the code in the `src/` directory to see the changes reflected in the browser.
+
+To see the other available commands, read the `README.md` file in the application root directory.
diff --git a/docs/docs/development/remote-bridge.mdx b/docs/docs/development/remote-bridge.mdx
@@ -0,0 +1,86 @@
+---
+sidebar_position: 3
+---
+
+import Prerequisites from './_prerequisites_app.mdx';
+
+# Remote Bridge
+
+<Prerequisites />
+
+Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
+
+## When to use Remote Bridge
+
+Use remote bridge when:
+- Testing against production data
+- Debugging deployed backend code
+- Developing UI without running backend locally
+- Collaborating with team members on the same backend
+
+## Starting and stopping Remote Bridge
+
+To start the remote bridge, run the following command:
+
+```bash
+databricks apps dev-remote
+```
+
+The command will:
+
+1. Obtain app name from the context (either `app.yml` file or user input in the CLI)
+1. Start a local Vite development server
+2. Establish a WebSocket bridge to your deployed app
+3. Provide two URLs:
+
+   - **App URL**: Direct link for your own use (`<app-url>?dev=true`)
+   - **Shareable URL**: Link with tunnel ID for sharing with team members (`<app-url>?dev=<tunnelId>`)
+
+:::note
+
+For all available options, run:
+```bash
+databricks apps dev-remote --help
+```
+:::
+
+To stop the remote bridge, press `Ctrl+C` in the terminal.
+
+## Connection approval
+
+When you start remote bridge, every time you open the URL in your browser from a new device, you'll be prompted to approve the connection.
+
+You can provide the URL to your team members to allow them to see the app in their browser. You will still need to approve the connection from your side.
+
+## How it works
+
+Remote bridge creates a WebSocket bridge between your local Vite dev server and the deployed backend, allowing you to develop UI locally while using the deployed backend.
+
+```mermaid
+flowchart LR
+    Browser[Browser]
+    Backend[Deployed Backend]
+    Bridge[WebSocket Bridge]
+    LocalVite[Local Vite Dev Server]
+
+    Browser <-->|HTTPS| Backend
+    Backend <-->|WSS Tunnel| Bridge
+    Bridge <-->|HTTP/WS| LocalVite
+```
+
+### Details
+
+- The **Browser** connects to the deployed app backend with `?dev=true` or `?dev=<tunnelId>` query parameter
+- The **Deployed Backend** proxies UI requests through a WebSocket tunnel (`/dev-tunnel`) to your local machine
+- The **WebSocket Bridge** (running locally) receives fetch requests and file read requests from the backend
+- The **Local Vite Dev Server** serves the UI files and provides hot module replacement (HMR)
+- The bridge sends responses back through the WebSocket to the backend, which serves them to the browser
+
+### What gets hot-reloaded
+
+With remote bridge you get instant hot-reload for:
+
+- **UI Changes** - Any changes to your React/TypeScript/CSS files in the `client/` directory
+- **Query Files** - SQL files in the `config/queries/` directory (`.sql` files only)
+
+Backend code is **not** hot-reloaded. You need to redeploy your app to see changes in the backend code.
diff --git a/docs/docs/index.md b/docs/docs/index.md
diff --git a/docs/src/pages/contributing.md b/docs/src/pages/contributing.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Principles`
	`1`	`+# Core Principles`
`2`	`2`
`3`	`3`	`Learn about the fundamental concepts and principles behind AppKit.`
`4`	`4`