Shopify Analytics AI

An AI-powered analytics application that connects to Shopify stores and allows users to ask natural language questions about their store data.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Frontend     │────▶│   Rails API     │────▶│   AI Service    │
│   (Nginx/HTML)  │     │   (Gateway)     │     │   (FastAPI)     │
│   Port: 8080    │     │   Port: 3000    │     │   Port: 8000    │
└─────────────────┘     └────────┬────────┘     └────────┬────────┘
                                 │                       │
                                 ▼                       ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │   PostgreSQL    │     │   Shopify API   │
                        │   Port: 5432    │     │   + OpenAI API  │
                        └─────────────────┘     └─────────────────┘

Components

1. Frontend (Port 8080)

   • Simple HTML/CSS/JS interface
   • Shopify OAuth flow initiation
   • Question input and response display

2. Rails API (Port 3000)

   • Shopify OAuth handling
   • Request validation and routing
   • Store management and request logging

3. AI Service (Port 8000)

   • LLM-powered analytics agent
   • Intent classification
   • GraphQL query generation
   • Natural language response generation

4. PostgreSQL (Port 5432)

   • Store credentials
   • Request logs

Agent Workflow

┌──────────────────────────────────────────────────────────────────┐
│                      Analytics Agent                              │
├──────────────────────────────────────────────────────────────────┤
│  1. UNDERSTAND INTENT                                             │
│     └─▶ Classify question (inventory/sales/customers/products)   │
│                                                                   │
│  2. GENERATE QUERY                                                │
│     └─▶ Create appropriate Shopify GraphQL query                 │
│                                                                   │
│  3. EXECUTE                                                       │
│     └─▶ Fetch data from Shopify Admin API                        │
│                                                                   │
│  4. ANALYZE                                                       │
│     └─▶ Process results with LLM                                 │
│                                                                   │
│  5. RESPOND                                                       │
│     └─▶ Return human-friendly answer with confidence level       │
└──────────────────────────────────────────────────────────────────┘

Prerequisites

• Docker and Docker Compose
• Shopify Partner account with app credentials
• OpenAI API key

Required API Keys

1. Shopify OAuth Credentials (provided in .env)

   • SHOPIFY_API_KEY
   • SHOPIFY_API_SECRET

2. OpenAI API Key (you need to provide)

   • OPENAI_API_KEY
   • Get one at: https://platform.openai.com/api-keys

Quick Start

1. Clone and configure

   cd shopify
   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY

2. Start all services

   docker-compose up --build

3. Access the application

   • Frontend: http://localhost:8080
   • Rails API: http://localhost:3000
   • AI Service: http://localhost:8000

4. Connect your Shopify store

   • Enter your store domain (e.g., your-store.myshopify.com)
   • Complete OAuth authorization
   • Start asking questions!

API Endpoints

Rails API

Health Check

GET /health

Initiate OAuth

GET /auth/shopify?shop=your-store.myshopify.com

Ask Question

POST /api/v1/questions
Content-Type: application/json

{
  "store_id": "your-store.myshopify.com",
  "question": "What were my top 5 selling products last week?"
}

Response:
{
  "answer": "Based on your order data, your top 5 selling products last week were...",
  "confidence": "high",
  "intent": "sales",
  "store_id": "your-store.myshopify.com"
}

List Stores

GET /api/v1/stores

Verify Store Connection

GET /api/v1/stores/:shop_domain/verify

AI Service

Health Check

GET /health

Analyze Question

POST /analyze
Content-Type: application/json

{
  "store_id": "your-store.myshopify.com",
  "question": "How much inventory should I reorder?",
  "access_token": "shpat_xxxxx"
}

Example Questions

• "How many units of Product X will I need next month?"
• "Which products are likely to go out of stock in 7 days?"
• "What were my top 5 selling products last week?"
• "How much inventory should I reorder based on last 30 days sales?"
• "Which customers placed repeat orders in the last 90 days?"

Development

Running Individual Services

# AI Service only
cd services/ai-service
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Rails API only
cd services/rails-api
bundle install
rails db:prepare
rails server -p 3000

# Frontend only
cd services/frontend
python -m http.server 8080

Database Migrations

docker-compose exec rails-api rails db:migrate

Project Structure

shopify/
├── docker-compose.yml          # Orchestration
├── .env                        # Environment variables
├── README.md
└── services/
    ├── ai-service/             # Python FastAPI
    │   ├── Dockerfile
    │   ├── requirements.txt
    │   └── app/
    │       ├── main.py         # FastAPI app
    │       ├── config.py       # Settings
    │       ├── agents/
    │       │   └── analytics_agent.py
    │       ├── services/
    │       │   ├── llm_service.py
    │       │   └── shopify_service.py
    │       └── models/
    │           └── schemas.py
    │
    ├── rails-api/              # Ruby on Rails
    │   ├── Dockerfile
    │   ├── Gemfile
    │   ├── config/
    │   │   ├── routes.rb
    │   │   └── initializers/
    │   ├── app/
    │   │   ├── controllers/
    │   │   │   ├── auth_controller.rb
    │   │   │   └── api/v1/
    │   │   │       ├── questions_controller.rb
    │   │   │       └── stores_controller.rb
    │   │   └── models/
    │   │       ├── store.rb
    │   │       └── request_log.rb
    │   └── db/
    │       └── migrate/
    │
    └── frontend/               # Simple HTML/JS
        ├── Dockerfile
        ├── nginx.conf
        ├── index.html
        ├── styles.css
        └── app.js

Security Notes

• Access tokens are stored in PostgreSQL (encrypt in production)
• All inter-service communication is within Docker network
• CORS is configured for development (restrict in production)
• Use HTTPS in production

Troubleshooting

OAuth Redirect Issues

• Ensure your Shopify app's redirect URL is set to http://localhost:3000/auth/shopify/callback
• For production, update the HOST environment variable

AI Service Errors

• Verify your OpenAI API key is valid and has credits
• Check the AI service logs: docker-compose logs ai-service

Database Issues

• Reset database: docker-compose down -v && docker-compose up --build