metabuilder/frontends/workflowui/docs/QUICKSTART.md

# WorkflowUI Quick Start Guide

## 🚀 Getting Started in 5 Minutes

### Prerequisites
- Node.js 18+ installed
- Python 3.9+ installed
- Port 3001 (frontend) and 5000 (backend) available

---

## Option 1: Full Stack (Frontend + Backend)

### Terminal 1 - Start Backend
```bash
cd workflowui/backend
pip install -r requirements.txt
python3 server_sqlalchemy.py
```

Expected output:
```
Starting WorkflowUI Backend on 0.0.0.0:5000
Database: sqlite:///workflows.db
 * Running on http://0.0.0.0:5000
```

### Terminal 2 - Start Frontend
```bash
cd workflowui
npm install
npm run dev
```

Expected output:
```
✓ Ready in 1085ms
Local: http://localhost:3001
```

### Terminal 3 - Test Backend (Optional)
```bash
# Health check
curl http://localhost:5000/api/health

# List workspaces
curl 'http://localhost:5000/api/workspaces?tenantId=default'
```

### Open in Browser
- Frontend: http://localhost:3001
- Backend: http://localhost:5000

---

## Option 2: Frontend Only (Mock Data)

```bash
cd workflowui
npm run dev
```

Browser automatically opens to http://localhost:3001 with local IndexedDB data.

---

## Option 3: Docker (Full Stack)

```bash
# Build and run everything
docker-compose up

# Or just the backend
docker-compose up -d backend

# Or just the frontend
docker-compose up -d frontend
```

Then open http://localhost:3001

---

## 🧪 Testing the API

### Create a Workspace
```bash
curl -X POST http://localhost:5000/api/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ws-1",
    "name": "My First Workspace",
    "tenantId": "default",
    "color": "#1976d2"
  }'
```

### Create a Project
```bash
curl -X POST http://localhost:5000/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "id": "proj-1",
    "name": "AI Workflows",
    "workspaceId": "ws-1",
    "tenantId": "default",
    "color": "#ff6b6b"
  }'
```

### Get Project Canvas Items
```bash
curl http://localhost:5000/api/projects/proj-1/canvas?tenantId=default
```

### Add Workflow to Canvas
```bash
curl -X POST http://localhost:5000/api/projects/proj-1/canvas/items \
  -H "Content-Type: application/json" \
  -d '{
    "id": "card-1",
    "workflowId": "workflow-123",
    "position": {"x": 100, "y": 100},
    "size": {"width": 300, "height": 200},
    "zIndex": 0,
    "color": "#4CAF50"
  }'
```

---

## 📁 Key Directory Structure

```
workflowui/
├── src/
│   ├── app/              # Next.js pages and routes
│   ├── components/       # React components (<150 LOC each)
│   ├── hooks/            # Custom hooks (42 total)
│   ├── store/            # Redux state management
│   ├── services/         # API clients
│   └── types/            # TypeScript types
│
├── backend/
│   ├── models.py         # SQLAlchemy models
│   ├── server_sqlalchemy.py  # Flask app + 28 API endpoints
│   └── requirements.txt   # Python dependencies
│
├── Dockerfile
├── docker-compose.yml
└── IMPLEMENTATION_STATUS.md  # Full documentation
```

---

## 🎯 Main Features

### Frontend
- ✅ Infinite canvas with zoom/pan
- ✅ Workspace and Project management
- ✅ Workflow cards with drag-and-drop
- ✅ Real-time collaboration setup
- ✅ Settings (Canvas, Security, Notifications)
- ✅ Material Design 3 UI

### Backend
- ✅ RESTful API (28 endpoints)
- ✅ SQLAlchemy ORM
- ✅ Multi-tenant support
- ✅ Proper database indexing
- ✅ CRUD operations for all entities

---

## 🧬 Architecture Highlights

### Three-Layer Hierarchy
```
Workspace (top level)
  └── Project (grouping)
      └── Workflow Cards (spatial canvas items)
          └── Workflow Editor (existing React Flow)
```

