RavenDB + AI Agents Shopping Dashboard Sample

A comprehensive sample application demonstrating RavenDB integration with AI Agents for an e-commerce shopping cart scenario. This full-stack TypeScript application showcases modern database operations, AI-powered conversations, and real-time shopping features.

Overview

This sample application illustrates how to build a modern shopping platform using:

RavenDB Document Database for data persistence and AI conversations
AI Agent Integration for intelligent customer support
Real-time Shopping Cart with document-based storage
Order Management with RavenDB queries and operations
TypeScript Full-Stack architecture with shared types

Key RavenDB Features Demonstrated

🤖 AI Agent Integration

Conversation Management: AI conversations stored as RavenDB documents
RAG (Retrieval Augmented Generation): AI agent with access to product/order knowledge
Chat History: Persistent conversation threads with usage tracking
Tool Calls: AI function calling for dynamic responses

📊 Document Database Operations

CRUD Operations: Create, read, update, delete operations on documents
Document Sessions: Proper session management and change tracking
Include Queries: Efficient data loading with single round-trips
Collection Organization: Structured document collections (Orders, Products, Carts, Conversations)

🛒 Shopping Cart System

Document-Based Carts: Cart storage using RavenDB documents
Product Integration: Product catalog with RavenDB references
Real-time Updates: Live cart synchronization
User-Specific Data: Isolated cart and order data per user

Features

Order Management: View order history with RavenDB queries and document operations
Shopping Cart: Document-based cart storage with real-time RavenDB updates
AI Chat Support: Intelligent conversations powered by RavenDB AI Agents
Product Catalog: RavenDB product documents with rich metadata
Responsive Design: Modern UI works on desktop and mobile devices
Real-time Updates: Live synchronization using RavenDB sessions
Beautiful UI: Pastel yellow and green design system

RavenDB Architecture

Document Collections

RavenDB Collections:
├── Orders/              # Order documents with complex structures
├── Products/            # Product catalog with supplier references
├── Carts/              # User shopping carts with cart items
├── @conversations/     # AI conversation documents
├── CurrentChats/       # Current conversation references
└── Companies/          # User/company documents

AI Agent Configuration

The application includes a configured RavenDB AI Agent:

Agent ID: ravendb-docs-rag-agent
Knowledge Base: Product and order documentation
Capabilities: Natural language querying, order assistance, product recommendations
Integration: Seamless conversation storage and retrieval

Project Structure

ravendb-shopping-sample/
├── backend/              # Express.js + RavenDB TypeScript API
│   ├── src/
│   │   ├── index.ts         # Main server with RavenDB initialization
│   │   ├── types/           # Shared TypeScript interfaces
│   │   ├── routes/          # API endpoints with RavenDB operations
│   │   │   ├── orders.ts    # Order management with RavenDB queries
│   │   │   ├── cart.ts      # Cart operations with document storage
│   │   │   ├── chat.ts      # AI conversation integration
│   │   │   └── products.ts  # Product catalog endpoints
│   │   └── services/
│   │       └── databaseService.ts  # RavenDB DocumentStore configuration
│   ├── package.json
│   └── tsconfig.json
├── frontend/            # React TypeScript app
│   ├── src/
│   │   ├── App.tsx          # Main dashboard component
│   │   ├── components/      # React UI components
│   │   │   ├── OrdersPanel.tsx   # Order history with add-to-cart
│   │   │   ├── CartPanel.tsx     # Shopping cart management
│   │   │   └── ChatPanel.tsx     # AI chat interface
│   │   ├── services/        # API integration services
│   │   ├── types/           # Shared TypeScript interfaces
│   │   └── App.css          # Design system styles
│   └── package.json
└── .vscode/
    └── tasks.json       # Development workflow tasks

Getting Started

Prerequisites

Node.js (v16 or higher)
RavenDB Server (v6.0 or higher)
npm or yarn

RavenDB Setup

