enterprise-app-tutorial - GitLite

KO | EN

gitlite — search

#sql #php #developer-tools #awesome #containers #agent #mcp #awesome-list #java #pytorch

enterprise-app-tutorial

(★ 9)

Hands-on tutorial: build a production-style AI support app with Superblocks, Databricks Unity AI Gateway, and AWS.

File Explorer

ZIP Download

- - superblocks-sync.yml
- - AI_Chadwick_Coffee_Table.pdf
  - AI_Extra_Deep_Mid_Century_Expandable_Dining_Table.pdf
  - AI_Foundry_Side_Table.pdf
  - AI_Frame_Dining_Table-72in.pdf
  - AI_Georgia_74in_Dining_Table.pdf
  - products_silver.csv
- - Image 1 - Integrations.gif
  - Image 2 - Demo Chat.gif
  - Image 3 - Demo Analytics.gif
  - Image 4 - main diagram.jpg
  - Image 5 - Animated Diagram.gif
  - Image 6 - Cloud Prem.jpg
- - amazon s3.webp
  - Amazon-S3-icon.jpg
  - assembly-assistant-architecture.pptx
  - lakehouse-lockup-full-color (3).svg
  - lakehouse-lockup-full-color-container (1).svg
  - lakehouse-lockup-full-color-white (2).svg
  - lakehouse-lockup-full-color-white-container (1).svg
  - meta llama.png
  - openai-chatgpt-logo-icon-free-png.webp
  - openai.svg
  - PDF_file_icon.svg.webp
  - qwen icon.webp
  - slack icon.png
  - Slack-logo.png
  - superblocks.avif
  - unity-ai-gateway-lockup-full-color-container.svg
  - unity-ai-gateway-lockup-full-color-white-container.svg
  - unity-catalog-lockup-full-color (1).svg
  - unity-catalog-lockup-full-color-white (1).svg
- - Part 1 - Data Foundations.ipynb
- - superblocks.json
- - App.tsx
  - index.css
  - root.tsx
  - router.tsx
- - .gitkeep
  - config.ts
  - index.ts
