diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 22788cb..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. @@ -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..b29fbbc --- /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/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 20fca75..9c1c838 100644 --- a/docs/docs/development/index.mdx +++ b/docs/docs/development/index.mdx @@ -16,8 +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 new file mode 100644 index 0000000..f9159cb --- /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). 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",