Shopify Analytics Cursor Rules Template for Rails

Overview

The Cursor rules configuration is designed for building Shopify analytics apps that recommend product bundles from sales data using Ruby on Rails. This template centers on Rails API services, PostgreSQL storage, ActiveRecord patterns, and Cursor AI-powered guidance to transform raw Shopify sales into actionable bundle recommendations with safe, auditable AI interactions.

Direct answer: paste the included .cursorrules configuration block into your Rails project root to enforce stack-specific rules, structure, and guardrails for Cursor-powered bundle suggestions.

When to Use These Cursor Rules

You are building a Shopify analytics app in Ruby on Rails and want reliable, reproducible bundle recommendations from sales data.
You need framework-aligned guidelines for architecture, testing, and security that align with Rails conventions.
You must enforce data privacy, OAuth flows, and Shopify webhook validation in a production Rails environment.
You require a copyable .cursorrules block to drop into your project and a recommended Rails project structure.

Copyable .cursorrules Configuration

# Cursor Rules for Shopify Analytics Rails App
# Cursor Rules Template for Rails with Shopify integration

framework_role: "Ruby on Rails developer role for Shopify analytics apps"
framework_context: "Rails API app ingesting Shopify sales data, computing product bundles, and serving results via Rails controllers/serializers."

code_style_and_style_guides:
  - "Follow Ruby Style Guide v3.x and RuboCop Rails cops"
  - "Prefer single quotes for strings, unless interpolation is needed"
  - "Keep methods under 100 lines when possible; extract to service objects"

architecture_and_directory_rules:
  app:
    controllers: "app/controllers"
    models: "app/models"
    services: "app/services/Shopify|app/services/Analytics"
    jobs: "app/jobs"
    serializers: "app/serializers"
    workers: "app/workers"
  config: "config/initializers, environments, credentials"
  db: "db/migrate, db/schema.rb"
  lib: "lib/"

authentication_and_security_rules:
  - "Shopify OAuth 2.0 for app installation; store tokens securely in Rails credentials"
  - "Verify Shopify webhooks using HMAC and Shopify's shared secret"
  - "Do not expose tokens to the client; use server-side API calls only"
  - "Enable CSRF protection and signed/rotating session cookies for admin endpoints"

database_and_orm_patterns:
  - "PostgreSQL database"
  - "ActiveRecord models with proper associations; utilize includes to avoid N+1"
  - "Indexes on foreign keys, frequently queried columns, and bundle score caches"
  - "Migrate data with versioned migrations; avoid schema drift"

testing_and_linting_workflows:
  - "RSpec for unit and integration tests; request specs for API endpoints"
  - "FactoryBot for test data; fixtures for baseline datasets"
  - "VCR or WebMock to stub Shopify API interactions"
  - "Rubocop and Reek for linting; configure CI to fail on lint errors"
  - "GitHub Actions: run tests on PRs and on push to main"

prohibited_actions_and_anti_patterns:
  - "Do not call Shopify Admin API from client-side code"
  - "Do not log raw orders, customer data, or access tokens in logs"
  - "Do not bypass Shopify rate limits; implement exponential backoff and request queuing"
  - "Do not store long-lived secrets in source control; use Rails credentials and env vars"

Recommended Project Structure

shopify-rails-app/
├── app/
│   ├── controllers/
│   │   └── analytics_controller.rb
│   ├── models/
│   │   └── bundle.rb
│   ├── services/
│   │   ├── shopify/
│   │   │   ├── api_client.rb
│   │   │   └── webhooks_handler.rb
│   │   └── analytics/
│   │       └── bundle_recommender.rb
│   ├── serializers/
│   │   └── bundle_serializer.rb
│   └── workers/
│       └── bundle_processor_worker.rb
├── config/
│   ├── routes.rb
│   ├── initializers/
│   │   └── shopify.rb
│   └── environments/
├── db/
│   ├── migrate/
│   │   └── 20240501000000_create_bundles.rb
│   └── seeds.rb
├── lib/
│   └── tasks/
├── app/assets/
└── README.md

Core Engineering Principles

Explicit separation of concerns: models, controllers, services, and workers have distinct responsibilities.
Defensive coding: validate Shopify data, sanitize inputs, and guard against nulls in analytics.
Deterministic, observable behavior: track bundle scores with provenance and audit logs.
Security by design: store secrets securely, verify webhooks, and enforce least privilege access.
Idempotence in data processing: ensure repeated runs do not duplicate or corrupt analytics.

Code Construction Rules

Place all Shopify API calls in app/services/shopify; never in controllers.
Encapsulate the bundling algorithm in a service object (Analytics::BundleRecommender).
Use ActiveRecord scopes for reusable query patterns (e.g., recent_sales, top_bundles).
Serialize bundle results with a dedicated serializer for stable API responses.
Cache bundle recommendations per store and lesson; invalidate on sales data updates.
Follow Rails testing conventions; test service objects with unit tests and API endpoints with integration tests.

Security and Production Rules

Use TLS; shield all endpoints behind authenticated routes and IP allowlists where applicable.
Verify Shopify HMAC for all incoming webhooks and validate the shop domain.
Store secrets in Rails credentials or environment variables; rotate on schedule.
Background work should be resilient and idempotent; use retries with backoff for external calls.
Limit data exposure: only return essential fields in API responses; redact sensitive data in logs.

Testing Checklist

Unit tests for models, services, and serializers (RSpec).
Integration tests for Shopify webhook processing and OAuth flows.
End-to-end tests for bundle generation from a sample sales dataset.
CI workflows for linting, tests, and security checks on pull requests.
Load and soak tests for API endpoints under typical shop workloads.

Common Mistakes to Avoid

Mixing business logic into controllers; prefer service objects for analytics.
Ignoring Shopify rate limits and not implementing robust backoff strategies.
Storing large JSON payloads in logs or database columns without compression or privacy controls.
Hardcoding shop-specific data or tokens in code; always use credentials/env vars.

FAQ

What is the purpose of this Cursor Rules Template for a Rails Shopify analytics app?

This Cursor Rules Template provides a complete, Rails‑oriented blueprint to ingest Shopify sales data and generate product bundle recommendations using Cursor AI. It includes a ready-to-paste .cursorrules block, a Rails-friendly project structure, and stack-specific guardrails to keep AI-assisted development safe and deterministic.

Where should I paste the .cursorrules block?

Paste the copied .cursorrules block into the Rails project root as a .cursorrules file (e.g., .cursorrules) and reference it in your CI or tooling so Cursor AI applies the rules consistently during code generation and guidance.

Does this template cover Shopify OAuth and webhooks?

Yes. The rules include authentication and webhook verification guidance tailored to a Rails app, including HMAC verification, OAuth flow handling, and secure storage of tokens.

How do I customize the bundle recommendation algorithm for my store?

Adjust the Analytics::BundleRecommender service with store-specific scoring metrics, including sales recency, frequency, monetary value, and cross-sell heuristics. Use Rails models to fetch data within defined scopes and ensure caching for performance.

What testing and deployment steps are recommended?

Use RSpec for unit/integration tests, VCR/WebMock for Shopify API calls, and RuboCop for linting. Deploy with CI that runs tests on PRs, and use background workers for long-running bundle calculations in production.

Target User

Use Cases