shopify-ai-backup/IMPLEMENTATION_NOTES.md

Shopify AI App Builder - Implementation Notes

Overview

This document describes the recent updates to the Shopify AI App Builder to improve the user experience and implement a plan-first workflow.

Key Changes

1. New Apps List Page (/apps)

• File: chat/public/apps.html
• Purpose: Default landing page for authenticated users
• Features:
  • Grid view of all user's Shopify app projects
  • Search functionality to filter apps
  • Create new app button
  • App cards showing:
    • App name/title
    • Model used
    • Status (Ready/Building)
    • Creation date
    • Quick actions (Open, Delete)
  • Clicking an app navigates to /builder?session={sessionId}

2. Enhanced Builder Page (/builder)

• File: chat/public/builder.html
• Changes:
  • Removed "New Project" button
  • Removed session list from sidebar (single-app focus)
  • Added Build Mode indicator showing current phase:
    • 📋 Planning - AI creates a detailed plan
    • 🔨 Building - AI implements the approved plan
  • Added "Approve & Build" button for plan approval
  • Updated design with brand accent color scheme (#008060)
  • URL parameter support: ?session={id} to load specific app

3. Editable System Prompt

• File: chat/public/shopify-builder-prompt.txt
• Purpose: Contains the system prompt for Shopify app development
• Features:
  • Loaded dynamically by builder.html
  • Can be edited without modifying code
  • Falls back to default if file not found
  • Defines app structure, requirements, and best practices

4. Plan Mode Workflow

The builder now follows a two-phase workflow:

Phase 1: Planning (Default)

• User describes the app they want to build
• AI creates a detailed plan including:
  • Feature outline
  • Required Shopify APIs and webhooks
  • Data models and schema
  • UI components (Polaris-based)
  • Authentication approach (App Bridge)
  • Implementation roadmap
• User can refine the plan through conversation
• "Approve & Build" button appears after initial plan

Phase 2: Building

• User clicks "Approve & Build"
• AI receives approval message
• Switches to build mode (🔨 icon)
• Implements the approved plan
• Creates all necessary files and code

5. Design Improvements

• Color Scheme: Shopify green (#008060) throughout
• Typography: Space Grotesk for headings, Inter for body
• Icons: Text-based monochrome icons (SH, PLAN, BUILD, BOX, TERM, CLOSE, HOME, etc.)
• Cards: Clean white cards with subtle shadows
• Gradients: Professional green gradients on buttons
• Responsive: Works on mobile and desktop

Server Changes

New Route

• GET /apps → Serves the apps list page

Updated Prompt Loading

• System prompt loaded from /chat/shopify-builder-prompt.txt
• Served via existing /chat/* route handler

User Flow

New User Journey

1. User visits home page (/)
2. Clicks "Start Building Free" → redirected to /apps
3. Clicks "Create New App" → redirected to /builder
4. Describes app in input field
5. AI creates detailed plan
6. User reviews and refines plan
7. User clicks "Approve & Build"
8. AI implements the complete app
9. User can export as ZIP or push to GitHub

Returning User Journey

1. User visits /apps
2. Sees list of all their apps
3. Clicks on an app card
4. Redirected to /builder?session={id}
5. Continues working on that specific app

Technical Details

Session Management

• Sessions tied to user ID (from localStorage or cookie)
• Each session = one app project
• Session state includes messages, model, CLI, and metadata
• Builder page loads specific session via URL parameter

Build Mode State

Managed in builderState object:

{
  mode: 'plan' | 'build',
  planApproved: false,
  shopifyPrompt: '...'
}

Message Interception

• First message automatically includes system prompt
• Plan mode instruction added to guide AI
• Build mode instruction sent when plan approved
• UI updates based on mode changes

Files Modified/Created

New Files

• chat/public/apps.html - Apps list page
• chat/public/shopify-builder-prompt.txt - Editable system prompt

Modified Files

• chat/public/builder.html - Enhanced builder interface
• chat/public/home.html - Updated links to point to /apps
• chat/server.js - Added /apps route, Admin endpoints

Unchanged Files

• chat/public/app.js - Session/message handling (reused)
• chat/public/styles.css - Base styles

Customization

Editing the System Prompt

Edit chat/public/shopify-builder-prompt.txt to customize:

• App structure and organization
• Required features and components
• Best practices and guidelines
• Technology stack preferences (Node, Remix, App Bridge)
• Deployment targets

Styling

Builder-specific styles are in <style> tags in builder.html:

• CSS variables for colors (--brand-accent, etc.)
• Component-specific styles
• Responsive breakpoints

Templates

Quick-start templates in builder.html can be edited:

• Product Discount App
• Inventory Sync App
• Review Collector App
• Custom Checkout App

Future Enhancements

Potential improvements:

1. App preview/screenshots in apps list
2. Collaborative editing (multiple users)
3. Version history for apps
4. Template marketplace
5. Direct deploy to Shopify CLI
6. Real-time collaboration
7. App analytics and metrics

Testing

To test the implementation:

1. Start the server: cd chat && node server.js
2. Visit http://localhost:4000/apps
3. Create a new app
4. Verify plan mode workflow
5. Approve plan and verify build mode
6. Check app list shows the new app
7. Open existing app from list

Notes

• Session list hidden in builder (CSS: display: none !important)
• "New chat" button also hidden in builder
• All styling uses brand accent theme
• Plan/build mode persists during session
• Apps page is now the main entry point for authenticated users