Restore to commit 74e578279624c6045ca440a3459ebfa1f8d54191

2026-02-07 20:32:41 +00:00
commit ed67b7741b
252 changed files with 99814 additions and 0 deletions
--- a/IMPLEMENTATION_NOTES.md
+++ b/IMPLEMENTATION_NOTES.md
@@ -0,0 +1,193 @@
+# 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