From dabf3a57e062bf413522495e9859ee7087d33cde Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 13 Jan 2026 20:45:03 +0100 Subject: [PATCH 1/2] docs: describe plugins and high-level architecture --- docs/docs/api/index.md | 3 +- docs/docs/architecture.md | 93 +++++++++++++++++++++++++++++ docs/docs/development/index.mdx | 1 + docs/docs/plugins.md | 101 ++++++++++++++++++++++++++++++++ 4 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 docs/docs/architecture.md create mode 100644 docs/docs/plugins.md diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 22788cb..a79a004 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -7,6 +7,8 @@ This section contains the API reference for the AppKit packages. - [`appkit`](appkit/index.md) - Core library. Provides the core functionality for building Databricks applications. - [`appkit-ui`](appkit-ui/index.md) - UI components library. Provides a set of UI primitives for building Databricks apps in [React](https://react.dev/). +Learn more about the architecture of AppKit in the [architecture](../architecture.md) document. + ## Getting started To learn how to get started with AppKit, see the [getting started guide](../index.md) for AI-assisted and manual quick start options. @@ -19,4 +21,3 @@ To install the AppKit packages into your existing JavaScript/TypeScript project, npm install @databricks/appkit npm install @databricks/appkit-ui ``` - diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md new file mode 100644 index 0000000..4fafeed --- /dev/null +++ b/docs/docs/architecture.md @@ -0,0 +1,93 @@ +--- +sidebar_position: 4 +--- + +# Architecture + +AppKit follows a plugin-based architecture designed for building production-ready Databricks applications. This document provides a high-level overview of the system components and their interactions. + +## High-level architecture + +```mermaid +graph LR + User[User/Browser] + + subgraph serverLayer [Server Layer] + AppKitCore["appkit"] + PluginSystem[Plugin System] + Plugins[Plugins] + AppKitCore -->|Manages| PluginSystem + PluginSystem -->|Initializes| Plugins + end + + subgraph clientLayer [Client Layer] + ReactApp[React Application] + AppKitUI["appkit-ui"] + ReactApp -->|Uses| AppKitUI + end + + DatabricksServices[Databricks Services] + + User -->|Accesses| ReactApp + ReactApp <-->|HTTP/SSE| Plugins + Plugins -->|Queries| DatabricksServices +``` + +## Core components + +AppKit is organized into two main packages: + +### @databricks/appkit + +The backend SDK that provides the plugin architecture and core functionality. It includes: + +- Plugin system with lifecycle management +- Built-in server and analytics plugins +- Telemetry and observability features +- Cache management and streaming capabilities +- Type generation for SQL queries + +See the [Plugins](./plugins.md) and [API Reference](./api/appkit/) documentation for detailed information. + +### @databricks/appkit-ui + +A React UI library with pre-built components optimized for data applications: + +- React hooks for query execution and streaming +- UI components based on Radix UI and Tailwind +- Data visualization components +- Type-safe integration with backend queries + +See the [API Reference](./api/appkit-ui/) for component documentation. + +## Application layers + +### Client layer + +The React frontend layer that optionally uses `@databricks/appkit-ui` components: +- Renders UI components and visualizations +- Manages client state and user interactions +- Consumes backend APIs via HTTP and SSE +- Provides type-safe query execution hooks + +### Server layer + +The Node.js backend layer built with `@databricks/appkit`: +- Serves the React application (dev and production modes) +- Executes SQL queries against Databricks SQL Warehouses +- Handles authentication and authorization +- Provides caching, retry logic, and error handling +- Exposes REST APIs and SSE endpoints + +### Data layer + +Integration with Databricks services: +- **SQL Warehouses**: Execute analytical queries with Arrow or JSON format +- **Lakebase**: Access data from Lakebase + +## See also + +- [Plugins](./plugins.md): Deep dive into the plugin system +- [API Reference](./api/): Complete API documentation +- [Development](./development/): Explore development workflows +- [Core Principles](./core-principles.md): Learn about AppKit's design philosophy diff --git a/docs/docs/development/index.mdx b/docs/docs/development/index.mdx index 20fca75..aca754f 100644 --- a/docs/docs/development/index.mdx +++ b/docs/docs/development/index.mdx @@ -21,3 +21,4 @@ There are multiple supported development flows available with AppKit: ## See also - [App Management](../app-management.mdx): Manage your AppKit application throughout its lifecycle using the Databricks CLI +- [Architecture](../architecture.md): Learn about the architecture of AppKit diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md new file mode 100644 index 0000000..2bed603 --- /dev/null +++ b/docs/docs/plugins.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 3 +--- + +# Plugins + +Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming. + +For complete API documentation, see the [`Plugin`](api/appkit/Class.Plugin.md) class reference. + +## Built-in Plugins + +### Server Plugin + +Provides HTTP server capabilities with development and production modes. + +**Key features:** +- Express server for REST APIs +- Vite dev server with hot module reload +- Static file serving for production +- Remote tunneling to deployed backends + +The Server Plugin uses the deferred initialization phase to access routes from other plugins. + +### Analytics Plugin + +Enables SQL query execution against Databricks SQL Warehouses. + +**Key features:** +- File-based SQL queries with automatic type generation +- Parameterized queries with type-safe [SQL helpers](api/appkit/Variable.sql.md) +- JSON and Arrow format support +- Built-in caching and retry logic +- Server-Sent Events (SSE) streaming + +Store SQL queries in `config/queries/` directory and use parameterized queries with the [`sql`](api/appkit/Variable.sql.md) helper for type safety. + +## Using Plugins + +Configure plugins when creating your AppKit instance: + +```typescript +import { createApp, server, analytics } from "@databricks/app-kit"; + +const AppKit = await createApp({ + plugins: [ + server({ port: 8000 }), + analytics(), + ], +}); +``` + +For complete configuration options, see [`createApp`](api/appkit/Function.createApp.md). + +## Creating Custom Plugins + +Extend the [`Plugin`](api/appkit/Class.Plugin.md) class and export with `toPlugin()`: + +```typescript +import { Plugin, toPlugin } from "@databricks/app-kit"; + +interface MyPluginConfig { + apiKey?: string; +} + +export class MyPlugin extends Plugin { + name = "myPlugin"; + envVars = ["MY_API_KEY"]; + + async setup() { + // Initialize your plugin + } + + async shutdown() { + // Clean up resources + } +} + +export const myPlugin = toPlugin( + MyPlugin, + "myPlugin" +); +``` + +**Key extension points:** +- **Route injection**: Implement `injectRoutes()` to add custom endpoints using [`IAppRouter`](api/appkit/TypeAlias.IAppRouter.md) +- **Lifecycle hooks**: Override `setup()`, `shutdown()`, and `validateEnv()` methods +- **Shared services**: + - **Cache management**: Access the cache service via `this.cache`. See [`CacheConfig`](api/appkit/Interface.CacheConfig.md) for configuration. + - **Telemetry**: Instrument your plugin with traces and metrics via `this.telemetry`. See [`ITelemetry`](api/appkit/Interface.ITelemetry.md). +- **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](api/appkit/Interface.StreamExecutionSettings.md) + +See the [`Plugin`](api/appkit/Class.Plugin.md) API reference for complete documentation. + +## Plugin Phases + +Plugins initialize in three phases: + +- **Core**: Reserved for framework-level plugins. Initializes first. +- **Normal**: Default phase for application plugins. Initializes after core. +- **Deferred**: Initializes last with access to other plugin instances via `config.plugins`. Use when your plugin depends on other plugins (e.g., Server Plugin). From 2d0be87c7e287020d3b37c96c675ef70785c8f19 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Thu, 15 Jan 2026 11:16:18 +0100 Subject: [PATCH 2/2] chore: fix title capitalization --- docs/docs/api/index.md | 2 +- docs/docs/architecture.md | 6 +++--- docs/docs/core-principles.md | 16 ++++++++-------- docs/docs/development/index.mdx | 4 ++-- docs/docs/index.md | 6 +++--- docs/docs/plugins.md | 14 +++++++------- docs/docusaurus.config.ts | 2 +- docs/sidebars.ts | 2 +- 8 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index a79a004..d16354c 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -1,4 +1,4 @@ -# API Reference +# API reference This section contains the API reference for the AppKit packages. diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index 4fafeed..b29fbbc 100644 --- a/docs/docs/architecture.md +++ b/docs/docs/architecture.md @@ -47,7 +47,7 @@ The backend SDK that provides the plugin architecture and core functionality. It - Cache management and streaming capabilities - Type generation for SQL queries -See the [Plugins](./plugins.md) and [API Reference](./api/appkit/) documentation for detailed information. +See the [Plugins](./plugins.md) and [API reference](./api/appkit/) documentation for detailed information. ### @databricks/appkit-ui @@ -58,7 +58,7 @@ A React UI library with pre-built components optimized for data applications: - Data visualization components - Type-safe integration with backend queries -See the [API Reference](./api/appkit-ui/) for component documentation. +See the [API reference](./api/appkit-ui/) for component documentation. ## Application layers @@ -88,6 +88,6 @@ Integration with Databricks services: ## See also - [Plugins](./plugins.md): Deep dive into the plugin system -- [API Reference](./api/): Complete API documentation +- [API reference](./api/): Complete API documentation - [Development](./development/): Explore development workflows - [Core Principles](./core-principles.md): Learn about AppKit's design philosophy diff --git a/docs/docs/core-principles.md b/docs/docs/core-principles.md index ab094c3..791cd43 100644 --- a/docs/docs/core-principles.md +++ b/docs/docs/core-principles.md @@ -1,39 +1,39 @@ -# Core Principles +# Core principles Learn about the fundamental concepts and principles behind AppKit. -## 1. Highly Opinionated +## 1. Highly opinionated AppKit must provide a clear path with best practices for building Databricks applications. We provide strong defaults, with advanced customization when needed. -## 2. Built for Application Use Cases +## 2. Built for application use cases This SDK is for application development, not infrastructure management. Databricks' internal implementation details must be abstracted. We're building an application SDK, not a service wrapper. -## 3. Delightful Developer Experience +## 3. Delightful developer experience Every interface, doc, example, tool, and implementation must provide developer joy. Combined with the Highly Opinionated principle, this creates a true plug-and-play experience. -## 4. Zero-Trust Security +## 4. Zero-trust security Minimize exposed surface area, fail safely by default, and validate all inputs. AppKit must always have a zero-trust mindset. -## 5. Optimized for Humans and AI +## 5. Optimized for humans and AI Developers and LLMs both use this SDK. Every API must be discoverable, self-documenting, and inferable by both types of users. Test with both. -## 6. Production-Ready from Day One +## 6. Production-ready from day one Even the smallest feature can be used by enterprise users, so everything shipped must be production-ready. Observability, reliability, and scalability since day one. -## 7. Layered Extensibility +## 7. Layered extensibility AppKit provides high-level plugins, low-level primitives, and extension points for custom plugins. It integrates into any application architecture and never blocks your path forward. diff --git a/docs/docs/development/index.mdx b/docs/docs/development/index.mdx index aca754f..9c1c838 100644 --- a/docs/docs/development/index.mdx +++ b/docs/docs/development/index.mdx @@ -16,9 +16,9 @@ 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. +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 +- [App management](../app-management.mdx): Manage your AppKit application throughout its lifecycle using the Databricks CLI - [Architecture](../architecture.md): Learn about the architecture of AppKit diff --git a/docs/docs/index.md b/docs/docs/index.md index 2350b91..b684f68 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -84,6 +84,6 @@ This deploys the sample app to Databricks. ## Next steps -- **[App Management](./app-management.mdx)**: Manage your AppKit application throughout its lifecycle using the Databricks CLI -- **[API Reference](./api/appkit/)**: Explore the complete API documentation -- **[Core Concepts](./core-principles)**: Learn about AppKit's design principles and architecture +- **[App management](./app-management.mdx)**: Manage your AppKit application throughout its lifecycle using the Databricks CLI +- **[API reference](./api/appkit/)**: Explore the complete API documentation +- **[Core concepts](./core-principles)**: Learn about AppKit's design principles and architecture diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index 2bed603..f9159cb 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -8,9 +8,9 @@ Plugins are modular extensions that add capabilities to your AppKit application. For complete API documentation, see the [`Plugin`](api/appkit/Class.Plugin.md) class reference. -## Built-in Plugins +## Built-in plugins -### Server Plugin +### Server plugin Provides HTTP server capabilities with development and production modes. @@ -20,9 +20,9 @@ Provides HTTP server capabilities with development and production modes. - Static file serving for production - Remote tunneling to deployed backends -The Server Plugin uses the deferred initialization phase to access routes from other plugins. +The Server plugin uses the deferred initialization phase to access routes from other plugins. -### Analytics Plugin +### Analytics plugin Enables SQL query execution against Databricks SQL Warehouses. @@ -35,7 +35,7 @@ Enables SQL query execution against Databricks SQL Warehouses. Store SQL queries in `config/queries/` directory and use parameterized queries with the [`sql`](api/appkit/Variable.sql.md) helper for type safety. -## Using Plugins +## Using plugins Configure plugins when creating your AppKit instance: @@ -52,7 +52,7 @@ const AppKit = await createApp({ For complete configuration options, see [`createApp`](api/appkit/Function.createApp.md). -## Creating Custom Plugins +## Creating custom plugins Extend the [`Plugin`](api/appkit/Class.Plugin.md) class and export with `toPlugin()`: @@ -92,7 +92,7 @@ export const myPlugin = toPlugin( See the [`Plugin`](api/appkit/Class.Plugin.md) API reference for complete documentation. -## Plugin Phases +## Plugin phases Plugins initialize in three phases: diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index d09d9fd..9fd714d 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -185,7 +185,7 @@ const config: Config = { to: "/docs/", }, { - label: "API Reference", + label: "API reference", to: "/docs/api/", }, ], diff --git a/docs/sidebars.ts b/docs/sidebars.ts index c68b4e6..c295ed3 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -59,7 +59,7 @@ const sidebars: SidebarsConfig = { }, { type: "category", - label: "API Reference", + label: "API reference", link: { type: "doc", id: "api/index",