### Modular Component Design
- All components: <150 LOC (single responsibility)
- All hooks: Focused business logic
- Composition pattern: Complex hooks built from simple ones
- Barrel exports: Clean import statements

### State Management
- **Redux**: Global state (workspaces, projects, canvas)
- **IndexedDB**: Offline persistence + sync queue
- **Redux Slices**: workspaceSlice, projectSlice, canvasSlice, etc.

---

## 🔧 Customization

### Add a New Hook
```typescript
// src/hooks/useMyFeature.ts
import { useSelector, useDispatch } from 'react-redux';

export function useMyFeature() {
  const dispatch = useDispatch();
  const state = useSelector(s => s.myFeature);

  const doSomething = useCallback(() => {
    dispatch(myAction());
  }, [dispatch]);

  return { state, doSomething };
}
```

### Add a New Component
```typescript
// src/components/MyComponent/MyComponent.tsx
import { Box, Button } from '@mui/material';
import styles from './MyComponent.module.scss';

export function MyComponent() {
  return (
    <Box className={styles.container}>
      <Button variant="contained">Click me</Button>
    </Box>
  );
}
```

### Add a New API Endpoint
```python
# backend/server_sqlalchemy.py
@app.route('/api/my-endpoint', methods=['POST'])
def my_endpoint():
    data = request.json
    tenant_id = request.args.get('tenantId', 'default')

    # Your logic here

    return jsonify({'success': True})
```

---

## 📚 Documentation

- **[IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md)** - Complete status of all phases
- **[PHASE_3_QUICK_REFERENCE.md](./PHASE_3_QUICK_REFERENCE.md)** - Developer guide for hooks
- **[PHASE_3_TEST_TEMPLATE.md](./PHASE_3_TEST_TEMPLATE.md)** - Testing templates
- **[docs/HOOKS_ANALYSIS.md](./docs/HOOKS_ANALYSIS.md)** - Detailed hook analysis

---

## 🚨 Troubleshooting

### Port Already in Use
```bash
# Kill existing process
lsof -i :5000      # Find process on port 5000
kill -9 <PID>      # Kill process

# Or use a different port
# Edit backend/server_sqlalchemy.py, change port in app.run()
```

### Database Issues
```bash
# Clear database and reinitialize
rm -f backend/workflows.db
python3 backend/server_sqlalchemy.py
```

### Build Errors
```bash
# Clear build cache
rm -rf .next node_modules
npm install
npm run build
```

---

## 🎓 Learning Path

1. **Start**: Read this file
2. **Explore**: Check `src/components/` directory structure
3. **Understand**: Look at `src/hooks/index.ts` to see all available hooks
4. **Learn**: Study one hook file (e.g., `useWorkspace.ts`)
5. **Build**: Create your own component using existing hooks
6. **Test**: Use API endpoints to persist data

---

## 🔗 Related Information

- **[IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md)** - All phases complete
- **Miro-Style Canvas Plan** - See `.claude/plans/` for full architecture
- **MetaBuilder Integration** - Part of larger workflow ecosystem

---

## ✨ What's Next

The application is production-ready! Potential next steps:

1. **Add Tests** - Use provided test templates
2. **Deploy to Docker** - Production-ready Dockerfile included
3. **Enable Real-time Collaboration** - WebSocket infrastructure ready
4. **Performance Optimization** - Virtualization for 100+ workflows
5. **Expand Features** - Follow existing patterns to add new functionality

---

## 💡 Pro Tips

- **Fast Development**: Use `npm run dev` for hot reloading
- **Type Safety**: All code uses TypeScript strict mode
- **Easy Debugging**: Redux DevTools works with `useSelector`
- **Clean Code**: All files <150 LOC, single responsibility
- **Reusable**: All hooks exported, easy to combine

---

**Happy workflow building!** 🎉

For questions or issues, check the documentation files or review the implementation status document.