Shopify App Scaffold Template

A comprehensive template for building Shopify apps with CRUD operations, featuring AI-powered code generation for rapid development.

Repository: https://github.com/agiprolabs/ShopifyAI-Scaffold

Architecture Overview

graph TB
    A[Shopify Store] --> B[OAuth Flow]
    B --> C[FastAPI Backend]
    C --> D[Database]
    C --> E[Shopify API Client]
    C --> F[AI Code Generator]
    F --> G[Claude API]
    C --> H[CRUD Endpoints]
    H --> I[React Frontend]
    I --> J[CRUD Components]
    I --> K[API Calls]

    subgraph "Backend Services"
        C
        D
        E
        F
        H
    end

    subgraph "Frontend"
        I
        J
        K
    end

Loading

Features

• Full-Stack Template: FastAPI backend with React frontend
• Shopify Integration: OAuth authentication, webhooks, API client
• CRUD Operations: Generic models and endpoints for easy extension
• AI Code Generation: Use Claude API to generate CRUD code snippets
• Docker Support: Containerized development environment
• Database: PostgreSQL with SQLAlchemy and Alembic migrations

Why AI Integration Makes Sense

Integrating an AI API like Claude for generating CRUD code snippets provides several key benefits:

1. Accelerated Development: AI can generate boilerplate code instantly, reducing setup time from hours to minutes
2. Consistency: Ensures uniform code patterns across different CRUD operations
3. Error Reduction: AI-generated code follows best practices and reduces human error
4. Focus on Business Logic: Developers can concentrate on unique features rather than repetitive CRUD implementation
5. Rapid Prototyping: Quickly test ideas by generating functional code snippets
6. Learning Aid: New developers can learn patterns from AI-generated, well-structured code
7. Scalability: Easily generate CRUD for new entities as the app grows

Quick Start

Option 1: Automated Setup (Recommended)

# Use the automated kickoff script
export CLAUDE_API_KEY="your_claude_api_key_here"
./kickoff.sh my-awesome-app

# Or without API key (you'll be prompted to add it later)
./kickoff.sh my-awesome-app

Option 2: Manual Setup

1. Install Shopify CLI: npm install -g @shopify/cli
2. Clone from GitHub: git clone https://github.com/agiprolabs/ShopifyAI-Scaffold.git my-shopify-app
3. Change to project directory: cd my-shopify-app
4. Run shopify app dev to start development with ngrok tunnel
5. Access your app through the Shopify Admin
6. Use the AI code generator to create CRUD operations

🤖 AI-Assisted Development

This scaffold includes comprehensive AI agent instructions for accelerated development:

For Claude Code / Cursor

• .cursorrules: Instructions for AI coding assistants
• PRD Template: Generate comprehensive product requirements
• AI Code Generator: Built-in CRUD code generation

For KiloCode

• .kilocode-instructions.md: Agentic workflow protocols
• Automated kickoff: kickoff.sh script for project initialization
• PRD generation: Template and AI prompts for requirements

PRD Generation Workflow

1. Generate PRD: Use prd-template.md with AI assistance
2. Break down features: Identify CRUD operations for AI generation
3. Implement with AI: Use scaffold's AI generator for consistent code
4. Test & iterate: Deploy and refine using Shopify CLI

Example PRD Generation Prompt:

Generate a PRD for a Shopify inventory management app using the provided template.
Focus on CRUD operations that can be AI-generated, with specific user stories and acceptance criteria.

Step-by-Step Guide

1. Install Shopify CLI

npm install -g @shopify/cli

2. Setup Development Environment

# Clone from GitHub
git clone https://github.com/agiprolabs/ShopifyAI-Scaffold.git my-shopify-app
cd my-shopify-app

# Login to Shopify
shopify auth login

# Create a new app (or use existing)
shopify app create

# Copy environment template
cp .env.template .env

# Edit .env with your Claude API key
# CLAUDE_API_KEY=your_claude_api_key

# Start development server with ngrok tunnel
shopify app dev

The CLI will:

• Start your backend and frontend servers
• Create ngrok tunnel for OAuth callbacks
• Open your app in the browser
• Handle app registration and configuration automatically

3. Generate CRUD Operations with AI

Use the built-in AI code generator:

curl -X POST http://localhost:8000/api/ai/generate-crud \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "Product",
    "fields": ["name", "price", "description"],
    "operations": ["create", "read", "update", "delete"]
  }'

The AI will generate:

• Database models
• API endpoints
• Frontend components
• Integration code

4. Implement Generated Code

1. Add the generated models to backend/app/db/models.py
2. Create new router in backend/app/api/
3. Include the router in main.py
4. Add frontend components to React app
5. Test the CRUD operations

5. Deploy

# Deploy to Shopify
shopify app deploy

# Or for staging
shopify app deploy --source-control-url=<your-repo-url>

Project Structure

shopify-app-scaffold/
├── shopify.app.toml         # Shopify CLI configuration
├── .cursorrules            # Claude Code instructions
├── .kilocode-instructions.md # KiloCode agent protocols
├── prd-template.md         # PRD generation template
├── kickoff.sh              # Automated project setup script
├── web/                    # App code (Shopify CLI requirement)
│   ├── backend/            # FastAPI backend
│   │   ├── app/
│   │   │   ├── api/        # API routers (CRUD, Shopify, AI)
│   │   │   ├── core/       # Configuration
│   │   │   ├── db/         # Database models & session
│   │   │   └── services/   # Business logic
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   └── frontend/           # React + TypeScript frontend
│       ├── src/
│       │   ├── components/ # React components
│       │   └── App.tsx     # Main app
│       ├── package.json
│       └── Dockerfile
├── docker/                 # Database setup
│   └── init-db.sql
├── .env.template           # Environment variables
└── README.md

API Endpoints

• POST /api/shopify/install - Start OAuth flow
• GET /api/shopify/callback - OAuth callback
• POST /api/ai/generate-crud - Generate CRUD code
• GET /api/{entity} - List entities
• POST /api/{entity} - Create entity
• PUT /api/{entity}/{id} - Update entity
• DELETE /api/{entity}/{id} - Delete entity

Environment Variables

# AI (Claude)
CLAUDE_API_KEY=your_claude_api_key

# Database (optional - defaults to SQLite for development)
DATABASE_URL=sqlite:///./shopify_app.db

# Security
SECRET_KEY=your_secret_key
ENCRYPTION_KEY=your_32byte_encryption_key

Note: Shopify CLI handles Shopify API credentials automatically through the app configuration.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Test thoroughly
5. Submit a pull request

License

MIT License