🤖 iHeard.ai - AI Sales Assistant for Shopify

An intelligent AI-powered sales assistant widget for Shopify stores that helps customers find products, answer questions, and provide personalized recommendations.

📋 Features

• 🎯 Smart Product Recommendations - AI-powered product suggestions based on customer queries
• 💬 Real-time Chat Interface - Floating chat widget with customizable positioning
• 🎨 Fully Customizable - Admin panel to configure colors, text, position, and behavior
• 📱 Mobile Responsive - Optimized for all device sizes
• 🔌 N8N Integration - Optional integration with N8N workflows for advanced AI processing
• ⚡ Real-time Updates - Settings changes reflect immediately on the storefront
• 🛡️ Secure - Built with Shopify's security best practices

🏗️ Architecture

• Frontend: Remix with TypeScript and Shopify Polaris UI
• Backend: Node.js with Prisma ORM and SQLite database
• Theme Extension: Liquid template with vanilla JavaScript
• AI Integration: N8N webhooks with fallback processing
• Authentication: Shopify OAuth with session management

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Shopify Partner account
• Shopify CLI 3.0+

Installation

1. Clone the repository

   git clone https://github.com/SankaiAI/iheard.ai.git
   cd iheard.ai

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your Shopify app credentials

   Required values for .env:

   • SHOPIFY_API_KEY: Get from Shopify Partner Dashboard > Apps > [Your App] > App setup (Client ID)
   • SHOPIFY_SALES_ASSISTANT_WIDGET_ID: Generate a UUID at uuidgenerator.net

   Optional N8N Integration:

   • N8N_WEBHOOK_URL: Your N8N webhook URL for AI processing
   • N8N_API_KEY: N8N API key (if authentication required)

   See SETUP.md for detailed instructions on obtaining these values. See N8N_SETUP.md for complete N8N workflow setup.

4. Configure Shopify app

   cp shopify.app.example.toml shopify.app.toml
   # Edit shopify.app.toml with your app details

5. Set up the database

   npx prisma generate
   npx prisma migrate dev

6. Start development server

   shopify app dev

⚙️ Configuration

Environment Variables

Create a .env file with the following variables:

SHOPIFY_API_KEY=your_shopify_api_key_here
SHOPIFY_SALES_ASSISTANT_WIDGET_ID=your_widget_id_here

Shopify App Configuration

Update shopify.app.toml with your app details:

client_id = "your_shopify_app_client_id"
name = "ihear.ai"
application_url = "https://your-tunnel-url.trycloudflare.com"

📁 Project Structure

ihear-ai/
├── app/                          # Remix application
│   ├── routes/                   # App routes
│   │   ├── app.settings.tsx      # Admin settings page
│   │   ├── api.widget-settings.tsx # Widget settings API
│   │   └── apps.sales-assistant-api.tsx # AI chat API
│   ├── db.server.ts              # Database connection
│   └── shopify.server.ts         # Shopify authentication
├── extensions/                   # Shopify theme extensions
│   └── sales-assistant-widget/   # AI widget extension
│       ├── blocks/               # Theme blocks
│       │   └── ai_sales_assistant.liquid # Main widget
│       ├── assets/               # Static assets
│       ├── locales/              # Translations
│       └── snippets/             # Reusable snippets
├── prisma/                       # Database schema and migrations
│   ├── schema.prisma             # Database schema
│   └── migrations/               # Database migrations
└── services/                     # External services
    └── n8n.service.ts            # N8N integration

🎛️ Admin Panel Features

Widget Configuration

• Enable/Disable - Toggle widget on/off across the store
• Position Settings - 6 positioning options (corners and center sides)
• Customization - Button text, chat title, welcome message, placeholder text
• Color Picker - Fully functional color customization
• Live Preview - See changes in real-time

AI Workflow Configuration

• Default Workflow - Use the developer's pre-configured AI assistant with product recommendations
• Custom N8N Workflow - Configure your own N8N webhook URL for custom AI processing
• Dynamic Switching - Easily switch between default and custom workflows
• Fallback Protection - Automatic fallback to local processing if webhooks fail

Settings Auto-Sync

• Changes in admin panel update the storefront within 5 seconds
• Database persistence ensures settings survive server restarts
• Fallback to default settings if API is unavailable

🔧 Development

Database Management

# Generate Prisma client
npx prisma generate

# Create and apply migrations
npx prisma migrate dev --name description

# Reset database (development only)
npx prisma migrate reset

# View database in browser
npx prisma studio

Local Development Workflow

⚠️ Important for Local Development: Every time you restart shopify app dev, you must update the App Proxy URL in your Shopify Partner Dashboard because the tunnel URL changes.

Quick Steps:

1. Check your new tunnel URL in shopify.app.toml → application_url
2. Update the proxy URL in Partner Dashboard → Apps → [Your App] → App setup → App proxy
3. Set proxy URL to: https://NEW-TUNNEL-URL.trycloudflare.com/api/widget-settings

Why this matters:

• The widget needs to fetch settings from your app's API
• Tunnel URLs change on each restart for security
• Without updating the proxy URL, you'll get "Failed to fetch" errors

See SETUP.md for detailed instructions on app proxy configuration.

Theme Extension Development

The widget is built as a Shopify theme extension block that can be added to any theme template. It automatically:

• Fetches configuration from the admin panel
• Applies custom styling and positioning
• Handles real-time chat interactions
• Integrates with the AI backend

API Endpoints

• GET /api/widget-settings - Fetch widget configuration
• POST /apps/sales-assistant-api - Process AI chat messages

🤖 AI Integration

Two Workflow Options

1. Default Developer Workflow

• Pre-configured AI assistant with product recommendations
• Works out-of-the-box with no additional setup
• Integrated with your store's product catalog
• Handles common customer queries automatically

2. Custom N8N Workflow

• Configure your own N8N webhook URL through the admin panel
• Advanced AI processing with full customization
• Integrate with external AI services (OpenAI, Claude, etc.)
• Custom business logic and integrations

Configuration

Admin Panel Configuration:

1. Go to App Settings → AI Workflow Configuration
2. Choose between "Use Developer's Default Workflow" or "Use My Custom N8N Workflow"
3. If using custom: Enter your N8N webhook URL (must be HTTPS)
4. Save settings - changes take effect immediately

Environment Configuration (Optional):

• Set N8N_WEBHOOK_URL in .env for a global default
• Individual stores can override this with their own webhook URLs
• Supports both shared and per-store N8N configurations

Fallback Processing

The app provides robust fallback protection:

• If custom webhook fails → Falls back to local processing
• If network issues occur → Provides helpful default responses
• Ensures chat widget always works regardless of external dependencies

🚀 Deployment

Development Deployment

The app runs in development mode with Shopify CLI:

shopify app dev

Production Deployment

For production deployment, you'll need to:

1. Set up a production server (Railway, Heroku, etc.)
2. Configure production environment variables
3. Set up a production database
4. Deploy using Shopify CLI

shopify app deploy

🔒 Security Considerations

• API Keys: Never commit .env or shopify.app.toml files
• Database: SQLite is suitable for development; use PostgreSQL for production
• CORS: Widget API includes proper CORS headers for cross-origin requests
• Authentication: All admin routes require Shopify OAuth authentication

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Shopify App Development
• Issues: Open an issue on GitHub
• Discussions: Use GitHub Discussions for questions and ideas

🙏 Acknowledgments

• Built with Shopify CLI
• UI components from Shopify Polaris
• Database ORM by Prisma
• Web framework by Remix

---

Made with ❤️ for the Shopify ecosystem