- components.json
- css.d.ts
- eslint.config.js
- package-lock.json
- package.json
- tsconfig.client.json
- tsconfig.eslint.json
- tsconfig.json
- tsconfig.server.json
- vite.config.ts
.gitignore
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> A hands-on tutorial for building a production-style AI support app on
> [Superblocks](https://www.superblocks.com/), deployed inside your own AWS
> account, using **Databricks Unity AI Gateway**, **Amazon S3**, and **Slack**.

**Assembly Support** is an AI-powered customer support assistant for flat-pack
furniture. A customer picks a product, asks a question ("What tools do I need?",
"Walk me through the assembly steps"), and gets a grounded answer drawn from the
product's parsed manual. Along the way it demonstrates four enterprise
integration patterns you can reuse in your own apps:

- **Route one question to multiple LLMs** (open-source *and* proprietary) through
  Databricks Unity AI Gateway, and compare **latency, token usage, and cost**
  side by side.
- **Ground answers in your own data** — questions run against a **Delta table**
  of pre-parsed manual content via a Databricks **SQL warehouse**, not the raw
  PDFs.
- **Preview source documents** with **presigned Amazon S3 URLs**.
- **Escalate to a human** by posting a formatted message to **Slack**.

![Assembly Support architecture — seven numbered actions](https://raw.githubusercontent.com/viktoriasemaan/enterprise-app-tutorial/main/resources/demo/Image%205%20-%20Animated%20Diagram.gif)

The app is a full-stack Superblocks application: a React front end and a set of
typed server-side APIs. Superblocks is the **orchestration hub** — it talks to
every integration, and **all credentials live inside the Superblocks platform**,
so no secrets ever touch the repository.

### The seven actions

The numbers on the diagram trace a single customer question from start to
finish, plus the two support side-branches.

| # | Action | From → To | What happens | Code |
|---|---|---|---|---|
| **1** | **Ask a question** | Customer → Superblocks App | The customer selects a product and asks an assembly question in the chat UI (single model, or two models side-by-side to compare). | `client/pages/Page1` |
| **2** | **Retrieve context · RAG** | Superblocks → Databricks Lakehouse | Superblocks queries a **Delta table** of pre-parsed manual content through the Databricks **SQL Warehouse** — the answer is grounded in your data, not read from the raw PDF at query time. | `chat-with-document.ts`, `list-documents.ts` |
| **3** | **Grounded prompt** | Superblocks → Unity AI Gateway | The retrieved context is assembled into a grounded system prompt and sent to the **Unity AI Gateway** — one endpoint, governed model routing, usage logging. | `chat-with-document.ts` |
| **4** | **Route to model(s)** | Unity AI Gateway → LLMs | The Gateway routes the prompt to the selected model(s) — open-source (**Qwen**, **Llama**) or proprietary (**GPT**, plus Claude, Gemini, DBRX, Kimi…) — and returns the reply with **latency & token metrics**. | `ModelSelector`, `chat-with-document.ts` |
| **5** | **PDF preview** | Superblocks → Amazon S3 | When the customer clicks *Preview*, Superblocks asks **Amazon S3** for the source manual. | `get-document-url.ts` |
| **6** | **Presigned URL** | Amazon S3 → PDF preview | S3 returns a **presigned URL**, which the app renders in an in-app PDF viewer — no bucket credentials exposed to the browser. | `get-document-url.ts`, `SupportSidebar` |
| **7** | **Escalate to agent** | Superblocks → Slack | If the AI can't resolve the issue, the customer escalates and Superblocks posts a formatted conversation summary to **Slack** for a human agent. | `escalate-to-slack.ts` |

> **Actions 1–4** are the RAG chat path (the main flow). **Actions 5–6** (PDF
> preview) and **action 7** (Slack escalation) are independent side-branches that
> Superblocks orchestrates directly.

**Not shown on the diagram — the Analytics page:** every request in action 4 is
logged by the Gateway to the `system.ai_gateway.usage` system tables. The
Analytics dashboard (`get-gateway-metrics.ts`) reads those tables to compare
models on latency, tokens, and success rate.

---

[![Watch the tutorial on YouTube](https://img.youtube.com/vi/HyDFTUeSjRs/maxresdefault.jpg)](https://youtu.be/HyDFTUeSjRs)

## Table of contents

1. [See it in action](#see-it-in-action)
2. [How the integrations work](#how-the-integrations-work)
3. [Why Databricks Unity AI Gateway](#why-databricks-unity-ai-gateway)
4. [Runs inside your own AWS account](#runs-inside-your-own-aws-account)
5. [Governance and security](#governance-and-security)
6. [Tech stack](#tech-stack)
7. [Setup & tutorial](#setup--tutorial)
8. [Project structure](#project-structure)
9. [Repository hygiene](#repository-hygiene)

---

## See it in action

### Demo · Ask a question and compare models side-by-side

![Demo: chatting with a product manual and comparing two models](https://raw.githubusercontent.com/viktoriasemaan/enterprise-app-tutorial/main/resources/demo/Image%202%20-%20Demo%20Chat.gif)

The core experience. Here we pick a product (**Foundry Side Table**), ask
*"Give me instructions for assembly,"* and route the **same question to two
models at once** — **Claude Opus** and **GPT** — through Databricks Unity AI
Gateway. Both answers stream in side-by-side, each annotated with **latency and
token counts** so you can compare quality *and* cost at a glance.

From the support panel on the right we then **preview the source PDF**
(served by a presigned Amazon S3 URL) and **escalate to a human agent** — the
button confirms with *"Escalated"* once the message lands in Slack.

> 💡 **Tutorial takeaway:** the answer isn't read from the PDF at query time — it
> comes from a **Delta table** of pre-parsed manual content queried through the
> Databricks SQL Warehouse. The PDF is only fetched from S3 when you click
> *Preview*. This is the retrieval-augmented (RAG) pattern in miniature.

### Demo · Watch usage analytics update from the AI Gateway

![Demo: AI Gateway analytics dashboard](https://raw.githubusercontent.com/viktoriasemaan/enterprise-app-tutorial/main/resources/demo/Image%203%20-%20Demo%20Analytics.gif)

Every request through the AI Gateway is logged to the
`system.ai_gateway.usage` system tables. The **Analytics** page reads those
tables directly to show request counts, average latency, token efficiency, and
success rate **per model** — no extra instrumentation code. This is how you turn
"which model should we use?" into a data-backed decision.

---

## How the integrations work

| Integration | Where | What it does |
|---|---|---|
| **Databricks Unity AI Gateway** | `list-documents.ts`, `chat-with-document.ts`, `get-gateway-metrics.ts` | Single REST integration used for three things: running SQL statements (list + query), invoking LLM serving endpoints, and reading usage system tables. |
| **Amazon S3** | `get-document-url.ts` | Generates presigned URLs so the browser can preview PDFs without exposing bucket credentials. |
| **Slack** | `escalate-to-slack.ts` | Posts a formatted escalation message to a support channel via `chat.postMessage`. |

Every integration is referenced **by ID only**, centralized in
[`superblocks-app/server/config.ts`](superblocks-app/server/config.ts):

```ts
export const INTEGRATIONS = {
  databricksGateway: "…", // Superblocks integration ID
  amazonS3: "…",
  slack: "…",
} as const;
```

---

## Why Databricks Unity AI Gateway

The AI Gateway is what makes the "route one question to many models" pattern
practical:

- **One endpoint, many models** — call open-source (Llama, Mixtral, DBRX, Qwen)
  and proprietary (Claude, GPT, Gemini) models through the same API shape, with
  no per-provider SDKs.
- **Built-in governance & observability** — every request is logged to
  `system.ai_gateway.usage`, which is exactly what powers the analytics
  dashboard (latency, tokens, cost, success rate) with no extra instrumentation.
- **Governance works at two layers** — Superblocks governs the app and its
  deployment: permissions, audit logs, a security scan at publish, and hosting
  inside your own AWS account. Databricks Unity Catalog governs the data.
  Together they cover it end to end.

This is the core teaching point of the demo: **swapping the model is a one-line
change, and the cost/latency trade-offs become immediately visible.**

## Why Superblocks

Superblocks is the platform the app runs on. It orchestrates every integration,
hosts the app inside your own AWS account, enforces permissions and audit, and
scans for vulnerabilities at publish. Databricks powers the data and model
layer. Superblocks makes it a governed, deployed enterprise app.

---

## Runs inside your own AWS account

The app doesn't run on someone else's servers. Superblocks deploys it inside
your own AWS account, so your data and AI processing never leave your
environment. The app inherits your network boundaries, identity, encryption, and
audit controls, and users sign in through your SSO. That's the difference between
a prototype and something your security team will actually approve.

![Superblocks Cloud Prem deployment inside your own AWS account](https://raw.githubusercontent.com/viktoriasemaan/enterprise-app-tutorial/main/resources/demo/Image%206%20-%20Cloud%20Prem.jpg)

---

## Governance and security

- **Users see only what they're allowed to see.** Superblocks honors the
  permissions set in Databricks through its external OAuth, so a support agent
  and an admin querying the same app get back only the data their role permits.
- **Every action is logged.** Audit logs record who built what, what data it
  touched, and when.
- **Vulnerable code doesn't ship.** At publish, Superblocks runs a swarm of
  security agents that scan the app for vulnerabilities and business logic flaws
  before it's promoted.
- **Secrets live in the platform.** The app references integrations by ID, and
  no credentials ever touch the repo.

---

## Tech stack

- **Superblocks** full-stack app framework (`@superblocksteam/sdk-api`, `@superblocksteam/library`)
- **React 18** + **React Router 7** + **Vite 6**
- **Tailwind CSS 4** + shadcn/ui components
- **Recharts** for the analytics visualizations
- **Zod** for end-to-end typed, validated API inputs/outputs
- **TypeScript** throughout (typed `useApi` inference from the server registry)

---

## Setup & tutorial

### Prerequisites

- A **Superblocks** account
- A **Databricks** workspace with:
  - Unity AI Gateway serving endpoints enabled
  - A SQL warehouse
  - Permission to create a Unity Catalog, schema, Volume, and Delta tables
    (the [data-foundations notebook](#3-prepare-your-data-in-databricks) builds
    the Volume and the `products_silver` Delta table for you)
- An **Amazon S3** bucket for PDF previews
- A **Slack** workspace + bot with `chat:write`

### 1. Upload the sample PDFs to Amazon S3

The app previews source manuals with **presigned Amazon S3 URLs** (actions 5–6).
Upload the sample PDFs in [`resources/assembly-docs/`](resources/assembly-docs/)
to your S3 bucket so the *Preview* button has something to serve.

- Upload the `.pdf` files (not the CSV) to the bucket you'll use for previews.
- The S3 object keys must be the **bare filenames** (e.g.
  `AI_Foundry_Side_Table.pdf`) — they must match the filenames the app lists
  from the Databricks Volume in the next step.
- Note your bucket name; you'll set it in `superblocks-app/server/config.ts` (`S3.bucket`).

> 💡 Swap in your own PDFs here (and in the Databricks Volume) to ground the app
> in your own products.

### 2. Prepare your data in Databricks

Run the included notebook
[`resources/python notebook/Part 1 - Data Foundations.ipynb`](resources/python%20notebook/Part%201%20-%20Data%20Foundations.ipynb)
in your Databricks workspace. Using **Databricks AI Functions**
(`ai_parse_document`, `ai_query`, `ai_extract`, `ai_classify`), it builds the
entire data foundation the app depends on — you don't hand-build any tables.

1. **Copy the notebook into Databricks.** Import this repo (or at least the
   notebook and the `resources/assembly-docs/` folder with the sample PDFs +
   `products_silver.csv`) into your workspace via **Workspace → Import** or a Git
   folder, so the notebook can read the PDFs and CSV from its parent
   `resources/` folder.
2. **Set the catalog, schema, and table names.** In the config cell at the top
   of the notebook, set `catalog`, `schema`, and `volume`. These **must match**
   `superblocks-app/server/config.ts` (`DATABRICKS.catalog`, `DATABRICKS.schema`,
   `DATABRICKS.productsTable`, and `DATABRICKS.volumePath`). The defaults are
   `furniture_catalog` / `docs` / `assembly_docs` in both places — if you change
   them, change them in both.
3. **Run all cells.** The notebook will:
   - Create the Unity Catalog, schema, and **Volume**, then copy the sample PDFs
     and `products_silver.csv` into the Volume.
   - Parse the PDFs into a raw Delta table and build the structured
     **`products_silver`** Delta table (`manual_id` is the PDF filename without
     the `.pdf` extension).
   - Merge the pre-processed `products_silver.csv` records so you get a larger
     catalog without parsing every PDF yourself.

### 3. Add the integrations in Superblocks

![Demo: adding integrations in Superblocks](https://raw.githubusercontent.com/viktoriasemaan/enterprise-app-tutorial/main/resources/demo/Image%201%20-%20Integrations.gif)

On the Superblocks **Integrations** page, add the three integrations this app
uses. Click **+ Add Integration** to open the catalog (Superblocks ships
connectors for dozens more — databases, SaaS APIs, cloud storage — so you can
extend this app well beyond the tutorial).

| Integration | Type | Credentials you provide |
|---|---|---|
| Databricks Unity AI Gateway | REST API | Workspace host + Databricks token |
| Amazon S3 | S3 | AWS access key / secret (or role) |
| Slack | Slack | Bot token (`xoxb-…`) |

> 🔒 These credentials are stored **in Superblocks**, never in this repo.

Then edit [`superblocks-app/server/config.ts`](superblocks-app/server/config.ts)
and replace every value with your own — the integration IDs from above, your
Databricks warehouse ID,
catalog/schema/table, Volume path, S3 bucket, and Slack channel ID. This is the
**only** file you need to change to point the app at your environment, and the
catalog/schema/table must match what you set in the notebook (step 2).

### 4. Sync the repo to Superblocks and deploy

Pushes to `main` are synced to Superblocks automatically via
[`.github/workflows/superblocks-sync.yml`](.github/workflows/superblocks-sync.yml),
which uses the `SUPERBLOCKS_TOKEN` repository secret. Set the `id` in
[`superblocks-app/.superblocks/superblocks.json`](superblocks-app/.superblocks/superblocks.json)
to your own Superblocks application ID (it ships as `<YOUR_SUPERBLOCKS_APP_ID>`)
so the sync targets your app. Once the repo is synced, open the app in
Superblocks to review it, play with the chat and analytics, and then **deploy it
from Superblocks**.

> The chat model picker is driven by the serving endpoints available in your own
> Databricks workspace. To change which models appear, edit the `MODELS` list in
> [`superblocks-app/client/components/ModelSelector/index.tsx`](superblocks-app/client/components/ModelSelector/index.tsx)
> (endpoint IDs must start with `databricks-`).

---

## Project structure

```
README.md                       # This tutorial
resources/                      # Tutorial assets (not part of the app build)
  python notebook/
    Part 1 - Data Foundations.ipynb  # Builds the catalog, Volume & products_silver table
  assembly-docs/                # Sample PDFs + products_silver.csv (source data)
  demo/                         # Screenshots & GIFs used in this README
superblocks-app/                # ← the Superblocks application (synced to Superblocks)
  server/
    config.ts                   # ← all integration IDs & resource names (edit this)
    apis/
      index.ts                  # API registry (source of truth for typed clients)
      documents/
        list-documents.ts       # List PDFs from the Unity Catalog Volume
        chat-with-document.ts   # Query Delta table + call AI Gateway model
        get-document-url.ts     # Presigned S3 URL for PDF preview
      support/
        escalate-to-slack.ts    # Post escalation to Slack
      analytics/
        get-gateway-metrics.ts  # Aggregate AI Gateway usage system tables
  client/
    pages/
      Page1/                    # Main chat experience (single + compare modes)
      Analytics/                # AI Gateway analytics dashboard
    components/                 # ChatArea, ComparisonChat, ModelSelector, etc.
    hooks/                      # Typed useApi / useApiData wrappers
  package.json                  # App dependencies (run npm here)
.github/workflows/
  superblocks-sync.yml          # Syncs superblocks-app/ to Superblocks on push to main
```

---

## Repository hygiene

This repo is safe to publish:

- **No credentials in the code.** All secrets live in the Superblocks platform;
  the app references integrations by ID only.
- **Input validation.** User-supplied `model` and `documentKey` values are
  constrained with Zod (`model` must match `databricks-*`; `documentKey` must be
  a bare `.pdf` filename) to prevent path traversal into other Databricks
  endpoints or arbitrary S3 objects. The analytics `days` parameter is bounded.
- **`.gitignore`** excludes `.env`, `.npmrc`, and `*.pem`.

The identifiers in `superblocks-app/server/config.ts` are shipped as
`<YOUR_...>` placeholders — replace them with your own (warehouse ID, integration
IDs, bucket name, catalog/schema, Slack channel). Even when filled in they are
**not secrets**: they're useless without the underlying credentials, which live
in the Superblocks platform, never in this repo.

---