docs: describe plugins and high-level architecture

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
 ```
-

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

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

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).