Install RavenDB: Download and install RavenDB from ravendb.net
Start RavenDB Server: Run RavenDB Management Studio (typically on port 8080)
Create Database: Create a new database for the sample application
Configure AI Agent: Set up the AI agent with your preferred configuration

Installation

Install Backend Dependencies
```
cd backend
npm install
```
Install Frontend Dependencies
```
cd frontend
npm install
```

Development

Option 1: Using VS Code Tasks (Recommended)

Open the project in VS Code
Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
Type "Tasks: Run Task"
Select "Start Both (Frontend & Backend)"

This will start both servers in watch mode with automatic reloading.

Option 2: Manual Start

Start Backend (Terminal 1):

cd backend
npm run dev

Start Frontend (Terminal 2):

cd frontend
npm start

Access the Application

Frontend: http://localhost:3000
Backend API: http://localhost:3001
Health Check: http://localhost:3001/health

API Endpoints

User Management

GET /api/userid - Get current user ID

Shopping Cart (RavenDB Operations)

GET /api/cart?userId=uid - Get user's cart from RavenDB document
POST /api/cart?userId=uid&id=product_id&qty=1 - Add item to RavenDB cart
DELETE /api/cart?userId=uid&id=product_id&qty=1 - Remove item from RavenDB cart

Order Management (RavenDB Queries)

GET /api/orders?userId=uid - Query user's orders from RavenDB
POST /api/orders/cancel?userId=uid&id=order_id - Update order status in RavenDB

AI Chat (RavenDB Conversations)

GET /api/chat?userid=uid - Get conversation from RavenDB with include
POST /api/chat?userid=uid - Send message to AI agent and store in RavenDB

Product Catalog (RavenDB Documents)

GET /api/products - Get available products from RavenDB collection

RavenDB Implementation Details

Document Storage Patterns

Cart Documents (carts/{userId})

{
  id: "carts/companies/1-A",
  userId: "companies/1-A", 
  items: [
    {
      id: "products/1-A",
      name: "Product Name",
      price: 29.99,
      quantity: 2
    }
  ]
}

Order Documents (Complex RavenDB Structure)

{
  Company: "companies/1-A",
  Employee: "employees/1-A",
  Lines: [
    {
      Product: "products/1-A",
      ProductName: "Product Name",
      Quantity: 2,
      PricePerUnit: 29.99,
      Discount: 0.1
    }
  ],
  ShipTo: { /* Address details */ },
  "@metadata": { /* RavenDB metadata */ }
}

AI Conversation Documents

{
  Agent: "ravendb-docs-rag-agent",
  Parameters: { userId: "companies/1-A", language: "english" },
  Messages: [
    { role: "user", content: "Help with my order", date: "..." },
    { role: "assistant", content: "{...}", usage: {...} }
  ],
  TotalUsage: { PromptTokens: 150, CompletionTokens: 75 }
}

RavenDB Session Management

The application demonstrates proper RavenDB session usage:

Session Per Request: Each API call opens a new session
Include Optimization: Uses .include() for efficient data loading
Change Tracking: Automatic document change detection
Bulk Operations: Efficient multi-document operations

Features Overview

Dashboard Layout

The application showcases RavenDB capabilities through a three-panel layout:

Left Panel - Order History:
- Displays orders loaded from RavenDB with complex queries
- Features "Add to Cart" buttons that update cart documents
- Shows order status with real-time RavenDB data
Top Right - Shopping Cart:
- Real-time cart backed by RavenDB documents
- Automatic cart creation and updates
- Quantity controls with immediate persistence
Bottom Right - AI Chat:
- AI conversations stored as RavenDB documents
- Conversation history with include optimization
- AI agent integration with knowledge base

AI Agent Capabilities

The RavenDB AI agent can assist with:

Order Inquiries: Query order status and details from RavenDB
Product Information: Access product catalog and recommendations
Shopping Assistance: Help with cart operations and checkout
Knowledge Base: Answer questions using stored documentation

