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:
```javascript
{
  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