OpenWebUI with Flow Shortcuts

A custom fork of OpenWebUI with visual shortcut cards for quickly launching Langflow functions.

⚠️ NEW: See OVERVIEW.md for comprehensive project documentation.

---

🚀 Quick Start

Start the Application

cd "OpenWebUI fork"
docker compose up -d

Access at: http://localhost:3000

Stop the Application

cd "OpenWebUI fork"
docker compose down

---

📂 Project Structure

Root Directory
├── OVERVIEW.md                    ⭐ Comprehensive project guide (START HERE)
├── README.md                      ← Quick start (this file)
├── CLAUDE.md                      ← Instructions for Claude Code AI
│
├── OpenWebUI fork/                🎯 THE ACTUAL APPLICATION CODE
│   ├── src/                       ← Frontend (Svelte + TypeScript)
│   │   ├── lib/components/chat/
│   │   │   ├── FlowShortcuts.svelte        ⭐ Main shortcuts grid
│   │   │   ├── ShortcutCard.svelte         ⭐ Individual cards
│   │   │   └── AddShortcutModal.svelte     ⭐ Add/Edit modal
│   │   └── lib/stores/index.ts             ✏️ TypeScript types
│   ├── backend/                   ← Backend (FastAPI + Python)
│   ├── Dockerfile                 ✏️ Memory allocation fix
│   └── docker-compose.yaml
│
├── docs/                          📚 Documentation (5 essential files)
│   ├── FEATURE_IMPLEMENTATION_GUIDE.md    Complete implementation details
│   ├── FEATURES_COMPLETE.md               What's been built
│   ├── PROJECT_STRUCTURE.md               Directory organization
│   ├── TESTING-GUIDE.md                   How to test
│   ├── TROUBLESHOOTING.md                 Debugging help
│   └── archive/                           Old historical docs
│
└── tests/                         🧪 Test scripts (E2E tests)
    ├── e2e/                       Playwright test scripts
    └── fixtures/                  Test data files

---

✨ What's Been Built

Full CRUD Management

• ✅ Create shortcuts (Add button)
• ✅ Edit shortcuts (Edit icon)
• ✅ Delete shortcuts (Delete icon with confirmation)
• ✅ Drag & drop reordering
• ✅ Import/Export JSON
• ✅ Settings integration

Visual Features

• ✅ Customizable icons (emoji)
• ✅ Customizable colors
• ✅ Responsive layouts (2x2, 3x3, 4x2)
• ✅ Smooth animations
• ✅ Edit mode toggle

Advanced Features

• ✅ Pre-fill chat prompt
• ✅ Auto-submit option
• ✅ Empty state for new users
• ✅ Real-time updates (no page refresh)

---

📚 Documentation

Essential Reading

1. OVERVIEW.md ⭐ START HERE

   • Comprehensive project guide
   • Where code lives
   • How everything works
   • Common issues & solutions

2. docs/FEATURE_IMPLEMENTATION_GUIDE.md

   • Complete technical breakdown
   • What changed in each file
   • Why decisions were made

3. docs/FEATURES_COMPLETE.md

   • Summary of implemented features
   • User-facing documentation

For Development

4. CLAUDE.md - Instructions for Claude Code AI
5. docs/TESTING-GUIDE.md - How to test
6. docs/TROUBLESHOOTING.md - Common issues

---

🛠️ Development Workflow

Making Changes

# 1. Edit code in OpenWebUI fork/src/

# 2. Build frontend
cd "OpenWebUI fork"
npm run build

# 3. Rebuild Docker (IMPORTANT: use --no-cache!)
docker compose build --no-cache open-webui

# 4. Restart container
docker compose down open-webui && docker compose up -d open-webui

# 5. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+R)

⚠️ CRITICAL: Always use --no-cache flag or Docker will use cached old files!

---

🧪 Testing

Manual Test

1. Open http://localhost:3000
2. Click "Edit" in Quick Shortcuts section
3. Click "+ Add Shortcut"
4. Fill form and save
5. Click the card to test navigation

Automated Tests

# Test function selection
node tests/e2e/test-function-selection-steps-28-36.mjs

# Test drag and drop
node tests/e2e/test-drag-drop.mjs

# Test settings
node tests/e2e/test-settings-shortcuts.mjs

---

📊 Project Stats

• Implementation Time: 7 days (Oct 23-30, 2025)
• Lines of Code: ~1,412 lines added
• Files Created: 3 Svelte components
• Files Modified: 4 files
• Dependencies Added: 1 (svelte-dnd-action)
• Backend Changes: 0
• Database Migrations: 0

---

🐛 Common Issues

Shortcuts Not Showing

• Check Settings → Interface → Shortcuts (enabled?)
• Click "Edit" → "+ Add Shortcut" to create one
• Check browser console (F12) for errors

Changes Not Appearing After Build

• Use --no-cache flag: docker compose build --no-cache open-webui
• Verify in container: docker exec open-webui ls /app/build
• Hard refresh browser: Cmd+Shift+R (Mac) / Ctrl+Shift+R (Windows)

Docker Build Heap Memory Error

• Ensure Dockerfile line 30 is uncommented:

  ENV NODE_OPTIONS="--max-old-space-size=4096"

See docs/TROUBLESHOOTING.md for more solutions.

---

🔗 Links

• Comprehensive Guide: OVERVIEW.md ⭐
• OpenWebUI Docs: https://docs.openwebui.com/
• OpenWebUI GitHub: https://github.com/open-webui/open-webui

---

Version: OpenWebUI 0.6.34 + Flow Shortcuts v1.0 Status: ✅ Production Ready - Single Repository Structure Last Updated: November 1, 2025