RavenDB Features Demonstrated

Document Sessions: Proper session lifecycle management
Change Tracking: Automatic detection of document modifications
Include Queries: Efficient loading of related documents
Collection Queries: Filtering and sorting large datasets
AI Integration: Seamless AI conversation storage and retrieval
Metadata Handling: Working with RavenDB document metadata
Optimistic Concurrency: Safe concurrent document updates

Design System

Primary Colors: Pastel yellow (#fef9e7) and green (#f0f9f0)
Typography: System font stack for optimal readability
Icons: Lucide React for consistent iconography
Responsive: Mobile-first design approach

Development

VS Code Tasks

Start Both: Runs both frontend and backend in watch mode
Start Backend (Watch): Backend only with hot reload
Start Frontend (Watch): Frontend only with hot reload
Build Backend: Production build for backend
Build Frontend: Production build for frontend

Code Structure

The project follows TypeScript best practices with:

Shared type definitions
Modular component architecture
Service layer for API calls
Error handling and loading states

Technologies Used

Backend

RavenDB: NoSQL document database with AI agent support
Express.js: Web framework for API endpoints
TypeScript: Type-safe development with shared interfaces
RavenDB Client: Official Node.js client for database operations
CORS, Helmet, Compression: Security and performance middleware
Nodemon: Development hot-reload for rapid iteration

Frontend

React 18: Modern UI framework with hooks
TypeScript: Shared types with backend for consistency
Axios: HTTP client for RavenDB API integration
Lucide React: Consistent icon system
CSS3: Custom properties for theming and responsive design

RavenDB Configuration

DocumentStore: Centralized database connection management
AI Agent: Configured with knowledge base and conversation support
Indexes: Automatic and custom indexes for efficient querying
Collections: Organized document storage for different entity types

Learning Objectives

This sample demonstrates:

RavenDB Integration: How to properly initialize and use RavenDB in a Node.js application
Document Modeling: Best practices for structuring documents in a NoSQL database
Session Management: Proper lifecycle management of RavenDB sessions
AI Agent Integration: Setting up and using RavenDB's AI capabilities
TypeScript Integration: Creating type-safe applications with RavenDB
Real-time Operations: Building responsive applications with document database
Complex Queries: Advanced querying patterns and optimization techniques

Contributing

We welcome contributions to improve this RavenDB sample application:

Fork the repository
Create a feature branch (git checkout -b feature/ravendb-enhancement)
Make your changes (ensure RavenDB best practices)
Test thoroughly with RavenDB operations
Submit a pull request with detailed description

Areas for Enhancement

Additional RavenDB queries and operations
Extended AI agent capabilities
Performance optimization examples
Advanced indexing demonstrations
Sharding scenarios

Resources

License

This project is a sample application for educational and demonstration purposes. Use it to learn RavenDB concepts and build your own applications.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
.vscode		.vscode
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

RavenDB + AI Agents Shopping Dashboard Sample

Overview

Key RavenDB Features Demonstrated

🤖 AI Agent Integration

📊 Document Database Operations

🛒 Shopping Cart System

Features

RavenDB Architecture

Document Collections

AI Agent Configuration

Project Structure

Getting Started

Prerequisites

RavenDB Setup

Installation

Development

Option 1: Using VS Code Tasks (Recommended)

Option 2: Manual Start

Access the Application

API Endpoints

User Management

Shopping Cart (RavenDB Operations)

Order Management (RavenDB Queries)

AI Chat (RavenDB Conversations)

Product Catalog (RavenDB Documents)

RavenDB Implementation Details

Document Storage Patterns

RavenDB Session Management

Features Overview

Dashboard Layout

AI Agent Capabilities

RavenDB Features Demonstrated

Design System

Development

VS Code Tasks

Code Structure

Technologies Used

Backend

Frontend

RavenDB Configuration

Learning Objectives

Contributing

Areas for Enhancement

Resources

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages