AOV AI Agent

A React-based AI chat assistant library for Shopify applications, providing a seamless AI-powered support experience.

🏗️ Project Structure

This project follows Avada's monorepo structure as defined in CLAUDE.md:

aov-ai-agent/
├── packages/
│   └── ui/                  # Frontend React UI package
│       ├── src/
│       │   ├── components/  # Reusable React components
│       │   ├── contexts/    # React contexts
│       │   ├── hooks/       # Custom React hooks
│       │   ├── services/    # API services
│       │   ├── utils/       # Utility functions
│       │   └── index.js     # Main export
│       ├── .babelrc         # Babel config for UI
│       ├── .gitignore       # UI specific ignores
│       ├── package.json     # UI package metadata
│       └── README.md        # UI package documentation
├── dist/
│   └── agent-ui/            # Compiled UI output
├── types/                   # TypeScript type definitions
├── .babelrc                 # Root Babel configuration
├── package.json             # Root package configuration (monorepo)
└── CLAUDE.md                # Coding standards and guidelines

📦 Installation

npm install aov-agent

Install peer dependencies:

npm install react react-dom react-redux @shopify/polaris @shopify/polaris-icons

🚀 Usage

Import UI Components

// ✅ Import from agent-ui subpath
import { Assistant } from "aov-agent/agent-ui";

function App() {
  return (
    <Assistant
      shop={{
        id: "shop-123",
        showAgentChat: true,
      }}
      apiUrl="/api/chat/message"
    />
  );
}

Required Peer Dependencies

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "react-redux": "^9.2.0",
  "@shopify/polaris": "^13.9.5",
  "@shopify/polaris-icons": "^9.3.1"
}

✨ Features

• AI-Powered Chat Interface: Streaming chat with AI assistant
• Thread Management: Create, edit, delete, and switch between chat threads
• AI Suggestions: Contextual suggestions for quick actions
• Tool Execution: Support for AI tool calls and results
• Markdown Support: Rich text formatting with math equations (KaTeX)
• Resizable Modal: Draggable and resizable chat window
• Shopify Polaris UI: Built with Shopify's design system
• PropTypes Validation: Runtime type checking for components
• SSE Streaming: Real-time streaming responses

🛠️ Development

Build

npm run build

Compiles source code from packages/ui/src/ to dist/agent-ui/ using Babel.

Watch Mode

npm run build:watch

Automatically rebuilds on file changes.

📚 Documentation

See CLAUDE.md for:

• Coding standards and conventions
• Project structure guidelines
• React component patterns
• API integration guidelines
• Error handling best practices

See packages/ui/README.md for:

• Detailed component documentation
• Hook usage examples
• Context API reference

🏛️ Architecture

Components

• Assistant: Main container with provider wrappers
• AssistantWidget: Chat UI with thread list and composer
• ThreadProvider: Manages thread state and streaming runtime
• ResizableModal: Draggable modal container

Contexts

• AgentContext: Agent visibility state
• SuggestionsContext: AI suggestions management
• ThreadContext: Thread list and CRUD operations

Hooks

• useFetchApi: Data fetching with pagination
• useStreamApi: SSE streaming API calls
• useThreadAutoScrollFix: Auto-scroll behavior

🎨 Tech Stack

• React 18.2
• Shopify Polaris 13.9
• @assistant-ui/react
• Redux for state management
• KaTeX for math rendering
• PropTypes for validation

📝 Code Standards

This project follows Avada's coding standards:

• ✅ ES6+ features (import/export, async/await, arrow functions)
• ✅ camelCase for functions/variables
• ✅ PascalCase for components/classes
• ✅ JSDoc documentation
• ✅ PropTypes validation
• ✅ Early returns (no nested conditions)
• ✅ Structured error handling

🤝 Contributing

Follow the guidelines in CLAUDE.md for:

• Naming conventions
• Function design patterns
• React component structure
• Documentation requirements
• Error handling patterns

📦 Publishing to NPM

This package is designed to be published to NPM for use in other projects.

Build and Publish

# 1. Install dependencies
npm install

# 2. Clean and build (works on Windows & Linux)
npm run clean
npm run build

# 3. Verify build output
# On Linux/Mac:
ls -la dist/agent-ui/
# On Windows:
dir dist\agent-ui\

# 4. Test locally (optional)
npm link

# 5. Publish to NPM
npm publish

Note: The clean script uses rimraf which works cross-platform (Windows, Linux, Mac).

Package Structure

When published, the package structure will be:

aov-agent/
├── dist/
│   └── agent-ui/           # UI components
│       ├── components/
│       ├── contexts/
│       ├── hooks/
│       ├── services/
│       ├── utils/
│       └── index.js
└── package.json

Import Paths

// UI Components
import { Assistant } from "aov-agent/agent-ui";

// Future packages (coming soon)
// import { ... } from 'aov-agent/assets';
// import { ... } from 'aov-agent/functions';

📦 Monorepo Structure

This is a monorepo containing multiple packages:

• packages/ui/ - UI components (published as aov-agent/agent-ui)
• packages/assets/ - Frontend assets (coming soon)
• packages/functions/ - Backend functions (coming soon)

Each package can be developed, built, and tested independently.

📄 License

ISC

🔗 Links

• Repository: https://gitlab.com/avada/aov-ai-agent
• Issues: https://gitlab.com/avada/aov-ai-agent/issues
• NPM: https://www.npmjs.com/package/aov-agent