databricks · pkosiec · Jan 15, 2026 · Jan 13, 2026 · Jan 15, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<MyPluginConfig> {
+  name = "myPlugin";
+  envVars = ["MY_API_KEY"];
+
+  async setup() {
+    // Initialize your plugin
+  }
+
+  async shutdown() {
+    // Clean up resources
+  }
+}
+
+export const myPlugin = toPlugin<typeof MyPlugin, MyPluginConfig, "myPlugin">(
+  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
@@ -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
@@ -59,7 +59,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: "category",
-      label: "API Reference",
+      label: "API reference",
       link: {
         type: "doc",
         id: "api/index",