# FlowMason Product Roadmap

The definitive roadmap for FlowMason's evolution from a pipeline execution framework to an AI-native workflow platform.

---

## Executive Summary

FlowMason is positioned to become the **AI-native workflow platform** that bridges the gap between visual pipeline design, enterprise integration, and modern AI capabilities. This roadmap outlines 24 major features organized into four priority stages, with quick wins first.

### Vision

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         FlowMason Platform Vision                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                  │
│   │   Design    │     │   Execute   │     │   Deploy    │                  │
│   │             │     │             │     │             │                  │
│   │ • VSCode    │────▶│ • Studio    │────▶│ • Docker    │                  │
│   │ • Visual    │     │ • Debug     │     │ • SDK       │                  │
│   │ • AI-Assist │     │ • Monitor   │     │ • Code Gen  │                  │
│   └─────────────┘     └─────────────┘     └─────────────┘                  │
│          │                   │                   │                          │
│          └───────────────────┴───────────────────┘                          │
│                              │                                              │
│                    ┌─────────▼─────────┐                                   │
│                    │   MCP Protocol    │                                   │
│                    │   (AI-Native)     │                                   │
│                    └───────────────────┘                                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Roadmap Stages

### 🚀 Stage 1: Quick Wins (P1)
**Timeline Focus: Immediate**

Low effort, high impact features that provide immediate value.

| Feature | Effort | Status |
|---------|--------|--------|
| Docker - Local Dev | Low | ✅ DONE |
| Execution Endpoint Auth | Low | ✅ DONE |
| Local .fmpkg Import | Low | ✅ DONE |
| AI Pipeline Generation (Docs) | Low | ✅ DONE |
| Component Visual - Icons & Colors | Low | ✅ DONE |
| MCP Server (Core) | Medium | ✅ DONE |
| Secrets Management (Basic) | Medium | ✅ DONE |

**Quick Win Themes:**
- 🐳 **Docker**: Single-command local development
- 🔐 **Security**: Token auth for API endpoints
- 📦 **Packaging**: Import pipeline packages
- 🤖 **AI-Ready**: PIPELINES.md for AI generation
- 🎨 **Visual Polish**: Icons and colors for components

---

### ⚡ Stage 2: Core Platform (P2)
**Timeline Focus: Near-term**

Essential features that form the production-ready platform.

#### Deployment & Operations
| Feature | Effort | Status |
|---------|--------|--------|
| Docker - Staging | Medium | ✅ DONE |
| Docker - Production | Medium | ✅ DONE |
| Web Portal - Operations Dashboard | Medium | ✅ DONE |
| Web Portal - API Console | Medium | ✅ DONE |
| Web Portal - Admin Panel | Medium | ✅ DONE |

#### Developer Experience
| Feature | Effort | Status |
|---------|--------|--------|
| Visual Field Mapping (Basic) | Medium | ✅ DONE |
| Visual Field Mapping (Schema Inference) | Medium | ✅ DONE |
| Visual Field Mapping (Validation) | Low | ✅ DONE |
| Component Visual - Shapes & Ports | Medium | ✅ DONE |
| Pipeline Debugger (Basic) | Medium | ✅ DONE |

#### AI & Automation
| Feature | Effort | Status |
|---------|--------|--------|
| MCP Client Operators | Medium | ✅ DONE |
| AI Generation - Interactive | Medium | ✅ DONE |
| LLM Cost Tracking | Medium | ✅ DONE |
| Prompt Library | Medium | ✅ DONE |

#### Pipeline Lifecycle
| Feature | Effort | Status |
|---------|--------|--------|
| Pipeline Versioning | Medium | ✅ DONE |
| Pipeline Testing - Basic Runner | Medium | ✅ DONE |
| Scheduling - Cron | Medium | ✅ DONE |
| Webhook Triggers | Medium | ✅ DONE |

#### SDK & Integration
| Feature | Effort | Status |
|---------|--------|--------|
| Embedded SDK (Python) | Medium | ✅ DONE |
| OAuth 2.0 Support | Medium | ✅ DONE |
| Built-in Template Gallery | Medium | ✅ DONE |

---

### 🎯 Stage 3: Advanced Features (P3)
**Timeline Focus: Mid-term**

Sophisticated capabilities for enterprise and power users.

#### P3 Quick Wins (Completed)
| Feature | Effort | Status |
|---------|--------|--------|
| Embedded SDK (React Hooks) | Low | ✅ DONE |
| Embedded SDK (TypeScript) | Medium | ✅ DONE |
| Secrets - Rotation & Audit | Medium | ✅ DONE |
| OpenTelemetry Integration | Medium | ✅ DONE |
| Pipeline Testing - Mocking & Snapshots | Medium | ✅ DONE |
| AI Generation - MCP Tool | Medium | ✅ DONE |

#### P3 SDKs & Integrations (Completed)
| Feature | Effort | Status |
|---------|--------|--------|
| VSCode Extension MCP | Medium | ✅ DONE |
| Web Portal MCP Integration | Medium | ✅ DONE |

#### P3 Enterprise & Scale
| Feature | Effort | Status |
|---------|--------|--------|
| Remote Registry | High | ✅ DONE |
| Pipeline-Level Permissions | High | ✅ DONE |
| Multi-Region Deployment | Very High | ✅ DONE |

#### P3 Remaining - Advanced AI
| Feature | Effort | Status |
|---------|--------|--------|
| MCP Advanced (AI-assisted) | High | ✅ DONE |
| Natural Language Builder | High | ✅ DONE |
| Prompt A/B Testing | High | ✅ DONE |

#### P3 Remaining - Developer Tools
| Feature | Effort | Status |
|---------|--------|--------|
| Debugger - Time Travel | High | ✅ DONE |
| Event-Driven Triggers | High | ✅ DONE |
| Execution Analytics & AI Insights | High | ✅ DONE |
| Real-time Collaboration | Very High | ✅ DONE |

#### P3 Remaining - Ecosystem
| Feature | Effort | Status |
|---------|--------|--------|
| Component Visual - Rich Cards | High | ✅ DONE |
| Pipeline Marketplace | Very High | ✅ DONE |

---

### 🔮 Stage 4: Future Vision (P4)
**Timeline Focus: Long-term**

Code generation features for deploying pipelines as standalone code.

#### Code Generation - ✅ COMPLETE
| Feature | Effort | Status |
|---------|--------|--------|
| Code Gen - Python | High | ✅ DONE |
| Code Gen - Node.js/TypeScript | High | ✅ DONE |
| Code Gen - Go | High | ✅ DONE |
| Code Gen - Salesforce Apex | High | ✅ DONE |
| Code Gen - Serverless (Lambda/Workers) | Medium | ✅ DONE |

**Supported Platforms:**
- Python: Standalone, AWS Lambda, Firebase Functions
- TypeScript: Standalone, AWS Lambda, Cloudflare Workers
- Go: Standalone, AWS Lambda, Docker
- Apex: Salesforce Platform

#### Infrastructure & Advanced (Future)
| Feature | Effort | Status |
|---------|--------|--------|
| Kubernetes Operator | Very High | Future |
| Visual Pipeline Diff & Merge | High | Future |
| Pipeline Inheritance & Composition | High | Future |

---

## Feature Categories

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Feature Categories                                   │
├───────────────────┬─────────────────────────────────────────────────────────┤
│ 🐳 Deployment     │ Docker, Multi-Region, Serverless                        │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 🔐 Security       │ Auth, Secrets, Permissions, OAuth                       │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 🎨 Visual Editor  │ Field Mapping, Icons, DAG Canvas, Collaboration        │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 🤖 AI-Native      │ MCP, Natural Language, Cost Tracking, Prompts          │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 📦 Packaging      │ .fmpkg Import, Registry, Marketplace                   │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 🧪 Testing        │ Debugger, Mocking, Snapshots, A/B Testing              │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 📊 Operations     │ Portal, Analytics, Scheduling, Webhooks                │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 🔌 SDKs           │ Python, TypeScript, React, Embedded                    │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 💻 Code Gen       │ Python, Node, Apex, Lambda, Go/Java/Rust               │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ 📈 Versioning     │ Pipeline Versions, Rollback, Environments              │
└───────────────────┴─────────────────────────────────────────────────────────┘
```

---

## Strategic Differentiators

### 1. AI-Native (MCP Integration)
FlowMason as both **MCP Server** (expose pipelines to AI) and **MCP Client** (call AI tools from pipelines). This positions FlowMason as the workflow backbone for AI agents.

### 2. Code Generation
Unlike other workflow tools that lock you in, FlowMason can **compile pipelines to standalone code** (Python, Node, Apex). Run anywhere, no runtime dependency.

### 3. Visual Field Mapping
**Drag-and-drop data mapping** with schema inference from the component registry. Lower the barrier for non-developers while maintaining power for developers.

### 4. Developer-First
**VSCode-native** editing experience, not a browser-based alternative. The IDE is the source of truth; the web portal is for operations.

### 5. Enterprise Ready
Built-in **SAML/SSO**, multi-tenant organizations, secrets management, and audit logging from day one.

---

## Success Metrics

| Stage | Key Metrics |
|-------|-------------|
| **P1 Quick Wins** | Time to first pipeline: < 5 minutes |
| **P2 Core** | Production deployments, SDK adoption |
| **P3 Advanced** | Enterprise deals, marketplace listings |
| **P4 Vision** | Platform ecosystem, community growth |

---

## Document Structure

This document details each feature with:
- **Concept**: What and why
- **Current State**: What exists today
- **Mockups**: Visual designs (ASCII art)
- **Implementation**: Technical approach
- **Files**: Affected code paths

---

# Feature Details

Below are detailed specifications for each planned feature, organized by original feature number.

---

## 1. Pipeline Packaging & Import

Enable users to package, share, and import pipelines from within VSCode.

### Current State
- `.fmpkg` package format exists (ZIP with manifest.json)
- `PackageBuilder` can include pipelines in packages
- `PackageInstaller` installs to `~/.flowmason/packages/`
- VSCode has `buildPackage` command and packages tree view

### Planned Features

#### Phase 1: Local .fmpkg Import
- [ ] Add "Import Pipeline Package" command in VSCode
- [ ] File picker for `.fmpkg` files
- [ ] Extract pipelines to current project's `pipelines/` directory
- [ ] Handle dependencies (prompt to install missing operators)
- [ ] Show import summary dialog

#### Phase 2: Built-in Template Gallery ✅ (Studio API Complete)
- [x] Studio API with 10 starter templates (content, data, analysis, automation, development)
- [x] Template browsing, search, and filtering by category/difficulty
- [x] Create pipeline from template API
- [x] Template preview with stage diagram
- [ ] VSCode: Bundle templates with extension
- [ ] VSCode: Add "Pipeline Templates" sidebar section
- [ ] VSCode: "Use Template" action creates pipeline in project

#### Phase 3: Remote Registry
- [ ] Central registry at flowmason.com/registry
- [ ] `fm install <package-name>` CLI command
- [ ] VSCode "Browse Registry" command
- [ ] Search by name, tags, category
- [ ] Version management and updates
- [ ] User accounts for publishing

### Package Format Enhancement
```json
{
  "name": "etl-starter-kit",
  "version": "1.0.0",
  "description": "Common ETL pipeline patterns",
  "type": "pipeline-pack",
  "pipelines": [
    "pipelines/data-validation.pipeline.json",
    "pipelines/batch-processing.pipeline.json"
  ],
  "dependencies": {
    "flowmason": ">=0.7.0"
  },
  "tags": ["etl", "data", "validation"]
}
```

---

## 2. API Authentication & Authorization

Secure access to pipelines via tokens and OAuth2.

### Current State (Already Implemented)

#### API Keys
- `APIKey` model with scopes: `FULL`, `READ`, `EXECUTE`, `DEPLOY`
- Key format: `fm_live_<48-char-hex>` with prefix for identification
- SHA-256 hashing for secure storage
- Rate limiting (configurable per key)
- Expiration and revocation support
- Full CRUD API routes at `/api/v1/auth/api-keys`

**Files:** `studio/flowmason_studio/auth/models.py`, `studio/flowmason_studio/auth/service.py`

#### Users & Organizations
- User model with password hashing (SHA-256)
- Organization model with plans and limits (users, pipelines, executions/day)
- Org memberships with roles: `OWNER`, `ADMIN`, `DEVELOPER`, `VIEWER`
- SSO fields for external identity providers

**Files:** `studio/flowmason_studio/auth/models.py`, `studio/flowmason_studio/auth/service.py`

#### Supabase JWT Integration
- JWT verification via Supabase `/auth/v1/user` endpoint
- Role-based access control middleware
- Development mode fallback (no auth required locally)
- Pre-built role dependencies: `require_admin`, `require_pipeline_developer`, `require_node_developer`

**Files:** `studio/flowmason_studio/middleware/auth.py`

#### SAML/SSO (Enterprise)
- Full SAML 2.0 Service Provider implementation
- Supported IdPs: Okta, Azure AD, Google, OneLogin, Ping, Auth0, Custom
- SP-initiated and IdP-initiated SSO flows
- Just-in-time (JIT) user provisioning
- Configurable attribute mapping
- SP metadata generation for IdP configuration

**Files:** `studio/flowmason_studio/auth/saml.py`, `studio/flowmason_studio/api/routes/saml.py`

#### Audit Logging
- `AuditLogEntry` model tracking all actions
- Captures: user_id, api_key_id, ip_address, user_agent
- Action types: `pipeline.create`, `execution.run`, `api_key.create`, etc.
- Query API with filtering by action/resource type

**Files:** `studio/flowmason_studio/auth/service.py` (lines 525-623)

### Planned Features (Not Yet Implemented)

#### Phase 1: OAuth 2.0 Support ✅ Complete
- [x] OAuth 2.0 Authorization Code flow for web apps
- [x] Client Credentials flow for service-to-service
- [x] Refresh token support with rotation
- [x] OAuth client registration API (`/api/v1/oauth/clients`)
- [x] Token introspection endpoint (RFC 7662)
- [x] Token revocation endpoint (RFC 7009)
- [x] PKCE support for public clients (S256 + plain)
- [x] Server metadata discovery (RFC 8414)

```python
# Example OAuth client registration
POST /api/v1/oauth/clients
{
  "name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["read", "execute"]
}
```

#### Phase 2: Standalone JWT Tokens ✅ Complete
- [x] JWT token issuing without external dependencies
- [x] Configurable signing keys (HS256/HS384/HS512)
- [x] Token claims customization with custom_claims
- [x] Access + refresh token pattern with rotation
- [x] Token revocation via JTI blacklist
- [x] Token introspection and verification endpoints
- [x] Key rotation API

#### Phase 3: Pipeline-Level Permissions
- [ ] Fine-grained access control per pipeline
- [ ] Share pipelines with specific users/organizations
- [ ] Permission levels: `view`, `run`, `edit`, `admin`
- [ ] Pipeline visibility: `private`, `org`, `public`
- [ ] Access inheritance from folders

```json
{
  "pipeline_id": "pipe_abc123",
  "permissions": [
    {"principal": "user_xyz", "level": "edit"},
    {"principal": "org_acme", "level": "run"},
    {"principal": "*", "level": "view"}
  ]
}
```

#### Phase 4: Enforcement on Execution Endpoints
- [ ] Require auth on `/api/v1/debug/run` (currently open)
- [ ] Scope validation: `execute` scope required for running pipelines
- [ ] Rate limiting per API key/user
- [ ] Execution quotas per organization plan
- [ ] Webhook authentication (HMAC signatures)

### API Key Scopes Reference

| Scope | Permissions |
|-------|-------------|
| `full` | All operations |
| `read` | List/get pipelines, view executions |
| `execute` | Run pipelines, view results |
| `deploy` | Deploy pipelines to production |

---

## 3. Docker Installation & Deployment

Containerized deployment for local development, staging, and production environments.

### Current State
- No Docker support currently exists
- Manual Python installation required
- No standardized deployment process

### Planned Features

#### Phase 1: Local Development (Docker Compose)

**Single-command local setup:**
```bash
# Clone and start
git clone https://github.com/flowmason/flowmason.git
cd flowmason
docker compose up -d

# Access Studio at http://localhost:8999
```

**docker-compose.yml structure:**
```yaml
version: '3.8'

services:
  studio:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8999:8999"
    volumes:
      - ./pipelines:/app/pipelines          # Mount local pipelines
      - flowmason-data:/app/.flowmason      # Persist database
    environment:
      - FLOWMASON_ENV=development
      - FLOWMASON_LOG_LEVEL=debug
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

  # Optional: PostgreSQL for production-like setup
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: flowmason
      POSTGRES_USER: flowmason
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-flowmason}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    profiles:
      - production

volumes:
  flowmason-data:
  redis-data:
  postgres-data:
```

**Dockerfile:**
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    git curl && \
    rm -rf /var/lib/apt/lists/*

# Install FlowMason
COPY pyproject.toml .
COPY core/ core/
COPY studio/ studio/
COPY lab/ lab/

RUN pip install --no-cache-dir -e .

# Build frontend
COPY studio/frontend/ studio/frontend/
WORKDIR /app/studio/frontend
RUN npm ci && npm run build

WORKDIR /app

# Create non-root user
RUN useradd -m -u 1000 flowmason
USER flowmason

EXPOSE 8999

CMD ["fm", "studio", "start", "--host", "0.0.0.0", "--port", "8999"]
```

#### Phase 2: Staging Environment

**docker-compose.staging.yml:**
```yaml
version: '3.8'

services:
  studio:
    image: flowmason/studio:${VERSION:-latest}
    ports:
      - "8999:8999"
    environment:
      - FLOWMASON_ENV=staging
      - DATABASE_URL=postgresql://flowmason:${DB_PASSWORD}@postgres:5432/flowmason
      - REDIS_URL=redis://redis:6379
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: flowmason
      POSTGRES_USER: flowmason
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
```

**Usage:**
```bash
# Create .env.staging
cp .env.example .env.staging
# Edit with staging credentials

# Deploy staging
docker compose -f docker-compose.staging.yml --env-file .env.staging up -d

# View logs
docker compose -f docker-compose.staging.yml logs -f studio

# Update to new version
docker compose -f docker-compose.staging.yml pull
docker compose -f docker-compose.staging.yml up -d
```

#### Phase 3: Production Deployment

**docker-compose.production.yml:**
```yaml
version: '3.8'

services:
  studio:
    image: flowmason/studio:${VERSION}
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '0.5'
          memory: 1G
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    environment:
      - FLOWMASON_ENV=production
      - DATABASE_URL=postgresql://flowmason:${DB_PASSWORD}@postgres:5432/flowmason
      - REDIS_URL=redis://redis:6379
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
      - SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}
      - SECRET_KEY=${SECRET_KEY}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8999/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - studio
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: flowmason
      POSTGRES_USER: flowmason
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./backups:/backups
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U flowmason"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
```

**Production deployment script (deploy.sh):**
```bash
#!/bin/bash
set -e

VERSION=${1:-latest}
ENV_FILE=${2:-.env.production}

echo "Deploying FlowMason Studio v${VERSION}..."

# Pull latest images
docker compose -f docker-compose.production.yml pull

# Backup database before upgrade
docker compose -f docker-compose.production.yml exec postgres \
  pg_dump -U flowmason flowmason > backups/backup-$(date +%Y%m%d-%H%M%S).sql

# Rolling update
docker compose -f docker-compose.production.yml --env-file $ENV_FILE up -d --no-deps studio

# Wait for health check
echo "Waiting for health check..."
sleep 30
curl -f http://localhost:8999/health || exit 1

echo "Deployment complete!"
```

### Environment Variables Reference

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FLOWMASON_ENV` | No | development | Environment: development, staging, production |
| `DATABASE_URL` | Prod | SQLite | PostgreSQL connection string |
| `REDIS_URL` | No | None | Redis connection for caching/queues |
| `SUPABASE_URL` | Prod | None | Supabase project URL |
| `SUPABASE_ANON_KEY` | Prod | None | Supabase anonymous key |
| `SUPABASE_SERVICE_ROLE_KEY` | Prod | None | Supabase service role key |
| `SECRET_KEY` | Prod | Auto | JWT signing key (generate with `openssl rand -hex 32`) |
| `FLOWMASON_LOG_LEVEL` | No | info | Logging level: debug, info, warning, error |
| `MAX_WORKERS` | No | 4 | Number of worker processes |

### Quick Start Commands

```bash
# Local development
docker compose up -d
docker compose logs -f

# Run a pipeline
docker compose exec studio fm run pipelines/my-pipeline.json

# Access shell
docker compose exec studio bash

# Stop
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v
```

### Files to Create

- [ ] `Dockerfile` - Multi-stage build for optimized image
- [ ] `Dockerfile.dev` - Development image with hot reload
- [ ] `docker-compose.yml` - Local development
- [ ] `docker-compose.staging.yml` - Staging environment
- [ ] `docker-compose.production.yml` - Production with HA
- [ ] `.dockerignore` - Exclude unnecessary files
- [ ] `nginx.conf` - Reverse proxy configuration
- [ ] `.env.example` - Environment variables template
- [ ] `scripts/deploy.sh` - Production deployment script
- [ ] `scripts/backup.sh` - Database backup script
- [ ] `docs/docker-deployment.md` - Detailed documentation

---

## 4. Web Portal Enhancement

Improve the standalone web frontend for operators and non-VSCode users.

### Current State
- Basic React frontend in `studio/frontend/`
- Pipeline visualization and execution
- No file system access from browser

### Design Philosophy

**VSCode Extension = Developer Authoring Tool (Native)**
- Full IDE integration (IntelliSense, diagnostics, debugging)
- Pipeline creation and editing
- Deep file system integration

**Web Portal = Operations & Monitoring Dashboard**
- Execution monitoring and history
- Run pipelines with custom inputs
- Admin panel (API keys, users, settings)
- For non-VSCode users and operators
- NOT trying to replicate VSCode editing experience

### Planned Features

#### Phase 1: Operations Dashboard
- [x] Execution history with filtering (existing /runs endpoint)
- [x] Real-time execution monitoring (WebSocket support)
- [x] Log viewer with streaming (existing /logs endpoint)
- [x] Pipeline run statistics and metrics (NEW: /analytics API)
- [ ] Manual trigger UI with input form (Frontend)

#### Phase 2: Admin Panel (Backend APIs Complete)
- [x] API key management API (existing /auth/api-keys)
- [x] User and organization management (existing /auth)
- [x] SAML/SSO configuration (existing /saml)
- [x] Audit log API (existing /auth/audit)
- [x] System health and diagnostics (NEW: /system API)
- [ ] Admin Panel UI (Frontend)

#### Phase 3: Pipeline Viewer (Read-Only)
- [ ] Visual pipeline graph (view only)
- [ ] Stage configuration viewer
- [ ] Component documentation browser
- [ ] Input/output schema explorer

#### Phase 4: Limited Editing (via MCP)
- [ ] Edit pipeline inputs/config (not structure)
- [ ] File operations via MCP integration
- [ ] Create new runs from templates
- [ ] Save execution results

### Target Users

| User Type | Primary Interface | Use Case |
|-----------|------------------|----------|
| Developer | VSCode Extension | Build, debug, test pipelines |
| DevOps | Web Portal | Deploy, monitor, troubleshoot |
| Business User | Web Portal | Run pipelines, view results |
| Admin | Web Portal | Manage users, API keys, settings |

---

## 5. MCP Integration (Model Context Protocol)

Native MCP support to make FlowMason AI-agent ready and enable unified resource access.

### Strategic Value

**FlowMason + MCP = The workflow platform for the AI era**

- First workflow tool with native MCP support
- AI agents can invoke pipelines as tools
- Unified file/resource access across VSCode, Web, CLI
- Automatic integration with growing MCP ecosystem

### Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                         MCP Ecosystem                           │
│                                                                 │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐   │
│   │ Claude  │  │ Cursor  │  │ Other   │  │ FlowMason       │   │
│   │ Desktop │  │ IDE     │  │ Agents  │  │ Web Portal      │   │
│   └────┬────┘  └────┬────┘  └────┬────┘  └────────┬────────┘   │
│        │            │            │                │            │
│        └────────────┴─────┬──────┴────────────────┘            │
│                           │                                    │
│                    MCP Protocol                                │
│                           │                                    │
│        ┌──────────────────┼──────────────────┐                 │
│        ▼                  ▼                  ▼                 │
│  ┌──────────┐      ┌──────────────┐   ┌──────────────┐        │
│  │Filesystem│      │  FlowMason   │   │  Database    │        │
│  │MCP Server│      │  MCP Server  │   │  MCP Server  │        │
│  └──────────┘      └──────────────┘   └──────────────┘        │
│        │                  │                  │                 │
│        ▼                  ▼                  ▼                 │
│   Local Files      Pipeline Engine      PostgreSQL             │
└─────────────────────────────────────────────────────────────────┘
```

### Part A: FlowMason as MCP Server

Expose FlowMason capabilities to AI agents and other MCP clients.

#### MCP Server Specification

```typescript
// FlowMason MCP Server capabilities
{
  "name": "flowmason",
  "version": "1.0.0",
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true
  }
}
```

#### Tools (Actions AI Can Invoke)

```typescript
tools: [
  {
    name: "pipelines/list",
    description: "List all available pipelines in the project",
    inputSchema: {
      type: "object",
      properties: {
        project_path: { type: "string", description: "Path to FlowMason project" },
        tags: { type: "array", items: { type: "string" }, description: "Filter by tags" }
      }
    }
  },
  {
    name: "pipelines/run",
    description: "Execute a FlowMason pipeline with given inputs",
    inputSchema: {
      type: "object",
      properties: {
        pipeline: { type: "string", description: "Pipeline name or path" },
        inputs: { type: "object", description: "Pipeline input values" },
        wait: { type: "boolean", default: true, description: "Wait for completion" }
      },
      required: ["pipeline"]
    }
  },
  {
    name: "pipelines/get-status",
    description: "Get the status of a pipeline execution",
    inputSchema: {
      type: "object",
      properties: {
        run_id: { type: "string", description: "Execution run ID" }
      },
      required: ["run_id"]
    }
  },
  {
    name: "pipelines/get-result",
    description: "Get the result of a completed pipeline execution",
    inputSchema: {
      type: "object",
      properties: {
        run_id: { type: "string", description: "Execution run ID" }
      },
      required: ["run_id"]
    }
  },
  {
    name: "components/list",
    description: "List all available components (operators, nodes)",
    inputSchema: {
      type: "object",
      properties: {
        category: { type: "string", description: "Filter by category" },
        type: { type: "string", enum: ["operator", "node", "all"] }
      }
    }
  },
  {
    name: "components/get-schema",
    description: "Get the input/output schema for a component",
    inputSchema: {
      type: "object",
      properties: {
        component_name: { type: "string", description: "Component name" }
      },
      required: ["component_name"]
    }
  }
]
```

#### Resources (Data AI Can Read)

```typescript
resources: [
  {
    uri: "pipeline://data-validation",
    name: "Data Validation Pipeline",
    description: "Validates and transforms input data",
    mimeType: "application/json"
  },
  {
    uri: "execution://run_abc123",
    name: "Execution Run abc123",
    description: "Results from pipeline execution",
    mimeType: "application/json"
  },
  {
    uri: "component://filter",
    name: "Filter Operator",
    description: "Conditionally filter data based on conditions",
    mimeType: "application/json"
  }
]
```

#### Prompts (Pre-built AI Interactions)

```typescript
prompts: [
  {
    name: "analyze-pipeline",
    description: "Analyze a pipeline and suggest improvements",
    arguments: [
      { name: "pipeline", description: "Pipeline to analyze", required: true }
    ]
  },
  {
    name: "debug-execution",
    description: "Help debug a failed pipeline execution",
    arguments: [
      { name: "run_id", description: "Failed execution run ID", required: true }
    ]
  },
  {
    name: "create-pipeline",
    description: "Help create a new pipeline based on requirements",
    arguments: [
      { name: "description", description: "What the pipeline should do", required: true }
    ]
  }
]
```

#### Use Cases: AI Agents Using FlowMason

**Example 1: Claude Desktop Running a Pipeline**
```
User: "Validate my customer data file and show me any issues"

Claude: I'll use FlowMason to validate your data.
        → MCP: pipelines/run {pipeline: "data-validation", inputs: {file: "customers.csv"}}

FlowMason: Executes pipeline, returns results

Claude: "I found 3 validation issues:
        - Row 45: Invalid email format 'john@'
        - Row 67: Duplicate customer ID 'CUST-001'
        - Row 89: Missing required field 'country'"
```

**Example 2: AI Agent Orchestrating Multiple Pipelines**
```
User: "Process this month's sales data and generate the executive report"

Claude: I'll run the sales processing workflow.
        → MCP: pipelines/run {pipeline: "sales-etl", inputs: {month: "2025-01"}}
        → MCP: pipelines/run {pipeline: "generate-report", inputs: {data: <etl-output>}}

Claude: "Done! The executive report is ready at reports/2025-01-sales.pdf
        Key highlights:
        - Revenue up 15% vs last month
        - Top performing region: West Coast
        - 3 products flagged for review"
```

**Example 3: Cursor IDE Integration**
```
Developer in Cursor: "Run the test pipeline on this JSON"

Cursor: → MCP: pipelines/run {pipeline: "test-transform", inputs: {data: <selected-json>}}

Result appears inline in editor
```

### Part B: FlowMason as MCP Client

Pipeline stages can consume MCP servers for unified resource access.

#### New MCP Operators

```yaml
# New operators that consume MCP resources
stages:
  - id: read-data
    component: mcp_resource
    config:
      server: "filesystem"  # or "s3", "postgres", etc.
      uri: "file:///data/input.csv"

  - id: query-db
    component: mcp_tool
    config:
      server: "postgres"
      tool: "query"
      arguments:
        sql: "SELECT * FROM customers WHERE active = true"

  - id: call-api
    component: mcp_tool
    config:
      server: "http"
      tool: "fetch"
      arguments:
        url: "https://api.example.com/data"
        method: "GET"
```

#### Environment Portability

```yaml
# Same pipeline works in any environment
# Just configure different MCP servers

# Local development (.env.local)
MCP_FILESYSTEM_ROOT=/Users/dev/projects/data
MCP_DATABASE_URL=sqlite:///local.db

# Staging (.env.staging)
MCP_FILESYSTEM_ROOT=s3://staging-bucket/data
MCP_DATABASE_URL=postgresql://staging-db/flowmason

# Production (.env.production)
MCP_FILESYSTEM_ROOT=s3://prod-bucket/data
MCP_DATABASE_URL=postgresql://prod-cluster/flowmason
```

#### Unified File Access for Web Portal

```
┌─────────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Web Portal    │────▶│  Studio API     │────▶│  MCP Server  │
│   (Browser)     │     │  /api/v1/mcp/*  │     │  (filesystem)│
└─────────────────┘     └─────────────────┘     └──────────────┘
                                                       │
┌─────────────────┐                                    │
│ VSCode Extension│────────────────────────────────────┘
│   (MCP Client)  │     Same MCP server, same files
└─────────────────┘
```

### Part C: VSCode Extension MCP Integration

#### Extension as MCP Client

```typescript
// VSCode extension connects to FlowMason MCP server
import { Client } from "@modelcontextprotocol/sdk/client";

const mcpClient = new Client({
  name: "flowmason-vscode",
  version: "1.0.0"
});

// Connect to FlowMason MCP server
await mcpClient.connect(transport);

// List pipelines
const pipelines = await mcpClient.callTool("pipelines/list", {});

// Run pipeline
const result = await mcpClient.callTool("pipelines/run", {
  pipeline: "data-validation",
  inputs: { file: "test.csv" }
});
```

#### Extension Hosting MCP Server

```typescript
// VSCode extension can also HOST an MCP server
// Exposing VSCode workspace capabilities

const server = new Server({
  name: "flowmason-vscode-workspace",
  version: "1.0.0"
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "workspace/read-file",
      description: "Read a file from the VSCode workspace",
      inputSchema: { /* ... */ }
    },
    {
      name: "workspace/write-file",
      description: "Write a file to the VSCode workspace",
      inputSchema: { /* ... */ }
    }
  ]
}));
```

### Implementation Phases

#### Phase 1: FlowMason MCP Server (Core)
- [ ] Implement MCP server in Python (`flowmason_core/mcp/`)
- [ ] `pipelines/list` tool
- [ ] `pipelines/run` tool
- [ ] `pipelines/get-status` tool
- [ ] `components/list` tool
- [ ] Pipeline resources
- [ ] CLI command: `fm mcp serve`
- [ ] Documentation for Claude Desktop integration

#### Phase 2: MCP Client Operators
- [ ] `mcp_resource` operator - read from any MCP resource
- [ ] `mcp_tool` operator - invoke any MCP tool
- [ ] MCP server configuration in `flowmason.json`
- [ ] Built-in filesystem MCP server
- [ ] Environment-based MCP server selection

#### Phase 3: VSCode Extension MCP
- [ ] Extension as MCP client (connect to FlowMason MCP server)
- [ ] Extension hosts workspace MCP server
- [ ] Unified file operations via MCP
- [ ] MCP server status in status bar

#### Phase 4: Web Portal MCP
- [ ] Studio API proxies MCP requests
- [ ] Web portal file browser via MCP
- [ ] Pipeline editing via MCP (limited)
- [ ] MCP server management UI

#### Phase 5: Advanced Features
- [ ] MCP prompts for AI-assisted pipeline creation
- [ ] Pipeline composition via AI
- [ ] Execution debugging with AI assistance
- [ ] Multi-server MCP routing

### Files to Create

```
core/flowmason_core/mcp/
├── __init__.py
├── server.py              # FlowMason MCP Server implementation
├── tools/
│   ├── __init__.py
│   ├── pipelines.py       # Pipeline-related tools
│   ├── components.py      # Component-related tools
│   └── executions.py      # Execution-related tools
├── resources/
│   ├── __init__.py
│   ├── pipeline.py        # Pipeline resources
│   └── execution.py       # Execution resources
└── prompts/
    ├── __init__.py
    └── templates.py       # AI prompt templates

lab/flowmason_lab/operators/mcp/
├── __init__.py
├── mcp_resource.py        # Read from MCP resources
└── mcp_tool.py            # Invoke MCP tools

vscode-extension/src/mcp/
├── client.ts              # MCP client for extension
└── server.ts              # Workspace MCP server
```

### Configuration

```json
// flowmason.json - MCP configuration
{
  "mcp": {
    "server": {
      "enabled": true,
      "port": 3000,
      "transport": "stdio"  // or "http", "websocket"
    },
    "clients": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
      },
      "postgres": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
      }
    }
  }
}
```

### Claude Desktop Integration

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "flowmason": {
      "command": "fm",
      "args": ["mcp", "serve"],
      "env": {
        "FLOWMASON_PROJECT": "/path/to/project"
      }
    }
  }
}
```

---

## 6. AI Pipeline Generation

Enable AI assistants to generate valid FlowMason pipelines from natural language descriptions.

### Current State
- Created `PIPELINES.md` - comprehensive guide for AI assistants
- Documents pipeline structure, all components, patterns, and examples
- Can be used by Claude, ChatGPT, Copilot, Cursor, etc.

### Files Created

**`/PIPELINES.md`** - AI context file containing:
- Pipeline JSON structure
- Template syntax (`{{input.*}}`, `{{upstream.*}}`)
- All available components with examples:
  - Core: logger, json_transform, filter, variable_set, schema_validate
  - Control Flow: foreach, conditional, router
  - HTTP: http_request
  - AI/LLM: generator, critic, selector
- Pipeline patterns (ETL, Batch Processing, Conditional, AI Generation)
- Best practices
- Complete example pipeline
- Prompting tips for AI

### How to Use

**With Claude/ChatGPT:**
```
Read the PIPELINES.md file, then create a FlowMason pipeline that:
- Takes customer orders as input
- Validates the data
- Filters high-value orders (>$500)
- Generates a summary report
```

**With Cursor/Copilot:**
- Open PIPELINES.md in the workspace
- AI will use it as context for pipeline generation
- Type a comment describing what you want and autocomplete

**With Claude Desktop (via MCP):**
```
User: "Create a pipeline that processes survey responses"
Claude: [reads PIPELINES.md via MCP] Here's a FlowMason pipeline...
```

### Planned Enhancements

#### Phase 1: Documentation (Complete)
- [x] Create PIPELINES.md with full component reference
- [x] Include patterns and examples
- [x] Add prompting tips

#### Phase 2: Schema-Driven Generation
- [ ] Export JSON Schema for pipeline format
- [ ] Generate component schemas dynamically from code
- [ ] VSCode extension provides schema to AI assistants

#### Phase 3: Interactive Generation
- [ ] `/generate` command in VSCode extension
- [ ] Natural language input → pipeline JSON
- [ ] Preview and edit before saving
- [ ] Iterative refinement ("make it also filter by date")

#### Phase 4: MCP-Powered Generation
- [ ] `pipelines/generate` MCP tool
- [ ] AI can create pipelines programmatically
- [ ] Validation before returning result
- [ ] Suggest improvements to generated pipelines

### Example AI Interaction

```
User: Create a pipeline that analyzes customer feedback

AI: I'll create a FlowMason pipeline for customer feedback analysis.

{
  "name": "Customer Feedback Analysis",
  "version": "1.0.0",
  "description": "Analyzes customer feedback for sentiment and key themes",
  "input_schema": {
    "type": "object",
    "properties": {
      "feedback_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "text": { "type": "string" },
            "date": { "type": "string" }
          }
        }
      }
    },
    "required": ["feedback_items"]
  },
  "stages": [
    {
      "id": "validate-input",
      "component_type": "schema_validate",
      "config": { ... },
      "depends_on": []
    },
    {
      "id": "analyze-sentiment",
      "component_type": "foreach",
      "config": {
        "items": "{{upstream.validate-input.data}}",
        "loop_stages": ["sentiment-analysis"]
      },
      "depends_on": ["validate-input"]
    },
    ...
  ]
}

This pipeline:
1. Validates the input feedback format
2. Analyzes sentiment for each feedback item
3. Groups feedback by sentiment
4. Generates a summary report

Would you like me to modify anything?
```

---

## 7. Component Visual Enhancement

Improve the visual appearance of pipeline components in both VSCode and Web interfaces.

### Current State

**Operator metadata exists but is underutilized:**
```python
@operator(
    name="filter",
    icon="filter",           # Lucide icon name
    color="#8B5CF6",         # Hex color
    category="core",
    tags=["filter", "condition", "branch"],
)
```

**Current rendering issues:**

| Interface | Issue |
|-----------|-------|
| VSCode DAG Canvas | Plain rectangles, no icons, no component colors |
| VSCode Components Tree | Generic ThemeIcons, no component colors |
| Web Frontend | Generic icons (Box/Zap), colors partially used |

### Planned Improvements

#### Phase 1: Use Component Colors & Icons

**VSCode DAG Canvas:**
```html
<!-- Current -->
<rect class="node-bg" fill="var(--vscode-editor-background)" />
<text class="node-label">filter</text>

<!-- Improved -->
<rect class="node-bg" fill="#8B5CF6" opacity="0.1" />
<rect class="node-header" fill="#8B5CF6" height="32" />
<text class="node-icon">🔍</text>  <!-- or SVG icon -->
<text class="node-label" fill="white">Filter</text>
```

**Web Frontend - Map icon names to Lucide:**
```typescript
const iconMap: Record<string, LucideIcon> = {
  'filter': Filter,
  'code': Code,
  'globe': Globe,
  'file-text': FileText,
  'repeat': Repeat,
  'variable': Variable,
  'shield-check': ShieldCheck,
  'share-2': Share2,
  'git-branch': GitBranch,
  'zap': Zap,
  'sparkles': Sparkles,
};
```

#### Phase 2: Component Shape by Type

Different visual shapes for different component types:

```
┌─────────────────┐     ╔═════════════════╗     ◆─────────────────◆
│   Operators     │     ║     Nodes       ║     │  Control Flow   │
│   (Rectangles)  │     ║   (Rounded)     ║     │   (Diamond)     │
└─────────────────┘     ╚═════════════════╝     ◆─────────────────◆

┌─────────────────┐     ┌─────────────────┐
│ ⚡ Filter       │     │ 🌐 HTTP Request │
│ ─────────────── │     │ ─────────────── │
│ condition:      │     │ url: api.com    │
│ item.status     │     │ method: GET     │
└─────────────────┘     └─────────────────┘
```

#### Phase 3: Visual Data Flow

Show input/output schemas on connection ports:

```
                    ┌──────────────────┐
    {items[]}  ──●──│  foreach         │──●── {results[]}
                    │  ────────────────│
                    │  items: input    │
                    └──────────────────┘
                             │
                     {current_item}
                             │
                             ▼
                    ┌──────────────────┐
                    │  transform       │
                    └──────────────────┘
```

#### Phase 4: Rich Component Cards

**Enhanced node design:**
```
┌────────────────────────────────────┐
│ ■■■■■■■■■■■■■■■■ (category color)  │
├────────────────────────────────────┤
│  🔍  Filter                    v1.1│
│      ──────────────────────────────│
│  ○ data        →    passed ●       │
│  ○ condition        data   ●       │
│                     reason ●       │
├────────────────────────────────────┤
│  Tags: filter, condition, branch   │
└────────────────────────────────────┘
```

### Implementation Details

#### Component Icon Mapping

```typescript
// vscode-extension/src/utils/componentIcons.ts
export const componentIcons: Record<string, string> = {
  // Core
  'filter': 'filter',
  'json_transform': 'code',
  'logger': 'file-text',
  'variable_set': 'variable',
  'schema_validate': 'shield-check',
  'http_request': 'globe',

  // Control Flow
  'foreach': 'repeat',
  'conditional': 'git-branch',
  'router': 'share-2',
  'loop': 'repeat',

  // AI/LLM
  'generator': 'sparkles',
  'critic': 'message-square',
  'selector': 'check-square',

  // Default
  'default_operator': 'zap',
  'default_node': 'box',
};

export const categoryColors: Record<string, string> = {
  'core': '#6366F1',      // Indigo
  'control_flow': '#EC4899', // Pink
  'ai': '#F59E0B',        // Amber
  'integration': '#3B82F6', // Blue
  'data': '#14B8A6',      // Teal
  'workspace': '#78716C', // Stone
};
```

#### VSCode Webview SVG Icons

```typescript
// Generate inline SVG from Lucide icon data
function getLucideIconSvg(iconName: string, color: string): string {
  const iconPaths = lucideIcons[iconName];
  return `
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         viewBox="0 0 24 24" fill="none" stroke="${color}"
         stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
      ${iconPaths}
    </svg>
  `;
}
```

#### API Enhancement

```python
# Add to registry API response
@dataclass
class ComponentInfo:
    name: str
    category: str
    description: str
    icon: str           # Lucide icon name
    color: str          # Hex color
    input_schema: dict  # For port visualization
    output_schema: dict # For port visualization
    tags: List[str]
    version: str
```

### Design Tokens

```css
/* Component design tokens */
:root {
  /* Category colors */
  --fm-core-color: #6366F1;
  --fm-control-flow-color: #EC4899;
  --fm-ai-color: #F59E0B;
  --fm-integration-color: #3B82F6;
  --fm-data-color: #14B8A6;

  /* Node styles */
  --fm-node-radius: 12px;
  --fm-node-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --fm-node-border: 2px solid;
  --fm-node-header-height: 36px;

  /* Port styles */
  --fm-port-size: 12px;
  --fm-port-color-input: #94A3B8;
  --fm-port-color-output: #22C55E;
}
```

### Files to Modify

**VSCode Extension:**
- [ ] `src/editors/dagCanvasProvider.ts` - Enhanced node rendering with icons/colors
- [ ] `src/views/componentsTree.ts` - Use component icons and colors
- [ ] `src/utils/componentIcons.ts` - Icon mapping (new file)
- [ ] `src/services/flowmasonService.ts` - Fetch icon/color from API

**Web Frontend:**
- [ ] `src/components/PipelineCanvas.tsx` - Use component icons
- [ ] `src/components/nodes/StageNode.tsx` - Enhanced node design
- [ ] `src/utils/componentIcons.ts` - Icon mapping
- [ ] `src/components/ComponentPalette.tsx` - Show icons in palette

**Backend:**
- [ ] `studio/flowmason_studio/api/routes/registry.py` - Include icon/color in response
- [ ] `core/flowmason_core/registry/extractor.py` - Extract icon/color metadata

### Mockups

**Current vs Improved - VSCode:**
```
CURRENT:                          IMPROVED:
┌─────────────┐                   ┌────────────────────┐
│ filter      │                   │ 🔍 Filter     v1.1 │
│ operator    │        →          │ ────────────────── │
└─────────────┘                   │ Filters data based │
                                  │ on conditions      │
                                  └────────────────────┘
                                  (with purple accent)
```

**Current vs Improved - Web:**
```
CURRENT:                          IMPROVED:
┌──────────────────┐              ┌──────────────────────┐
│ ⚡ filter        │              │ ■■■■■ (purple bar)   │
│ operator         │     →        │ 🔍 Filter            │
└──────────────────┘              │ ○ data    → passed ● │
                                  └──────────────────────┘
```

---

## 8. Scheduling & Triggers

Enable automated pipeline execution via schedules, webhooks, and event-driven triggers.

### Current State
- Pipelines can only be run manually (CLI, API, VSCode)
- No scheduling capability
- No webhook endpoints for external triggers

### Planned Features

#### Phase 1: Cron Scheduling

```yaml
# In pipeline.json or separate schedule.json
{
  "pipeline": "data-sync.pipeline.json",
  "schedule": {
    "cron": "0 */6 * * *",           # Every 6 hours
    "timezone": "America/New_York",
    "enabled": true
  },
  "default_inputs": {
    "source": "production"
  }
}
```

**Implementation:**
- [ ] Schedule configuration schema
- [ ] Scheduler service (APScheduler or similar)
- [ ] Schedule management API (`/api/v1/schedules`)
- [ ] VSCode UI for viewing/managing schedules
- [ ] Web portal schedule dashboard

#### Phase 2: Webhook Triggers

```yaml
{
  "pipeline": "process-order.pipeline.json",
  "webhook": {
    "path": "/hooks/new-order",
    "method": "POST",
    "auth": "bearer",                 # or "hmac", "api_key", "none"
    "input_mapping": {
      "order_id": "$.body.id",
      "customer": "$.body.customer"
    }
  }
}
```

**Webhook endpoints:**
```
POST /api/v1/hooks/{hook_id}
POST /api/v1/hooks/by-name/{hook_name}
```

**Features:**
- [ ] Webhook registration and management
- [ ] Multiple auth methods (Bearer, HMAC, API Key)
- [ ] Request body → pipeline input mapping
- [ ] Webhook logs and retry on failure
- [ ] Rate limiting per webhook

#### Phase 3: Event-Driven Triggers

```yaml
{
  "pipeline": "process-file.pipeline.json",
  "triggers": [
    {
      "type": "file_watch",
      "path": "/data/incoming/*.csv",
      "events": ["created", "modified"],
      "debounce_seconds": 5
    },
    {
      "type": "mcp_event",
      "server": "database",
      "event": "row_inserted",
      "table": "orders"
    },
    {
      "type": "pipeline_completed",
      "pipeline": "data-fetch.pipeline.json",
      "status": "success"
    }
  ]
}
```

**Trigger types:**
- [ ] File system watch (local, S3 via MCP)
- [ ] Pipeline completion (chain pipelines)
- [ ] Database events (via MCP)
- [ ] Message queue (Redis, RabbitMQ)
- [ ] Custom MCP events

#### Phase 4: Trigger Management UI

**VSCode Extension:**
```
SCHEDULES & TRIGGERS
├── 📅 Schedules
│   ├── data-sync (every 6h) ✓
│   └── daily-report (9am daily) ✓
├── 🔗 Webhooks
│   ├── /hooks/new-order
│   └── /hooks/payment-received
└── 👁️ Watchers
    └── /data/incoming/*.csv
```

**Web Portal:**
- Schedule calendar view
- Webhook testing UI
- Trigger history and logs
- Enable/disable toggles

### CLI Commands

```bash
# List schedules
fm schedule list

# Create schedule
fm schedule create daily-sync.pipeline.json --cron "0 9 * * *"

# Disable schedule
fm schedule disable daily-sync

# List webhooks
fm webhook list

# Test webhook
fm webhook test new-order --data '{"id": "123"}'

# View trigger history
fm triggers history --limit 50
```

### API Endpoints

```
# Schedules
GET    /api/v1/schedules
POST   /api/v1/schedules
GET    /api/v1/schedules/{id}
PUT    /api/v1/schedules/{id}
DELETE /api/v1/schedules/{id}
POST   /api/v1/schedules/{id}/run   # Manual trigger

# Webhooks
GET    /api/v1/webhooks
POST   /api/v1/webhooks
GET    /api/v1/webhooks/{id}
DELETE /api/v1/webhooks/{id}
POST   /api/v1/hooks/{hook_id}      # Webhook endpoint

# Trigger history
GET    /api/v1/triggers/history
```

---

## 9. Pipeline Testing Framework

Enable developers to write and run tests for pipelines before deployment.

### Current State
- No testing framework for pipelines
- Manual testing only
- No way to mock external dependencies

### Planned Features

#### Phase 1: Test Runner

```python
# tests/test_data_validation.py
import flowmason.testing as fm_test

def test_valid_records_pass():
    """Test that valid records pass validation."""
    result = fm_test.run(
        "pipelines/data-validation.pipeline.json",
        inputs={
            "records": [
                {"id": "1", "email": "user@example.com", "status": "active"},
                {"id": "2", "email": "admin@example.com", "status": "active"},
            ]
        }
    )

    assert result.success
    assert result.output["summary"]["total_records"] == 2
    assert result.output["summary"]["active_count"] == 2

def test_invalid_email_filtered():
    """Test that invalid emails are caught."""
    result = fm_test.run(
        "pipelines/data-validation.pipeline.json",
        inputs={
            "records": [
                {"id": "1", "email": "invalid-email", "status": "active"},
            ]
        }
    )

    assert result.success
    assert result.output["summary"]["validation_errors"] is not None
```

**CLI:**
```bash
# Run all tests
fm test

# Run specific test file
fm test tests/test_data_validation.py

# Run with coverage
fm test --coverage

# Run in watch mode
fm test --watch
```

#### Phase 2: Stage Mocking

```python
def test_with_mocked_http():
    """Test pipeline with mocked HTTP responses."""
    result = fm_test.run(
        "pipelines/fetch-and-process.pipeline.json",
        inputs={"url": "https://api.example.com/data"},
        mocks={
            "fetch-data": {
                "result": {"items": [{"id": 1}, {"id": 2}]},
                "status_code": 200
            },
            "send-notification": fm_test.SKIP  # Skip this stage
        }
    )

    assert result.success
    assert len(result.output["processed_items"]) == 2

def test_http_failure_handling():
    """Test error handling when HTTP fails."""
    result = fm_test.run(
        "pipelines/fetch-and-process.pipeline.json",
        inputs={"url": "https://api.example.com/data"},
        mocks={
            "fetch-data": fm_test.MockError(
                error="Connection timeout",
                status_code=504
            )
        }
    )

    # Pipeline should handle error gracefully
    assert result.stages["use-fallback"].status == "completed"
```

#### Phase 3: Snapshot Testing

```python
def test_transform_output_snapshot():
    """Test that transform output matches snapshot."""
    result = fm_test.run(
        "pipelines/data-transform.pipeline.json",
        inputs={"data": sample_data}
    )

    # First run creates snapshot, subsequent runs compare
    fm_test.assert_snapshot_match(
        result.output,
        snapshot_name="transform_output"
    )
```

**Snapshot files:**
```
tests/
├── snapshots/
│   └── test_transform_output_snapshot/
│       └── transform_output.json
└── test_transform.py
```

#### Phase 4: Integration Testing

```python
@fm_test.integration  # Marks as integration test (not run by default)
def test_full_pipeline_with_real_api():
    """Integration test with real API (requires network)."""
    result = fm_test.run(
        "pipelines/production-workflow.pipeline.json",
        inputs={"environment": "staging"},
        timeout=60
    )

    assert result.success

@fm_test.fixtures("sample_customers.json")
def test_with_fixture_data(sample_customers):
    """Test using fixture data."""
    result = fm_test.run(
        "pipelines/customer-analysis.pipeline.json",
        inputs={"customers": sample_customers}
    )

    assert result.success
```

### Test Configuration

```json
// flowmason.json
{
  "testing": {
    "test_dir": "tests",
    "fixtures_dir": "tests/fixtures",
    "snapshots_dir": "tests/snapshots",
    "timeout_seconds": 30,
    "parallel": true,
    "coverage": {
      "enabled": true,
      "threshold": 80
    }
  }
}
```

### VSCode Integration

- Test explorer integration
- Run tests from editor
- Debug tests with breakpoints
- Coverage highlighting

### Files to Create

```
core/flowmason_core/testing/
├── __init__.py
├── runner.py          # Test runner
├── mocks.py           # Stage mocking
├── assertions.py      # Custom assertions
├── snapshots.py       # Snapshot testing
└── fixtures.py        # Fixture loading

lab/flowmason_lab/operators/testing/
├── __init__.py
└── test_helpers.py    # Helper operators for testing
```

---

## 10. Secrets Management

Secure handling of API keys, credentials, and sensitive configuration.

### Current State
- Secrets stored in environment variables
- No encryption at rest
- No secret rotation
- No audit trail for secret access

### Planned Features

#### Phase 1: Encrypted Secret Storage

```yaml
# Reference secrets in pipelines
stages:
  - id: call-api
    component_type: http_request
    config:
      url: "https://api.stripe.com/v1/charges"
      headers:
        Authorization: "Bearer {{secrets.STRIPE_API_KEY}}"
```

**Secret storage:**
```python
# Secrets encrypted at rest using Fernet (AES-128)
# Master key from environment or hardware security module

@dataclass
class Secret:
    id: str
    name: str                    # e.g., "STRIPE_API_KEY"
    encrypted_value: bytes       # Fernet encrypted
    environment: str             # "development", "staging", "production"
    created_at: datetime
    updated_at: datetime
    created_by: str
    last_accessed_at: Optional[datetime]
    expires_at: Optional[datetime]
    tags: List[str]
```

#### Phase 2: Environment-Specific Secrets

```
Secrets
├── development
│   ├── STRIPE_API_KEY (test key)
│   ├── DATABASE_URL (local)
│   └── OPENAI_API_KEY
├── staging
│   ├── STRIPE_API_KEY (test key)
│   ├── DATABASE_URL (staging db)
│   └── OPENAI_API_KEY
└── production
    ├── STRIPE_API_KEY (live key)
    ├── DATABASE_URL (prod db)
    └── OPENAI_API_KEY
```

**Resolution order:**
1. Environment-specific secret
2. Shared secret
3. Environment variable (fallback)

#### Phase 3: Secret Access Control

```python
# Scoped access to secrets
class SecretScope:
    PIPELINE = "pipeline"      # Accessible during pipeline execution
    OPERATOR = "operator"      # Accessible by specific operators
    ADMIN = "admin"            # Only via admin API

# Pipeline-level secret permissions
{
    "pipeline": "payment-processing.pipeline.json",
    "secrets": ["STRIPE_API_KEY", "DATABASE_URL"],  # Allowed secrets
    "deny_secrets": ["ADMIN_PASSWORD"]               # Explicitly denied
}
```

#### Phase 4: Audit Trail

```python
@dataclass
class SecretAccessLog:
    id: str
    timestamp: datetime
    secret_name: str
    action: str                  # "read", "write", "delete", "rotate"
    accessor_type: str           # "pipeline", "user", "api_key"
    accessor_id: str
    pipeline_id: Optional[str]
    stage_id: Optional[str]
    ip_address: Optional[str]
    success: bool
```

**Audit queries:**
```bash
# View secret access history
fm secrets audit STRIPE_API_KEY --days 30

# View all access by pipeline
fm secrets audit --pipeline payment-processing --days 7
```

### CLI Commands

```bash
# Set a secret
fm secrets set STRIPE_API_KEY --env production
# (prompts for value, never shown in terminal)

# Set from file
fm secrets set TLS_CERT --from-file ./cert.pem --env production

# List secrets (names only, not values)
fm secrets list
fm secrets list --env staging

# Delete secret
fm secrets delete STRIPE_API_KEY --env development

# Rotate secret
fm secrets rotate STRIPE_API_KEY --env production

# View audit log
fm secrets audit --days 7
```

### API Endpoints

```
# Secret management (admin only)
GET    /api/v1/secrets                    # List secret names
POST   /api/v1/secrets                    # Create secret
PUT    /api/v1/secrets/{name}             # Update secret
DELETE /api/v1/secrets/{name}             # Delete secret
POST   /api/v1/secrets/{name}/rotate      # Rotate secret

# Secret access (internal, during execution)
GET    /api/v1/secrets/{name}/value       # Get decrypted value (logged)

# Audit
GET    /api/v1/secrets/audit              # Access audit log
```

### VSCode Integration

```
SECRETS
├── 🔐 development
│   ├── STRIPE_API_KEY ••••••••
│   ├── DATABASE_URL ••••••••
│   └── + Add Secret
├── 🔐 staging
│   └── ...
└── 🔐 production
    └── ...
```

- View secret names (not values)
- Add/update secrets via secure input
- Copy secret reference (`{{secrets.NAME}}`)
- View audit log

### Web Portal

- Secret management dashboard
- Environment comparison view
- Rotation reminders
- Access audit visualization

### Security Considerations

| Aspect | Implementation |
|--------|----------------|
| Encryption at rest | Fernet (AES-128-CBC) |
| Key management | Environment variable or HSM |
| Access control | Role-based, pipeline-scoped |
| Audit logging | All access logged |
| Secret rotation | Supported, optional expiry |
| Transport | HTTPS only, no logging of values |

### Files to Create

```
core/flowmason_core/secrets/
├── __init__.py
├── store.py           # Secret storage and encryption
├── resolver.py        # Template resolution {{secrets.X}}
├── audit.py           # Access audit logging
└── rotation.py        # Secret rotation

studio/flowmason_studio/api/routes/secrets.py
studio/flowmason_studio/services/secrets.py
```

---

## 11. API Console / Testing Interface (Web Portal)

An interactive chat-like interface in the FlowMason Web Portal for testing and exploring APIs.

### Current State
- API testing requires external tools (curl, Postman, etc.)
- Web portal lacks an integrated way to test pipelines
- Operations teams need to switch between portal and external tools
- No unified interface for API exploration and testing

### Concept

A dedicated page in the Web Portal that provides:
1. Chat-like interface for API interactions
2. Pipeline execution with real-time output
3. API exploration and documentation
4. Request/response history
5. Saved test requests and collections

### Mockup

```
┌─────────────────────────────────────────────────────────────────┐
│ FlowMason API Console                              [Settings] ⚙ │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 🤖 FlowMason Studio running at http://localhost:8999    │   │
│  │    Connected • 3 pipelines available                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 👤 Run data-validation with test data                   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 🤖 Running pipeline: data-validation                    │   │
│  │    ├── ✓ log-start (12ms)                               │   │
│  │    ├── ✓ validate-schema (45ms)                         │   │
│  │    ├── ✓ transform-records (23ms)                       │   │
│  │    ├── ✓ filter-active (8ms)                            │   │
│  │    └── ✓ create-summary (15ms)                          │   │
│  │                                                         │   │
│  │    Result: ✓ Success (103ms)                            │   │
│  │    ┌──────────────────────────────────────────────┐     │   │
│  │    │ {                                            │     │   │
│  │    │   "total_records": 5,                        │     │   │
│  │    │   "active_count": 3,                         │     │   │
│  │    │   "high_value_count": 2                      │     │   │
│  │    │ }                                            │     │   │
│  │    └──────────────────────────────────────────────┘     │   │
│  │    [Copy] [Save] [View Full Response]                   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 👤 List all components                                  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 🤖 Found 12 components:                                 │   │
│  │    Core: filter, json_transform, logger, variable_set   │   │
│  │    Control Flow: foreach, conditional, router           │   │
│  │    HTTP: http_request                                   │   │
│  │    AI: generator, critic, selector, synthesizer         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Type a command or question...                         [↵] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│ Quick: [Run Pipeline ▾] [List Pipelines] [Health] [Components] │
└─────────────────────────────────────────────────────────────────┘
```

### Features

#### Phase 1: Basic API Console

**Chat Commands:**
```
# Health check
health
→ Studio is healthy (v1.0.0)

# List pipelines
pipelines
list pipelines
→ Found 3 pipelines: data-validation, batch-processing, customer-triage

# Run pipeline
run data-validation
run data-validation {"records": [...]}
→ [Streaming execution output]

# Get run status
status run_abc123
→ Status: completed, Duration: 103ms

# List components
components
components --category core
→ Lists all available components
```

**API Explorer:**
```
# Direct API calls
GET /health
POST /api/v1/debug/run {"pipeline_path": "..."}
GET /api/v1/runs/{run_id}

# With autocomplete for endpoints and parameters
```

#### Phase 2: Interactive Features

**Input Builder:**
```
┌─────────────────────────────────────────┐
│ Run Pipeline: data-validation           │
├─────────────────────────────────────────┤
│ Input Schema:                           │
│ ┌─────────────────────────────────────┐ │
│ │ records* (array)                    │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ [                               │ │ │
│ │ │   {"id": "1", "email": "..."}   │ │ │
│ │ │ ]                               │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │                                     │ │
│ │ threshold (number, default: 100)    │ │
│ │ [____100____]                       │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ [Load Sample] [Load from File] [Run ▶]  │
└─────────────────────────────────────────┘
```

**Real-time Execution View:**
```
Executing: data-validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 60%

├── ✓ log-start           12ms
├── ✓ validate-schema     45ms  [View Output]
├── ● transform-records   ...   ← Currently running
├── ○ filter-active
└── ○ create-summary

[Cancel] [Pause at Next Stage]
```

#### Phase 3: History & Saved Requests

```
HISTORY                              SAVED REQUESTS
├── Today                            ├── Test valid data
│   ├── run data-validation (✓)      ├── Test invalid emails
│   ├── run batch-processing (✗)     ├── Load test (100 items)
│   └── GET /health (✓)              └── Production sample
└── Yesterday
    └── ...
```

**Save request:**
```json
{
  "name": "Test valid data",
  "command": "run",
  "pipeline": "data-validation",
  "inputs": {
    "records": [...]
  },
  "description": "Happy path test with valid records"
}
```

#### Phase 4: AI-Assisted Testing

With MCP integration, the chat can understand natural language:

```
👤 "Run the data validation pipeline with 5 sample customers"
🤖 Generating sample data...
🤖 Running data-validation with 5 customers
🤖 ✓ Complete: 5 records processed, 3 active, 2 high-value

👤 "Now run it with an invalid email to test error handling"
🤖 Running with invalid email: "not-an-email"
🤖 ✓ Complete: Validation caught 1 error (invalid email format)

👤 "Compare the outputs"
🤖 Comparison:
   - Test 1: 5 valid → 5 processed
   - Test 2: 1 invalid → caught by validation
   Both handled correctly ✓
```

### Implementation

#### React Components (Web Portal Frontend)

```typescript
// studio/frontend/src/pages/ApiConsole.tsx
import { useState, useCallback } from 'react';
import { ChatMessage, ApiRequest, ExecutionResult } from '../types/console';
import { useStudioApi } from '../hooks/useStudioApi';
import { parseCommand } from '../utils/commandParser';

export function ApiConsolePage() {
    const [messages, setMessages] = useState<ChatMessage[]>([]);
    const [history, setHistory] = useState<ApiRequest[]>([]);
    const [savedRequests, setSavedRequests] = useState<ApiRequest[]>([]);
    const api = useStudioApi();

    const handleCommand = useCallback(async (input: string) => {
        const command = parseCommand(input);

        // Add user message
        setMessages(prev => [...prev, { type: 'user', content: input }]);

        try {
            let result: ExecutionResult;

            switch (command.type) {
                case 'run':
                    result = await api.runPipeline(command.pipeline, command.inputs);
                    break;
                case 'list':
                    result = await api.listResources(command.resource);
                    break;
                case 'health':
                    result = await api.healthCheck();
                    break;
                case 'api':
                    result = await api.rawRequest(command.method, command.path, command.body);
                    break;
            }

            // Add bot response
            setMessages(prev => [...prev, { type: 'bot', content: result }]);

            // Add to history
            setHistory(prev => [{ input, result, timestamp: Date.now() }, ...prev]);
        } catch (error) {
            setMessages(prev => [...prev, { type: 'error', content: error.message }]);
        }
    }, [api]);

    return (
        <div className="api-console">
            <ConsoleHeader />
            <ChatHistory messages={messages} />
            <CommandInput onSubmit={handleCommand} />
            <QuickActions onAction={handleCommand} />
            <Sidebar history={history} saved={savedRequests} />
        </div>
    );
}
```

#### Command Parser

```typescript
// studio/frontend/src/utils/commandParser.ts
interface Command {
    type: 'run' | 'list' | 'status' | 'health' | 'api' | 'unknown';
    pipeline?: string;
    inputs?: object;
    resource?: string;
    method?: string;
    path?: string;
    body?: object;
}

export function parseCommand(input: string): Command {
    const patterns = [
        { regex: /^(run|execute)\s+(\S+)(?:\s+(.+))?$/i, type: 'run' as const },
        { regex: /^(list\s+)?(pipelines?|components?|runs?)$/i, type: 'list' as const },
        { regex: /^(status|check)\s+(\S+)$/i, type: 'status' as const },
        { regex: /^health$/i, type: 'health' as const },
        { regex: /^(GET|POST|PUT|DELETE)\s+(\S+)(?:\s+(.+))?$/i, type: 'api' as const },
    ];

    for (const pattern of patterns) {
        const match = input.match(pattern.regex);
        if (match) {
            return buildCommand(pattern.type, match);
        }
    }

    return { type: 'unknown' };
}

function buildCommand(type: Command['type'], match: RegExpMatchArray): Command {
    switch (type) {
        case 'run':
            return {
                type,
                pipeline: match[2],
                inputs: match[3] ? JSON.parse(match[3]) : undefined
            };
        case 'api':
            return {
                type,
                method: match[1],
                path: match[2],
                body: match[3] ? JSON.parse(match[3]) : undefined
            };
        case 'list':
            return { type, resource: match[2] || 'pipelines' };
        default:
            return { type };
    }
}
```

#### Backend API Endpoints

```python
# studio/flowmason_studio/api/routes/console.py
from fastapi import APIRouter, Depends
from pydantic import BaseModel
from typing import Optional, List
from ..services.console_service import ConsoleService

router = APIRouter(prefix="/api/v1/console", tags=["console"])

class SavedRequest(BaseModel):
    name: str
    command: str
    inputs: Optional[dict] = None
    description: Optional[str] = None

@router.get("/history")
async def get_history(limit: int = 100, service: ConsoleService = Depends()):
    """Get command history for the current session"""
    return await service.get_history(limit)

@router.post("/saved")
async def save_request(request: SavedRequest, service: ConsoleService = Depends()):
    """Save a request for later reuse"""
    return await service.save_request(request)

@router.get("/saved")
async def list_saved_requests(service: ConsoleService = Depends()):
    """List all saved requests"""
    return await service.list_saved_requests()

@router.delete("/saved/{request_id}")
async def delete_saved_request(request_id: str, service: ConsoleService = Depends()):
    """Delete a saved request"""
    return await service.delete_saved_request(request_id)
```

### Files to Create

```
studio/frontend/src/
├── pages/
│   └── ApiConsole.tsx           # Main console page
├── components/console/
│   ├── ChatHistory.tsx          # Message display
│   ├── CommandInput.tsx         # Input with autocomplete
│   ├── QuickActions.tsx         # Quick action buttons
│   ├── ExecutionView.tsx        # Real-time execution display
│   ├── InputBuilder.tsx         # JSON input form builder
│   └── ConsoleSidebar.tsx       # History and saved requests
├── hooks/
│   └── useConsoleHistory.ts     # History state management
└── utils/
    └── commandParser.ts         # Command parsing logic

studio/flowmason_studio/api/routes/
└── console.py                   # Console-specific endpoints

studio/flowmason_studio/services/
└── console_service.py           # Console service (history, saved requests)
```

### Navigation Integration

```typescript
// studio/frontend/src/App.tsx - Add route
<Route path="/console" element={<ApiConsolePage />} />

// studio/frontend/src/components/Sidebar.tsx - Add nav item
<NavItem to="/console" icon={Terminal}>API Console</NavItem>
```

### Configuration

Console settings stored in portal (synced with backend):

```typescript
// Console preferences (stored per-user in portal)
interface ConsoleSettings {
    maxHistoryItems: number;      // Default: 100
    autoConnect: boolean;         // Default: true
    showTimestamps: boolean;      // Default: true
    jsonPrettyPrint: boolean;     // Default: true
    theme: 'auto' | 'light' | 'dark';
}
```

---

## 12. Pipeline Debugger with Time Travel

A visual debugger that lets you step through pipeline execution, inspect state at any point, and "rewind" to re-execute from any stage.

### Concept

Unlike traditional debuggers, FlowMason's debugger captures the complete execution state, allowing you to:
1. Set breakpoints on any stage
2. Step forward/backward through execution
3. Inspect inputs/outputs at any point
4. Modify data and re-run from that point
5. Compare different execution paths

### Mockup

```
┌─────────────────────────────────────────────────────────────────────────┐
│ FlowMason Debugger                    Run: run_abc123    [⏸ Paused]     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Timeline:                                                              │
│  ┌────┬────┬────┬────┬────┬────┬────┐                                   │
│  │ 1  │ 2  │ 3  │ 4  │ 5● │ 6  │ 7  │  ← Currently at stage 5          │
│  └────┴────┴────┴────┴────┴────┴────┘                                   │
│  [⏮] [◀] [▶] [⏭]  [↻ Restart]  [⏵ Continue]                            │
│                                                                         │
│  ┌─────────────────────────────┬───────────────────────────────────────┐│
│  │ Stage: filter-active        │ State Inspector                       ││
│  │ Status: ● Breakpoint        │                                       ││
│  │ Duration: --                │ Input:                                ││
│  │                             │ ┌─────────────────────────────────┐   ││
│  │ ○ log-start          ✓     │ │ {                               │   ││
│  │ ○ validate-schema    ✓     │ │   "data": [                     │   ││
│  │ ○ transform-records  ✓     │ │     {"id": "1", "status": ...}  │   ││
│  │ ● filter-active      ⏸     │ │   ],                            │   ││
│  │ ○ filter-high-score        │ │   "condition": "item.get..."    │   ││
│  │ ○ create-summary           │ │ }                               │   ││
│  │                             │ └─────────────────────────────────┘   ││
│  │ Breakpoints:                │                                       ││
│  │ ☑ filter-active            │ [Edit & Re-run] [Step Into]           ││
│  │ ☐ create-summary           │                                       ││
│  └─────────────────────────────┴───────────────────────────────────────┘│
│                                                                         │
│  Execution History:                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │ #5 filter-active: Received 10 items, condition="item.get('status')" ││
│  │ #4 transform-records: Transformed 10 → 10 items (100%)              ││
│  │ #3 validate-schema: Validation passed, 0 errors                     ││
│  │ #2 log-start: "Starting ETL pipeline"                               ││
│  └─────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
```

### Features

#### Time Travel Debugging
```python
# Backend stores execution snapshots
class ExecutionSnapshot:
    stage_id: str
    timestamp: datetime
    inputs: dict
    outputs: dict
    context: dict
    variables: dict

# API endpoints
POST /api/v1/debug/breakpoint/{run_id}/{stage_id}  # Set breakpoint
POST /api/v1/debug/step/{run_id}                    # Step to next stage
POST /api/v1/debug/rewind/{run_id}/{stage_id}      # Rewind to stage
POST /api/v1/debug/modify/{run_id}/{stage_id}      # Modify and continue
GET  /api/v1/debug/snapshot/{run_id}/{stage_id}    # Get snapshot
```

#### Edit & Re-run
Modify the input data at any snapshot point and re-execute from there:
```
1. Pause at stage 5
2. Edit the input data (fix a bug, test edge case)
3. Click "Re-run from here"
4. Execution continues from stage 5 with modified data
5. Original execution preserved for comparison
```

#### Comparison Mode
```
┌─────────────────────────────┬─────────────────────────────┐
│ Original Run                │ Modified Run                │
├─────────────────────────────┼─────────────────────────────┤
│ filter-active: 3 passed     │ filter-active: 5 passed     │
│ Duration: 45ms              │ Duration: 52ms              │
│                             │                             │
│ Output:                     │ Output:                     │
│ ["USR001", "USR002", ...]   │ ["USR001", "USR002", ...]   │
│                             │ + "USR003", "USR005"        │
└─────────────────────────────┴─────────────────────────────┘
```

---

## 13. LLM Cost Tracking & Optimization

Track, analyze, and optimize LLM API costs across all pipeline executions.

### Concept

AI-powered pipelines can get expensive. FlowMason tracks every LLM call, provides cost analytics, and suggests optimizations.

### Dashboard

```
┌─────────────────────────────────────────────────────────────────────────┐
│ LLM Cost Analytics                                  Period: Last 30 days │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Total Spend: $847.23                    Budget: $1,000/month           │
│  ████████████████████████░░░░ 85%                                       │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ $                                                                │   │
│  │ 50 ┤                              ╭─╮                            │   │
│  │ 40 ┤                    ╭────────╯  ╰──╮                         │   │
│  │ 30 ┤       ╭────────────╯              ╰────╮                    │   │
│  │ 20 ┤  ╭────╯                                ╰────                │   │
│  │ 10 ┤──╯                                                          │   │
│  │    └─────────────────────────────────────────────────────────────│   │
│  │      1    5    10   15   20   25   30                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Cost by Pipeline:                    Cost by Model:                    │
│  ┌────────────────────────────┐       ┌────────────────────────────┐   │
│  │ customer-triage    $312.45 │       │ claude-3-opus     $523.00  │   │
│  │ content-generator  $287.12 │       │ claude-3-sonnet   $198.45  │   │
│  │ code-reviewer      $156.89 │       │ gpt-4-turbo       $125.78  │   │
│  │ summarizer          $90.77 │       │ claude-3-haiku     $0.00   │   │
│  └────────────────────────────┘       └────────────────────────────┘   │
│                                                                         │
│  💡 Optimization Suggestions:                                           │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 1. customer-triage uses opus for classification - haiku would   │   │
│  │    work equally well. Potential savings: $280/month             │   │
│  │                                                   [Apply Fix]   │   │
│  │                                                                 │   │
│  │ 2. content-generator has redundant summarization step.          │   │
│  │    Consider caching. Potential savings: $95/month               │   │
│  │                                                   [View Details]│   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

### Features

#### Automatic Cost Tracking
```python
# Tracked automatically for every LLM call
class LLMUsage:
    run_id: str
    stage_id: str
    provider: str          # anthropic, openai, etc.
    model: str             # claude-3-opus, gpt-4, etc.
    input_tokens: int
    output_tokens: int
    cost_usd: float
    latency_ms: int
    timestamp: datetime
```

#### Budget Alerts
```yaml
# flowmason.yaml
cost_management:
  monthly_budget: 1000
  alerts:
    - threshold: 80%
      action: email
    - threshold: 95%
      action: pause_non_critical
    - threshold: 100%
      action: pause_all

  # Per-pipeline limits
  pipeline_limits:
    customer-triage: 500
    content-generator: 300
```

#### Model Comparison Testing
Run the same pipeline with different models to compare cost vs. quality:
```
A/B Test: customer-triage classification step

| Model           | Accuracy | Cost/1000 | Latency |
|-----------------|----------|-----------|---------|
| claude-3-opus   | 98.2%    | $15.00    | 2.1s    |
| claude-3-sonnet | 96.8%    | $3.00     | 0.8s    |
| claude-3-haiku  | 94.1%    | $0.25     | 0.2s    |
| gpt-4-turbo     | 97.5%    | $10.00    | 1.5s    |

Recommendation: Use haiku for initial triage, escalate to sonnet for
uncertain cases. Projected savings: 78%
```

---

## 14. Pipeline Versioning & Rollback

Git-like versioning for pipelines with instant rollback capabilities.

### Concept

Every pipeline change is tracked. Deploy with confidence knowing you can instantly rollback to any previous version.

### Version History

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Pipeline: customer-triage                                    [Deploy ▾] │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Current: v2.3.1 (production)                                           │
│                                                                         │
│  Version History:                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ v2.3.1  ● LIVE    "Fix threshold for high-priority"   2h ago   │   │
│  │                   by sam@company.com                            │   │
│  │                   [View] [Diff] [Rollback]                      │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ v2.3.0           "Add sentiment analysis stage"       1d ago   │   │
│  │                   by alex@company.com                           │   │
│  │                   [View] [Diff] [Restore]                       │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ v2.2.0           "Optimize LLM prompts"               3d ago   │   │
│  │                   by sam@company.com                            │   │
│  │                   [View] [Diff] [Restore]                       │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ v2.1.0           "Add email notification"             1w ago   │   │
│  │                   [View] [Diff] [Restore]                       │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  [Compare Versions ▾]  [Create Branch]  [View All Tags]                 │
└─────────────────────────────────────────────────────────────────────────┘
```

### Features

#### Visual Diff
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Comparing: v2.2.0 → v2.3.0                                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Pipeline Changes:                                                      │
│  + Added stage: sentiment-analysis (after classify-intent)              │
│  ~ Modified stage: route-ticket (added sentiment condition)             │
│                                                                         │
│  Stage: sentiment-analysis (NEW)                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ + {                                                             │   │
│  │ +   "id": "sentiment-analysis",                                 │   │
│  │ +   "component_type": "generator",                              │   │
│  │ +   "config": {                                                 │   │
│  │ +     "prompt": "Analyze the sentiment of: {{input.message}}"   │   │
│  │ +   }                                                           │   │
│  │ + }                                                             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Stage: route-ticket (MODIFIED)                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │   "conditions": [                                               │   │
│  │     { "when": "priority == 'high'", "goto": "urgent-queue" },   │   │
│  │ +   { "when": "sentiment == 'angry'", "goto": "escalation" },   │   │
│  │     { "default": true, "goto": "standard-queue" }               │   │
│  │   ]                                                             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

#### Instant Rollback
```bash
# CLI
fm rollback customer-triage --to v2.2.0

# API
POST /api/v1/pipelines/customer-triage/rollback
{ "target_version": "v2.2.0" }

# Result: Pipeline instantly reverted, new version v2.3.2 created
```

#### Deployment Environments
```yaml
# environments.yaml
environments:
  development:
    auto_deploy: true
    version: latest

  staging:
    auto_deploy: false
    version: v2.3.1
    approval_required: false

  production:
    auto_deploy: false
    version: v2.3.0
    approval_required: true
    approvers: ["lead@company.com", "ops@company.com"]
```

---

## 15. Prompt Library & A/B Testing

Centralized prompt management with version control and A/B testing capabilities.

### Concept

Prompts are first-class citizens. Store them centrally, version them, and A/B test variations to optimize performance.

### Prompt Library

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Prompt Library                                          [+ New Prompt]  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Search: [________________________]  Filter: [All Categories ▾]         │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 📝 customer-classification                              v3.2    │   │
│  │    "Classify customer intent into categories..."                │   │
│  │    Used in: customer-triage, support-bot                        │   │
│  │    Performance: 96.2% accuracy │ A/B Test: Running              │   │
│  │    [Edit] [Duplicate] [View A/B Results]                        │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ 📝 content-summarizer                                   v2.1    │   │
│  │    "Summarize the following content in 2-3 sentences..."        │   │
│  │    Used in: news-digest, report-generator                       │   │
│  │    Performance: 4.7/5 quality │ A/B Test: None                  │   │
│  │    [Edit] [Duplicate] [Start A/B Test]                          │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ 📝 code-review-feedback                                 v1.5    │   │
│  │    "Review this code and provide constructive feedback..."      │   │
│  │    Used in: pr-reviewer, code-mentor                            │   │
│  │    Performance: 89% helpful │ A/B Test: Completed               │   │
│  │    [Edit] [Duplicate] [View History]                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

### A/B Testing Interface

```
┌─────────────────────────────────────────────────────────────────────────┐
│ A/B Test: customer-classification                        Status: Active │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Test Configuration:                                                    │
│  ├─ Traffic Split: 50% / 50%                                           │
│  ├─ Sample Size: 1,000 (682 completed)                                 │
│  ├─ Success Metric: classification_accuracy                            │
│  └─ Started: 2 days ago                                                │
│                                                                         │
│  ┌──────────────────────────────┬──────────────────────────────┐       │
│  │ Variant A (Control)          │ Variant B (Challenger)       │       │
│  │ v3.1                         │ v3.2-beta                    │       │
│  ├──────────────────────────────┼──────────────────────────────┤       │
│  │ "Classify the customer       │ "You are a customer service  │       │
│  │ message into one of these    │ expert. Analyze this message │       │
│  │ categories: billing,         │ and determine the customer's │       │
│  │ technical, sales, general"   │ primary intent. Categories:  │       │
│  │                              │ billing, technical, sales,   │       │
│  │                              │ general. Also rate urgency." │       │
│  ├──────────────────────────────┼──────────────────────────────┤       │
│  │ Accuracy: 94.8%              │ Accuracy: 97.1%              │       │
│  │ Avg Tokens: 145              │ Avg Tokens: 198              │       │
│  │ Cost/1000: $0.43             │ Cost/1000: $0.59             │       │
│  │ Latency: 0.8s                │ Latency: 1.1s                │       │
│  └──────────────────────────────┴──────────────────────────────┘       │
│                                                                         │
│  Statistical Significance: 94% (need 95% to declare winner)            │
│  Estimated completion: 6 hours                                         │
│                                                                         │
│  [End Test - Keep A] [End Test - Keep B] [Extend Test] [Cancel]        │
└─────────────────────────────────────────────────────────────────────────┘
```

### Prompt Templates with Variables

```yaml
# prompts/customer-classification.yaml
name: customer-classification
version: 3.2
description: Classify customer intent from support messages
category: classification

template: |
  You are a customer service expert at {{company_name}}.

  Analyze this customer message and determine:
  1. Primary intent: {{categories}}
  2. Urgency: low, medium, high, critical
  3. Sentiment: positive, neutral, negative

  Customer message:
  {{message}}

  Respond in JSON format.

variables:
  company_name:
    type: string
    default: "our company"
  categories:
    type: array
    default: ["billing", "technical", "sales", "general"]
  message:
    type: string
    required: true

metadata:
  model_recommendation: claude-3-haiku
  expected_tokens: 150-250
  use_cases:
    - customer-triage
    - support-bot
```

### Usage in Pipeline

```json
{
  "id": "classify-intent",
  "component_type": "generator",
  "config": {
    "prompt_ref": "prompts://customer-classification@v3.2",
    "prompt_variables": {
      "company_name": "Acme Corp",
      "message": "{{input.customer_message}}"
    }
  }
}
```

---

## 16. Pipeline Marketplace

A community marketplace for sharing and discovering pipeline templates, components, and integrations.

### Concept

An ecosystem where users can:
1. Publish and share pipeline templates
2. Discover pre-built solutions for common use cases
3. Monetize their components (optional)
4. Rate and review community contributions

### Marketplace Interface

```
┌─────────────────────────────────────────────────────────────────────────┐
│ FlowMason Marketplace                               [Publish] [My Items]│
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  [Templates] [Components] [Integrations] [Prompts]                      │
│                                                                         │
│  Search: [________________________]  Sort: [Most Popular ▾]             │
│                                                                         │
│  Featured Templates                                                     │
│  ┌────────────────────┬────────────────────┬────────────────────┐      │
│  │ 🎯 Customer Support│ 📊 Data Analytics  │ 🤖 Content Gen     │      │
│  │    Triage          │    Pipeline        │    Suite           │      │
│  │                    │                    │                    │      │
│  │ Automatically route│ ETL + transform +  │ Blog posts, social │      │
│  │ support tickets    │ visualization      │ media, newsletters │      │
│  │                    │                    │                    │      │
│  │ ⭐ 4.8 (234)       │ ⭐ 4.6 (189)       │ ⭐ 4.9 (412)       │      │
│  │ 📥 1.2k installs   │ 📥 890 installs    │ 📥 2.1k installs   │      │
│  │ FREE               │ FREE               │ $29                │      │
│  │ [Install] [Preview]│ [Install] [Preview]│ [Purchase][Preview]│      │
│  └────────────────────┴────────────────────┴────────────────────┘      │
│                                                                         │
│  Popular Components                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 🔌 slack-notifier         Send notifications to Slack    FREE   │   │
│  │    by @flowmason-team     ⭐ 4.9 (567)  📥 3.4k                  │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ 🔌 pdf-extractor          Extract text/tables from PDFs  $9     │   │
│  │    by @doctools           ⭐ 4.7 (123)  📥 890                   │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ 🔌 salesforce-sync        Bi-directional Salesforce sync $49    │   │
│  │    by @enterprise-int     ⭐ 4.5 (78)   📥 234                   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Categories: [CRM] [Analytics] [AI/ML] [DevOps] [Marketing] [More ▾]   │
└─────────────────────────────────────────────────────────────────────────┘
```

### Template Detail Page

```
┌─────────────────────────────────────────────────────────────────────────┐
│ 🎯 Customer Support Triage                              [★ Star] [Fork] │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  by @enterprise-solutions  │  v2.1.0  │  Updated 3 days ago             │
│  ⭐ 4.8 (234 reviews)  │  📥 1,247 installs  │  MIT License              │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     [Pipeline Preview DAG]                       │   │
│  │   ┌──────┐    ┌──────────┐    ┌────────┐    ┌──────────┐        │   │
│  │   │Intake│───▶│Classify  │───▶│Route   │───▶│Notify    │        │   │
│  │   └──────┘    └──────────┘    └────────┘    └──────────┘        │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Description:                                                           │
│  Automatically classify and route customer support tickets using AI.    │
│  Integrates with Zendesk, Intercom, and Freshdesk. Includes sentiment   │
│  analysis and urgency detection.                                        │
│                                                                         │
│  Features:                                                              │
│  ✓ Intent classification (12 categories)                               │
│  ✓ Sentiment & urgency analysis                                        │
│  ✓ Auto-routing to appropriate teams                                   │
│  ✓ SLA-based prioritization                                            │
│  ✓ Slack/Email notifications                                           │
│                                                                         │
│  Requirements:                                                          │
│  • FlowMason >= 0.7.0                                                  │
│  • API keys: Anthropic or OpenAI                                       │
│  • Optional: Zendesk, Slack credentials                                │
│                                                                         │
│  [Install to Project]  [View Source]  [Try in Playground]              │
│                                                                         │
│  Reviews:                                                               │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ ⭐⭐⭐⭐⭐ "Saved us 20 hours/week on ticket routing"              │   │
│  │ @startup-cto, 2 weeks ago                                        │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ ⭐⭐⭐⭐ "Great template, needed some customization for our use"  │   │
│  │ @support-lead, 1 month ago                                       │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 17. Real-time Collaboration

Google Docs-style real-time collaboration for pipeline editing.

### Concept

Multiple team members can edit the same pipeline simultaneously, see each other's cursors, and collaborate in real-time.

### Collaborative Editor

```
┌─────────────────────────────────────────────────────────────────────────┐
│ customer-triage.pipeline.json               👤 Sam 👤 Alex 👤 Jordan    │
│                                              ↑ 3 collaborators          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                                                                 │   │
│  │   ┌──────────┐        ┌──────────┐        ┌──────────┐         │   │
│  │   │ intake   │───────▶│ classify │───────▶│ route    │         │   │
│  │   └──────────┘        └────┬─────┘        └──────────┘         │   │
│  │        │                   │ 👤 Alex                            │   │
│  │        │              (editing)                                 │   │
│  │        │                                                        │   │
│  │        │              ┌──────────┐        ┌──────────┐         │   │
│  │        └─────────────▶│ sentiment│───────▶│ escalate │         │   │
│  │           👤 Sam      └──────────┘        └──────────┘         │   │
│  │         (selecting)                            │                │   │
│  │                                          👤 Jordan              │   │
│  │                                         (editing)               │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 💬 Comments (3)                                        [+ Add]  │   │
│  │─────────────────────────────────────────────────────────────────│   │
│  │ 📍 On "classify" stage:                                         │   │
│  │    Alex: Should we add a confidence threshold?                  │   │
│  │    └─ Sam: Good idea, I'll add it                              │   │
│  │                                                                 │   │
│  │ 📍 On "escalate" stage:                                         │   │
│  │    Jordan: This should also trigger PagerDuty for critical     │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Activity:                                                              │
│  • Alex modified "classify" stage config (just now)                    │
│  • Sam added new stage "sentiment" (2 min ago)                         │
│  • Jordan joined the session (5 min ago)                               │
└─────────────────────────────────────────────────────────────────────────┘
```

### Features

#### Presence & Cursors
- See who's viewing/editing
- Real-time cursor positions
- Stage selection highlighting per user

#### Inline Comments
- Comment on specific stages
- Threaded discussions
- @mentions and notifications
- Resolve/archive comments

#### Change Attribution
```json
{
  "stages": [
    {
      "id": "classify",
      "_meta": {
        "last_modified_by": "alex@company.com",
        "last_modified_at": "2025-12-13T14:32:00Z"
      }
    }
  ]
}
```

#### Conflict Resolution
```
┌─────────────────────────────────────────────────────────────────────────┐
│ ⚠️ Conflict Detected on "classify" stage                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  You and Alex both modified the same config at the same time.           │
│                                                                         │
│  Your change:                    Alex's change:                         │
│  ┌───────────────────────────┐   ┌───────────────────────────────────┐ │
│  │ "threshold": 0.8          │   │ "threshold": 0.85                 │ │
│  │ "model": "claude-3-haiku" │   │ "model": "claude-3-sonnet"        │ │
│  └───────────────────────────┘   └───────────────────────────────────┘ │
│                                                                         │
│  [Keep Yours] [Keep Alex's] [Merge Both] [Open Chat]                   │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 18. Execution Analytics & Insights

Deep analytics on pipeline performance with AI-powered insights and anomaly detection.

### Dashboard

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Pipeline Analytics: customer-triage                    Period: 7 days   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Overview                                                               │
│  ┌────────────────┬────────────────┬────────────────┬────────────────┐ │
│  │ Total Runs     │ Success Rate   │ Avg Duration   │ P95 Latency    │ │
│  │    12,847      │    98.2%       │    1.3s        │    2.8s        │ │
│  │   ↑ 23%        │   ↑ 0.5%       │   ↓ 0.2s       │   ↓ 0.4s       │ │
│  └────────────────┴────────────────┴────────────────┴────────────────┘ │
│                                                                         │
│  Execution Timeline                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ runs                                                            │   │
│  │ 200 ┤     ╭─╮                                                   │   │
│  │ 150 ┤  ╭──╯ ╰──╮    ╭────╮                    ╭──╮              │   │
│  │ 100 ┤──╯       ╰────╯    ╰────────────────────╯  ╰──            │   │
│  │  50 ┤                                                           │   │
│  │     └───────────────────────────────────────────────────────────│   │
│  │       Mon    Tue    Wed    Thu    Fri    Sat    Sun             │   │
│  │                                                                 │   │
│  │  ━ Successful  ━ Failed  ━ Timeout                              │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Stage Performance                                                      │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ Stage             │ Avg Time │ P95    │ Failures │ % of Total   │   │
│  │───────────────────┼──────────┼────────┼──────────┼──────────────│   │
│  │ intake            │   45ms   │  82ms  │    0     │ ██░░░░ 3%    │   │
│  │ classify          │  890ms   │ 1.8s   │   12     │ ████████ 68% │   │
│  │ sentiment         │  245ms   │ 520ms  │    3     │ ████░░░ 19%  │   │
│  │ route             │   23ms   │  45ms  │    0     │ █░░░░░ 2%    │   │
│  │ notify            │  102ms   │ 234ms  │    8     │ ██░░░░ 8%    │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  🤖 AI Insights                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 1. ⚠️ Anomaly detected: "classify" stage latency increased 40%  │   │
│  │    since Wednesday. Correlates with increased input length.     │   │
│  │    Suggestion: Add input truncation or switch to streaming.     │   │
│  │                                                                 │   │
│  │ 2. 💡 The "notify" stage fails primarily during 9-10am (peak).  │   │
│  │    Likely Slack rate limiting. Consider batching notifications. │   │
│  │                                                                 │   │
│  │ 3. ✨ Weekend traffic is 60% lower. Consider cost savings by    │   │
│  │    reducing reserved capacity during off-peak hours.            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

### Anomaly Detection

```yaml
# analytics.yaml
alerts:
  - name: latency_spike
    condition: p95_latency > baseline * 1.5
    window: 1h
    action:
      - slack: "#ops-alerts"
      - email: ["oncall@company.com"]

  - name: error_rate
    condition: error_rate > 5%
    window: 15m
    action:
      - pagerduty: high
      - auto_rollback: true  # Rollback to last stable version

  - name: cost_anomaly
    condition: hourly_cost > daily_average * 3
    action:
      - slack: "#cost-alerts"
      - throttle: 50%  # Reduce throughput to 50%
```

---

## 19. Multi-Region Deployment

Deploy pipelines across multiple regions for low latency and high availability.

### Concept

Run pipelines closer to your users with automatic failover and load balancing.

### Architecture

```
                           ┌─────────────────┐
                           │  Global Router  │
                           │  (DNS/Anycast)  │
                           └────────┬────────┘
                                    │
            ┌───────────────────────┼───────────────────────┐
            │                       │                       │
            ▼                       ▼                       ▼
   ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
   │   US-EAST       │    │   EU-WEST       │    │   APAC          │
   │   (Primary)     │    │   (Replica)     │    │   (Replica)     │
   │                 │    │                 │    │                 │
   │  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
   │  │ FlowMason │  │    │  │ FlowMason │  │    │  │ FlowMason │  │
   │  │  Studio   │  │    │  │  Studio   │  │    │  │  Studio   │  │
   │  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
   │                 │    │                 │    │                 │
   │  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
   │  │  Workers  │  │    │  │  Workers  │  │    │  │  Workers  │  │
   │  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
   └─────────────────┘    └─────────────────┘    └─────────────────┘
            │                       │                       │
            └───────────────────────┴───────────────────────┘
                                    │
                           ┌────────▼────────┐
                           │  Shared State   │
                           │  (CockroachDB/  │
                           │   Spanner)      │
                           └─────────────────┘
```

### Configuration

```yaml
# deployment.yaml
multi_region:
  enabled: true

  regions:
    - name: us-east-1
      role: primary
      capacity: 100

    - name: eu-west-1
      role: replica
      capacity: 50
      sync_delay: 100ms

    - name: ap-southeast-1
      role: replica
      capacity: 30
      sync_delay: 200ms

  routing:
    strategy: latency  # latency, round-robin, geo
    failover:
      enabled: true
      threshold: 3  # failures before failover
      cooldown: 60s

  pipelines:
    customer-triage:
      regions: [us-east-1, eu-west-1]  # Not in APAC
      affinity: user_region

    global-analytics:
      regions: all
      affinity: data_region  # Process data where it lives
```

### Dashboard

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Multi-Region Status                                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
│  │    US-EAST      │    │    EU-WEST      │    │     APAC        │     │
│  │   ● Primary     │    │   ● Healthy     │    │   ● Healthy     │     │
│  │                 │    │                 │    │                 │     │
│  │  Load: 67%      │    │  Load: 45%      │    │  Load: 23%      │     │
│  │  Latency: 45ms  │    │  Latency: 12ms  │    │  Latency: 8ms   │     │
│  │  Runs: 5,234/hr │    │  Runs: 3,102/hr │    │  Runs: 1,456/hr │     │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘     │
│                                                                         │
│  Traffic Distribution                                                   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ US-EAST:    ████████████████████████████░░░░░░░░░░░░░░  54%     │   │
│  │ EU-WEST:    ███████████████████░░░░░░░░░░░░░░░░░░░░░░░  32%     │   │
│  │ APAC:       ███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  14%     │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Recent Events:                                                         │
│  • 14:32 - EU-WEST: Auto-scaled from 3 to 5 workers                    │
│  • 12:15 - APAC: Brief latency spike (resolved)                        │
│  • 09:00 - US-EAST: Deployed v2.3.1 (propagated to all regions)        │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 20. Natural Language Pipeline Builder

Create and modify pipelines using natural language instructions.

### Concept

Talk to FlowMason like you would to a colleague. Describe what you want, and it builds the pipeline.

### Interface

```
┌─────────────────────────────────────────────────────────────────────────┐
│ FlowMason AI Builder                                      [New Session] │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 👤 I need a pipeline that takes customer feedback emails,       │   │
│  │    analyzes the sentiment, extracts key issues, and creates     │   │
│  │    tickets in our system. High-priority issues should go to     │   │
│  │    Slack immediately.                                           │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 🤖 I'll create a pipeline for that. Here's what I'm thinking:   │   │
│  │                                                                 │   │
│  │    1. **Email Intake** - Receive and parse incoming emails      │   │
│  │    2. **Sentiment Analysis** - Detect positive/negative/neutral │   │
│  │    3. **Issue Extraction** - Use AI to identify key problems    │   │
│  │    4. **Priority Assignment** - Based on sentiment + keywords   │   │
│  │    5. **Ticket Creation** - Create tickets in your system       │   │
│  │    6. **Slack Alert** - Notify for high-priority only           │   │
│  │                                                                 │   │
│  │    Questions:                                                   │   │
│  │    • What ticketing system do you use? (Jira, Linear, etc.)    │   │
│  │    • What makes an issue "high priority" for you?               │   │
│  │                                                                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 👤 We use Linear. High priority = negative sentiment AND        │   │
│  │    mentions "urgent", "broken", or "can't access"               │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 🤖 Perfect! I've created the pipeline:                          │   │
│  │                                                                 │   │
│  │    ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐   │   │
│  │    │Intake │──▶│Analyze│──▶│Extract│──▶│Route  │──▶│Linear │   │   │
│  │    └───────┘   └───────┘   └───────┘   └───┬───┘   └───────┘   │   │
│  │                                            │                    │   │
│  │                                            ▼ (high priority)    │   │
│  │                                       ┌───────┐                 │   │
│  │                                       │ Slack │                 │   │
│  │                                       └───────┘                 │   │
│  │                                                                 │   │
│  │    [View Pipeline JSON] [Open in Editor] [Run Test]            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 👤 Actually, can you also add a step that auto-replies to the   │   │
│  │    customer acknowledging their feedback?                       │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 🤖 Done! I've added an "Auto-Reply" stage after intake that     │   │
│  │    sends a personalized acknowledgment email. The template      │   │
│  │    includes the ticket ID so customers can track their issue.   │   │
│  │                                                                 │   │
│  │    [Show Changes] [Undo] [Continue]                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Describe what you want to build or modify...                   [↵] │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```

### Modification Mode

Also works on existing pipelines:

```
👤 "In my customer-triage pipeline, add rate limiting so we don't
    process more than 100 tickets per minute"

🤖 I've added a rate limiter stage before the classify step:

   Changes:
   + Added "rate-limiter" stage (100 req/min, queue overflow)
   + Modified "classify" depends_on to include rate-limiter

   [Apply Changes] [Show Diff] [Explain More]
```

```
👤 "The sentiment analysis is too slow. Can you optimize it?"

🤖 I analyzed your sentiment stage. Here are optimization options:

   1. **Switch to Haiku** - Currently using Sonnet (890ms avg)
      Haiku would be ~200ms with 94% accuracy (vs 97%)

   2. **Add caching** - 30% of your inputs are similar
      Could reduce LLM calls by ~25%

   3. **Batch processing** - Process 5 items per LLM call
      Would reduce latency to ~180ms per item

   Recommendation: Option 1 + 2 for best cost/performance

   [Apply Option 1] [Apply Option 2] [Apply Both] [Explain Trade-offs]
```

---

## 21. Pipeline Observability with OpenTelemetry

First-class distributed tracing and observability integration.

### Concept

Every pipeline execution generates OpenTelemetry traces, enabling deep visibility and integration with existing observability stacks.

### Trace View

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Trace: run_abc123                                Duration: 1,847ms       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Timeline:                                                              │
│  0ms                500ms              1000ms             1500ms         │
│  │                   │                   │                   │          │
│  ├── pipeline.execute ─────────────────────────────────────────┤        │
│  │   │                                                         │        │
│  │   ├── stage.intake ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │        │
│  │   │   └── http.request ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │        │
│  │   │                                                         │        │
│  │   ├── stage.classify ░░░░████████████████░░░░░░░░░░░░░░░    │        │
│  │   │   └── llm.anthropic ░░░░███████████████░░░░░░░░░░░░░    │        │
│  │   │       model: claude-3-haiku                             │        │
│  │   │       tokens: 234 in / 89 out                           │        │
│  │   │                                                         │        │
│  │   ├── stage.route ░░░░░░░░░░░░░░░░░░░░██░░░░░░░░░░░░░░░░    │        │
│  │   │                                                         │        │
│  │   └── stage.notify ░░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░    │        │
│  │       └── http.slack ░░░░░░░░░░░░░░░░░░░░░███████░░░░░░░    │        │
│  │           status: 200                                       │        │
│  │                                                                      │
│  Span Details: stage.classify                                           │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ Attributes:                                                     │   │
│  │   flowmason.stage.id: "classify"                               │   │
│  │   flowmason.stage.type: "generator"                            │   │
│  │   flowmason.run.id: "run_abc123"                               │   │
│  │   llm.provider: "anthropic"                                    │   │
│  │   llm.model: "claude-3-haiku-20240307"                         │   │
│  │   llm.input_tokens: 234                                        │   │
│  │   llm.output_tokens: 89                                        │   │
│  │   llm.cost_usd: 0.000089                                       │   │
│  │                                                                 │   │
│  │ Events:                                                         │   │
│  │   • prompt_sent (t+523ms)                                      │   │
│  │   • response_received (t+1,412ms)                              │   │
│  │   • parsed_output (t+1,418ms)                                  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

### Integration

```yaml
# flowmason.yaml
observability:
  tracing:
    enabled: true
    exporter: otlp
    endpoint: "https://otel-collector.company.com:4317"

    # What to trace
    spans:
      pipeline: true
      stage: true
      llm_calls: true
      http_requests: true

    # Sampling
    sampling:
      strategy: parent_based  # or always_on, always_off, ratio
      ratio: 0.1  # 10% of traces

  metrics:
    enabled: true
    exporter: prometheus
    port: 9090

  logging:
    enabled: true
    format: json
    level: info
```

### Grafana Dashboard

```
┌─────────────────────────────────────────────────────────────────────────┐
│ FlowMason Overview                                              Grafana │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Pipeline Throughput                    Error Rate                      │
│  ┌─────────────────────────┐           ┌─────────────────────────┐     │
│  │  ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁       │           │  ▁▁▁▂▁▁▁█▁▁▁▁▁▁▁       │     │
│  │  1,234 req/min          │           │  0.8%                    │     │
│  └─────────────────────────┘           └─────────────────────────┘     │
│                                                                         │
│  P95 Latency by Stage                  LLM Cost (24h)                   │
│  ┌─────────────────────────┐           ┌─────────────────────────┐     │
│  │  intake:     ██ 82ms    │           │  Anthropic: $45.23      │     │
│  │  classify:   ████████   │           │  OpenAI:    $12.89      │     │
│  │              1,823ms    │           │  Total:     $58.12      │     │
│  │  route:      █ 45ms     │           │                         │     │
│  │  notify:     ███ 234ms  │           │  ↑ 12% from yesterday   │     │
│  └─────────────────────────┘           └─────────────────────────┘     │
│                                                                         │
│  Trace Search:                                                          │
│  [pipeline="customer-triage" AND duration>2s AND status=error]         │
│                                                                         │
│  Results: 23 traces                                                     │
│  • run_xyz789 - 3.2s - timeout in classify                             │
│  • run_abc456 - 2.8s - LLM rate limit                                  │
│  • run_def123 - 2.1s - Slack API error                                 │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 22. Embedded FlowMason (SDK)

Embed FlowMason pipelines directly into your applications.

### Concept

Run pipelines as a library within your application - no separate server required.

### Python SDK

```python
from flowmason import Pipeline, FlowMason

# Initialize FlowMason (embedded mode)
fm = FlowMason(
    mode="embedded",
    providers={
        "anthropic": {"api_key": os.environ["ANTHROPIC_API_KEY"]}
    }
)

# Load pipeline from file
pipeline = fm.load_pipeline("./pipelines/customer-triage.pipeline.json")

# Or define inline
pipeline = Pipeline(
    name="quick-classifier",
    stages=[
        Stage(
            id="classify",
            component="generator",
            config={
                "prompt": "Classify this text: {{input.text}}",
                "model": "claude-3-haiku"
            }
        )
    ]
)

# Execute synchronously
result = pipeline.run({"text": "I need help with billing"})
print(result.output)  # {"category": "billing", "confidence": 0.95}

# Execute asynchronously
async def process_batch(items):
    tasks = [pipeline.run_async(item) for item in items]
    results = await asyncio.gather(*tasks)
    return results

# Stream results
async for event in pipeline.stream({"text": "..."}):
    if event.type == "stage_complete":
        print(f"Stage {event.stage_id} completed")
    elif event.type == "output":
        print(f"Final output: {event.data}")
```

### TypeScript/Node SDK

```typescript
import { FlowMason, Pipeline } from '@flowmason/sdk';

// Initialize
const fm = new FlowMason({
  mode: 'embedded',
  providers: {
    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY }
  }
});

// Load and run
const pipeline = await fm.loadPipeline('./pipelines/customer-triage.json');
const result = await pipeline.run({ text: 'Need billing help' });

// With Express middleware
import { flowmasonMiddleware } from '@flowmason/sdk/express';

app.use('/api/pipelines', flowmasonMiddleware({
  pipelines: {
    'classify': './pipelines/classifier.json',
    'summarize': './pipelines/summarizer.json'
  }
}));

// POST /api/pipelines/classify { "text": "..." }
// Returns pipeline output
```

### React Hooks

```typescript
import { usePipeline, useFlowMason } from '@flowmason/react';

function CustomerForm() {
  const { run, loading, result, error } = usePipeline('customer-triage');

  const handleSubmit = async (data) => {
    const output = await run(data);
    // Handle result
  };

  return (
    <form onSubmit={handleSubmit}>
      {loading && <Spinner />}
      {error && <Error message={error} />}
      {result && <Result data={result} />}
    </form>
  );
}

// Or with streaming
function StreamingChat() {
  const { stream, events, isStreaming } = usePipelineStream('chat-pipeline');

  return (
    <div>
      {events.map(event => (
        <div key={event.id}>
          {event.type === 'stage_start' && `Running ${event.stage}...`}
          {event.type === 'output' && event.data}
        </div>
      ))}
    </div>
  );
}
```

---

## Priority Matrix

| Feature | Impact | Effort | Priority |
|---------|--------|--------|----------|
| **Docker - Local Dev** | High | Low | **P1** ✅ |
| **Execution Endpoint Auth** | High | Low | **P1** ✅ |
| **Local .fmpkg Import** | High | Low | **P1** ✅ |
| **MCP Server (Core)** | Very High | Medium | **P1** ✅ |
| **AI Pipeline Generation (Docs)** | High | Low | **P1** ✅ |
| **Component Visual - Icons & Colors** | High | Low | **P1** ✅ |
| **Secrets Management (Basic)** | High | Medium | **P1** ✅ |
| **Docker - Staging** | High | Medium | **P2** ✅ |
| **OAuth 2.0 Support** | High | Medium | **P2** ✅ |
| **Standalone JWT Tokens** | Medium | Medium | **P2** ✅ |
| **Built-in Template Gallery** | High | Medium | **P2** ✅ |
| **Docker - Production** | High | Medium | **P2** ✅ |
| **Web Portal - Operations Dashboard** | High | Medium | **P2** ✅ |
| **Web Portal - API Console** | High | Medium | **P2** ✅ |
| **MCP Client Operators** | High | Medium | **P2** ✅ |
| **Web Portal - Admin Panel** | Medium | Medium | **P2** ✅ |
| **AI Generation - Interactive** | High | Medium | **P2** ✅ |
| **Component Visual - Shapes & Ports** | Medium | Medium | **P2** ✅ |
| **Pipeline Testing - Basic Runner** | High | Medium | **P2** ✅ |
| **Scheduling - Cron** | High | Medium | **P2** ✅ |
| **Webhook Triggers** | High | Medium | **P2** ✅ |
| **Pipeline Debugger (Basic)** | High | Medium | **P2** ✅ |
| **LLM Cost Tracking** | High | Medium | **P2** ✅ |
| **Pipeline Versioning** | High | Medium | **P2** ✅ |
| **Prompt Library** | High | Medium | **P2** ✅ |
| **Embedded SDK (Python)** | Very High | Medium | **P2** ✅ |
| **Visual Field Mapping (Basic)** | Very High | Medium | **P2** ✅ |
| **Visual Field Mapping (Schema Inference)** | High | Medium | **P2** ✅ |
| **Visual Field Mapping (Validation)** | High | Low | **P2** ✅ |
| Remote Registry | High | High | P3 |
| Pipeline-Level Permissions | High | High | P3 |
| **VSCode Extension MCP** | High | Medium | **P3** |
| **Web Portal MCP Integration** | High | Medium | **P3** |
| **MCP Advanced (AI-assisted)** | Very High | High | **P3** |
| **AI Generation - MCP Tool** | Very High | Medium | **P3** |
| **Component Visual - Rich Cards** | Medium | High | **P3** |
| **Pipeline Testing - Mocking & Snapshots** | Medium | Medium | **P3** |
| **Event-Driven Triggers** | Medium | High | **P3** |
| **Secrets - Rotation & Audit** | Medium | Medium | **P3** |
| **Debugger - Time Travel** | High | High | **P3** |
| **Prompt A/B Testing** | High | High | **P3** |
| **Pipeline Marketplace** | Very High | Very High | **P3** |
| **Real-time Collaboration** | High | Very High | **P3** |
| **Execution Analytics & AI Insights** | High | High | **P3** |
| **Multi-Region Deployment** | High | Very High | **P3** |
| **Natural Language Builder** | Very High | High | **P3** |
| **OpenTelemetry Integration** | High | Medium | **P3** |
| **Embedded SDK (TypeScript)** | High | Medium | **P3** |
| **Embedded SDK (React Hooks)** | Medium | Low | **P3** |
| **Code Gen - Python** | Very High | High | **P3** |
| **Code Gen - Node.js/TypeScript** | Very High | High | **P3** |
| **Code Gen - Salesforce Apex** | High | High | **P3** |
| **Code Gen - Go/Java/Rust** | Medium | High | **P4** |
| **Code Gen - Serverless (Lambda/Workers)** | High | Medium | **P3** |

## 23. Pipeline-to-Code Generation

Compile FlowMason pipelines into standalone backend applications in multiple languages.

### Concept

Transform declarative pipeline JSON into production-ready code that runs independently - no FlowMason runtime required. Perfect for:
- Deploying to restricted environments
- Maximum performance (native code vs. interpreted)
- Integration with existing codebases
- Enterprise platforms (Salesforce Apex)

### Supported Targets

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Pipeline Code Generator                                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Source: customer-triage.pipeline.json                                  │
│                                                                         │
│  Generate Code:                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                                                                 │   │
│  │  🐍 Python                              [Generate]              │   │
│  │     FastAPI service with async execution                        │   │
│  │     Output: customer_triage/                                    │   │
│  │             ├── main.py                                         │   │
│  │             ├── stages/                                         │   │
│  │             ├── requirements.txt                                │   │
│  │             └── Dockerfile                                      │   │
│  │                                                                 │   │
│  │  📦 Node.js / TypeScript               [Generate]              │   │
│  │     Express/Fastify service with TypeScript                     │   │
│  │     Output: customer-triage/                                    │   │
│  │             ├── src/                                            │   │
│  │             ├── package.json                                    │   │
│  │             └── Dockerfile                                      │   │
│  │                                                                 │   │
│  │  ☁️ Salesforce Apex                    [Generate]              │   │
│  │     Apex classes with Flow integration                          │   │
│  │     Output: force-app/main/default/                             │   │
│  │             ├── classes/                                        │   │
│  │             ├── flows/                                          │   │
│  │             └── triggers/                                       │   │
│  │                                                                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  Options:                                                               │
│  ☑ Include tests          ☑ Add Docker support                         │
│  ☑ Generate API docs      ☐ Inline all dependencies                    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### Python Generation

**Input Pipeline:**
```json
{
  "name": "customer-triage",
  "stages": [
    {
      "id": "classify",
      "component_type": "generator",
      "config": {
        "prompt": "Classify: {{input.message}}",
        "model": "claude-3-haiku"
      }
    },
    {
      "id": "route",
      "component_type": "router",
      "config": {
        "conditions": [
          { "when": "priority == 'high'", "goto": "urgent" },
          { "default": true, "goto": "standard" }
        ]
      }
    }
  ]
}
```

**Generated Python:**
```python
# customer_triage/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import anthropic
import asyncio
from typing import Optional

app = FastAPI(title="Customer Triage API", version="1.0.0")
client = anthropic.AsyncAnthropic()

class TriageInput(BaseModel):
    message: str

class TriageOutput(BaseModel):
    classification: dict
    route: str
    priority: str

@app.post("/triage", response_model=TriageOutput)
async def triage_customer(input: TriageInput) -> TriageOutput:
    # Stage: classify
    classification = await classify_message(input.message)

    # Stage: route
    route = route_by_priority(classification)

    return TriageOutput(
        classification=classification,
        route=route,
        priority=classification.get("priority", "normal")
    )

async def classify_message(message: str) -> dict:
    """Generated from: classify stage (generator)"""
    response = await client.messages.create(
        model="claude-3-haiku-20240307",
        max_tokens=256,
        messages=[{
            "role": "user",
            "content": f"Classify: {message}"
        }]
    )
    return parse_json_response(response.content[0].text)

def route_by_priority(classification: dict) -> str:
    """Generated from: route stage (router)"""
    priority = classification.get("priority")

    if priority == "high":
        return "urgent"
    else:
        return "standard"

# --- Generated utilities ---
def parse_json_response(text: str) -> dict:
    import json
    import re
    # Extract JSON from markdown code blocks if present
    match = re.search(r'```(?:json)?\s*([\s\S]*?)\s*```', text)
    if match:
        text = match.group(1)
    return json.loads(text)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

**Generated requirements.txt:**
```
fastapi>=0.104.0
uvicorn>=0.24.0
anthropic>=0.18.0
pydantic>=2.0.0
```

**Generated Dockerfile:**
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Node.js/TypeScript Generation

**Generated TypeScript:**
```typescript
// src/index.ts
import Anthropic from "@anthropic-ai/sdk";
import Fastify from "fastify";

const app = Fastify({ logger: true });
const anthropic = new Anthropic();

interface TriageInput {
  message: string;
}

interface TriageOutput {
  classification: Record<string, unknown>;
  route: string;
  priority: string;
}

// Stage: classify
async function classifyMessage(message: string): Promise<Record<string, unknown>> {
  const response = await anthropic.messages.create({
    model: "claude-3-haiku-20240307",
    max_tokens: 256,
    messages: [{ role: "user", content: `Classify: ${message}` }],
  });

  return parseJsonResponse(
    response.content[0].type === "text" ? response.content[0].text : ""
  );
}

// Stage: route
function routeByPriority(classification: Record<string, unknown>): string {
  const priority = classification.priority;

  if (priority === "high") {
    return "urgent";
  }
  return "standard";
}

// Main pipeline endpoint
app.post<{ Body: TriageInput }>("/triage", async (request, reply) => {
  const { message } = request.body;

  // Execute pipeline stages
  const classification = await classifyMessage(message);
  const route = routeByPriority(classification);

  const output: TriageOutput = {
    classification,
    route,
    priority: (classification.priority as string) || "normal",
  };

  return output;
});

// Start server
app.listen({ port: 8000, host: "0.0.0.0" }, (err) => {
  if (err) throw err;
  console.log("Server running on http://0.0.0.0:8000");
});
```

### Salesforce Apex Generation

**Generated Apex Class:**
```java
// CustomerTriageService.cls
public class CustomerTriageService {

    public class TriageInput {
        @AuraEnabled public String message { get; set; }
    }

    public class TriageOutput {
        @AuraEnabled public Map<String, Object> classification { get; set; }
        @AuraEnabled public String route { get; set; }
        @AuraEnabled public String priority { get; set; }
    }

    @AuraEnabled(cacheable=false)
    public static TriageOutput triageCustomer(TriageInput input) {
        // Stage: classify
        Map<String, Object> classification = classifyMessage(input.message);

        // Stage: route
        String route = routeByPriority(classification);

        TriageOutput output = new TriageOutput();
        output.classification = classification;
        output.route = route;
        output.priority = (String) classification.get('priority');

        return output;
    }

    private static Map<String, Object> classifyMessage(String message) {
        // Call Claude API via Named Credential
        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:Anthropic_API/v1/messages');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setHeader('anthropic-version', '2023-06-01');

        Map<String, Object> body = new Map<String, Object>{
            'model' => 'claude-3-haiku-20240307',
            'max_tokens' => 256,
            'messages' => new List<Map<String, String>>{
                new Map<String, String>{
                    'role' => 'user',
                    'content' => 'Classify: ' + message
                }
            }
        };
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        Map<String, Object> response = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        List<Object> content = (List<Object>) response.get('content');
        Map<String, Object> textBlock = (Map<String, Object>) content[0];
        String text = (String) textBlock.get('text');

        return (Map<String, Object>) JSON.deserializeUntyped(text);
    }

    private static String routeByPriority(Map<String, Object> classification) {
        String priority = (String) classification.get('priority');

        if (priority == 'high') {
            return 'urgent';
        }
        return 'standard';
    }
}
```

**Generated Apex Test:**
```java
// CustomerTriageServiceTest.cls
@isTest
public class CustomerTriageServiceTest {

    @isTest
    static void testTriageHighPriority() {
        // Mock the HTTP callout
        Test.setMock(HttpCalloutMock.class, new AnthropicMock('{"priority": "high", "category": "billing"}'));

        CustomerTriageService.TriageInput input = new CustomerTriageService.TriageInput();
        input.message = 'URGENT: My account is locked!';

        Test.startTest();
        CustomerTriageService.TriageOutput output = CustomerTriageService.triageCustomer(input);
        Test.stopTest();

        System.assertEquals('urgent', output.route, 'High priority should route to urgent');
        System.assertEquals('high', output.priority);
    }

    @isTest
    static void testTriageNormalPriority() {
        Test.setMock(HttpCalloutMock.class, new AnthropicMock('{"priority": "normal", "category": "inquiry"}'));

        CustomerTriageService.TriageInput input = new CustomerTriageService.TriageInput();
        input.message = 'What are your business hours?';

        Test.startTest();
        CustomerTriageService.TriageOutput output = CustomerTriageService.triageCustomer(input);
        Test.stopTest();

        System.assertEquals('standard', output.route, 'Normal priority should route to standard');
    }
}
```

**Generated Flow (metadata):**
```xml
<!-- CustomerTriageFlow.flow-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <label>Customer Triage Flow</label>
    <processType>AutoLaunchedFlow</processType>

    <actionCalls>
        <name>Triage_Customer</name>
        <label>Triage Customer</label>
        <actionName>CustomerTriageService</actionName>
        <actionType>apex</actionType>
        <inputParameters>
            <name>input</name>
            <value>
                <elementReference>inputRecord</elementReference>
            </value>
        </inputParameters>
        <outputParameters>
            <assignToReference>outputResult</assignToReference>
            <name>output</name>
        </outputParameters>
    </actionCalls>
</Flow>
```

### CLI Usage

```bash
# Generate Python backend
fm generate python customer-triage.pipeline.json -o ./output/python

# Generate Node.js/TypeScript
fm generate node customer-triage.pipeline.json -o ./output/node --typescript

# Generate Salesforce Apex
fm generate apex customer-triage.pipeline.json -o ./output/salesforce

# Options
fm generate python pipeline.json \
  --include-tests \
  --include-docker \
  --api-framework fastapi \  # or flask, starlette
  --async-mode \
  --output-dir ./backend
```

### API Endpoint

```python
# POST /api/v1/generate
{
  "pipeline_path": "pipelines/customer-triage.pipeline.json",
  "target": "python",
  "options": {
    "framework": "fastapi",
    "include_tests": true,
    "include_docker": true,
    "async_mode": true
  }
}

# Response: ZIP file with generated project
```

### Generation Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        Pipeline Code Generator                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐     ┌─────────────────┐     ┌────────────────────┐    │
│  │   Pipeline  │────▶│  IR Generator   │────▶│  Target Emitter    │    │
│  │    JSON     │     │                 │     │                    │    │
│  └─────────────┘     │ • Parse stages  │     │ ┌────────────────┐ │    │
│                      │ • Resolve deps  │     │ │ Python Emitter │ │    │
│                      │ • Build DAG     │     │ └────────────────┘ │    │
│                      │ • Type inference│     │ ┌────────────────┐ │    │
│                      └─────────────────┘     │ │ Node Emitter   │ │    │
│                              │               │ └────────────────┘ │    │
│                              ▼               │ ┌────────────────┐ │    │
│                      ┌─────────────────┐     │ │ Apex Emitter   │ │    │
│                      │ Intermediate    │     │ └────────────────┘ │    │
│                      │ Representation  │────▶│                    │    │
│                      │                 │     └────────────────────┘    │
│                      │ • StageNode[]   │              │                │
│                      │ • DataFlow      │              ▼                │
│                      │ • TypeMap       │     ┌────────────────────┐    │
│                      └─────────────────┘     │  Post-Processor    │    │
│                                              │                    │    │
│                                              │ • Format code      │    │
│                                              │ • Add imports      │    │
│                                              │ • Generate tests   │    │
│                                              │ • Create Dockerfile│    │
│                                              └────────────────────┘    │
│                                                       │                │
│                                                       ▼                │
│                                              ┌────────────────────┐    │
│                                              │   Output Project   │    │
│                                              │   (ZIP or folder)  │    │
│                                              └────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
```

### Component Mappings

Each FlowMason component maps to language-specific implementations:

| Component | Python | Node.js | Apex |
|-----------|--------|---------|------|
| `generator` | `anthropic.messages.create()` | `anthropic.messages.create()` | `HttpRequest` to Named Credential |
| `json_transform` | `jmespath.search()` | `jmespath.search()` | Custom JSON utility class |
| `filter` | List comprehension | `Array.filter()` | SOQL or List iteration |
| `http_request` | `httpx.AsyncClient` | `fetch` / `axios` | `HttpRequest` |
| `conditional` | `if/elif/else` | `if/else if/else` | `if/else` |
| `foreach` | `async for` / `asyncio.gather` | `Promise.all` / `for await` | `for` loop |
| `router` | Match statement | Switch/if chain | `if/else` chain |

### Future Targets

Planned additional language targets:

```
• Go           - Chi/Gin REST service
• Java         - Spring Boot application
• Rust         - Axum/Actix service
• C#           - ASP.NET Core / Azure Functions
• AWS Lambda   - Python/Node handlers with SAM template
• Cloudflare   - Workers with Hono
• Deno         - Fresh/Oak service
```

---

## 24. Visual Field Mapping Between Nodes

A visual interface for mapping data fields between pipeline stages, with schemas derived from the component registry.

### Concept

Instead of manually typing `{{upstream.classify.result.category}}`, users can visually drag-and-drop connections between output fields of one stage and input fields of another. The component registry provides the schema definitions for each component's inputs and outputs.

### Current State

```json
{
  "id": "route-ticket",
  "component_type": "router",
  "config": {
    "value": "{{upstream.classify.result.priority}}",
    "conditions": [...]
  }
}
```

Users must:
1. Know the exact path to reference upstream data
2. Manually type template expressions
3. Hope they got the field names right (no validation until runtime)

### Visual Mapping Interface

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Pipeline Editor: customer-triage                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────┐         ┌─────────────────────────┐           │
│  │ 📥 classify             │         │ 🔀 route-ticket         │           │
│  │ generator               │         │ router                  │           │
│  ├─────────────────────────┤         ├─────────────────────────┤           │
│  │ Inputs:                 │         │ Inputs:                 │           │
│  │ ┌─────────────────────┐ │         │ ┌─────────────────────┐ │           │
│  │ │ ○ prompt      string│ │         │ │ ● value      string│◀──┐        │
│  │ │ ○ model       string│ │         │ │ ○ conditions  array│ │  │        │
│  │ └─────────────────────┘ │         │ └─────────────────────┘ │  │        │
│  ├─────────────────────────┤         ├─────────────────────────┤  │        │
│  │ Outputs:                │         │ Outputs:                │  │        │
│  │ ┌─────────────────────┐ │         │ ┌─────────────────────┐ │  │        │
│  │ │ ● category   string│──────┐    │ │ ○ route      string│ │  │        │
│  │ │ ● priority   string│──────┼────┼▶│ ○ matched    bool  │ │  │        │
│  │ │ ● confidence number│──┐   │    │ └─────────────────────┘ │  │        │
│  │ │ ● sentiment  string│  │   │    └─────────────────────────┘  │        │
│  │ └─────────────────────┘ │  │   │                               │        │
│  └─────────────────────────┘  │   │  ┌─────────────────────────┐  │        │
│                               │   │  │ 📊 create-summary       │  │        │
│                               │   │  │ json_transform          │  │        │
│                               │   │  ├─────────────────────────┤  │        │
│                               │   │  │ Inputs:                 │  │        │
│                               │   │  │ ┌─────────────────────┐ │  │        │
│                               │   └──┼▶│ ● category   string│ │  │        │
│                               └──────┼▶│ ● confidence number│ │  │        │
│                                      │ │ ○ threshold  number│ │  │        │
│                                      │ └─────────────────────┘ │  │        │
│                                      └─────────────────────────┘  │        │
│                                                                    │        │
│  ┌─ Legend ───────────────────────────────────────────────────────┘        │
│  │ ● = Connected   ○ = Unconnected   ─▶ = Data flow                        │
│  └──────────────────────────────────────────────────────────────────────────│
└─────────────────────────────────────────────────────────────────────────────┘
```

### Field Mapping Panel

When clicking on a connection or an input field:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Field Mapping: route-ticket.value                                    [✕]    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Target Field                          Source                               │
│  ┌───────────────────────┐            ┌───────────────────────────────────┐│
│  │ value                 │     ◀───   │ ○ Input                           ││
│  │ type: string          │            │   ├─ message                      ││
│  │ required: true        │            │   └─ customer_id                  ││
│  │                       │            │                                   ││
│  │ Current mapping:      │            │ ● Upstream Stages                 ││
│  │ {{upstream.classify   │            │   └─ classify                     ││
│  │   .result.priority}}  │            │       ├─ ● category    ← selected ││
│  │                       │            │       ├─ ● priority               ││
│  │                       │            │       ├─ ○ confidence             ││
│  │                       │            │       └─ ○ sentiment              ││
│  │                       │            │                                   ││
│  │                       │            │ ○ Context Variables               ││
│  │                       │            │   ├─ run_id                       ││
│  │                       │            │   └─ timestamp                    ││
│  │                       │            │                                   ││
│  │                       │            │ ○ Pipeline Variables              ││
│  │                       │            │   └─ active_user_count            ││
│  └───────────────────────┘            └───────────────────────────────────┘│
│                                                                             │
│  Transform (optional):                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ ○ Direct mapping (no transform)                                     │   │
│  │ ○ JMESPath expression: [________________]                           │   │
│  │ ○ Template expression: [________________]                           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Preview:                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ Source value: "high"                                                │   │
│  │ Mapped value: "high"                                                │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│                                              [Cancel]  [Apply Mapping]      │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Registry-Driven Schemas

Component schemas come from the `@operator` decorator in the registry:

```python
# lab/flowmason_lab/operators/core/generator.py
@operator(
    name="generator",
    category="ai",
    input_schema={
        "type": "object",
        "properties": {
            "prompt": {"type": "string", "description": "The prompt template"},
            "model": {"type": "string", "default": "claude-3-haiku"},
            "temperature": {"type": "number", "default": 0.7},
            "max_tokens": {"type": "integer", "default": 1024}
        },
        "required": ["prompt"]
    },
    output_schema={
        "type": "object",
        "properties": {
            "result": {
                "type": "object",
                "description": "Parsed JSON response from LLM",
                "additionalProperties": True
            },
            "raw_text": {"type": "string"},
            "tokens_used": {"type": "integer"},
            "model": {"type": "string"}
        }
    }
)
class GeneratorOperator(Operator):
    ...
```

### Schema Inference

For dynamic outputs (like `generator` that returns parsed JSON), the system can:

1. **Use explicit schema hints** in the pipeline:
```json
{
  "id": "classify",
  "component_type": "generator",
  "config": { ... },
  "output_hints": {
    "result": {
      "type": "object",
      "properties": {
        "category": {"type": "string"},
        "priority": {"type": "string", "enum": ["low", "medium", "high"]},
        "confidence": {"type": "number"}
      }
    }
  }
}
```

2. **Learn from execution history**:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 💡 Schema learned from last 10 executions of "classify" stage:              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  result: {                                                                  │
│    category: string     (seen: "billing", "technical", "sales")            │
│    priority: string     (seen: "low", "medium", "high")                    │
│    confidence: number   (range: 0.75 - 0.98)                               │
│    sentiment: string    (seen: "positive", "negative", "neutral")          │
│  }                                                                          │
│                                                                             │
│  [Save as Schema Hint]  [Ignore]                                           │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Complex Mapping Scenarios

#### Array Mapping (foreach context)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Inside foreach: process-items                                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Available Sources:                                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 📍 Loop Context (current iteration)                                 │   │
│  │    ├─ current_item: object                                          │   │
│  │    │   ├─ id: string                                                │   │
│  │    │   ├─ name: string                                              │   │
│  │    │   └─ value: number                                             │   │
│  │    ├─ item_index: number                                            │   │
│  │    └─ total_items: number                                           │   │
│  │                                                                     │   │
│  │ 📦 Upstream (before loop)                                           │   │
│  │    └─ fetch-items.result: array                                     │   │
│  │                                                                     │   │
│  │ 📥 Pipeline Input                                                   │   │
│  │    └─ threshold: number                                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### Object Spread / Multiple Fields
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Multi-Field Mapping: create-summary.data                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Target: data (object)                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ {                                                                   │   │
│  │   "classification": ← classify.result                              │   │
│  │   "items": ← process-items.results                                 │   │
│  │   "count": ← process-items.total_iterations                        │   │
│  │   "threshold": ← input.threshold                                   │   │
│  │ }                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Mapping Mode:                                                              │
│  ● Build object from multiple sources                                      │
│  ○ Map single value                                                        │
│  ○ Spread upstream result                                                  │
│                                                                             │
│  [+ Add Field]                                          [Apply]            │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Visual Validation

Real-time validation as you map:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Mapping Validation                                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ✅ route-ticket.value ← classify.result.priority                          │
│     string → string (compatible)                                           │
│                                                                             │
│  ⚠️ filter-items.threshold ← classify.result.confidence                    │
│     number expected, but source is sometimes string                        │
│     Suggestion: Add type coercion or validate upstream                     │
│                                                                             │
│  ❌ notify.recipient ← (unmapped)                                          │
│     Required field has no mapping                                          │
│                                                                             │
│  ℹ️ create-summary.optional_note ← (unmapped)                              │
│     Optional field, will use default value                                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Implementation

#### Registry Schema Enhancement

```python
# core/flowmason_core/registry/types.py
@dataclass
class OperatorSchema:
    input_schema: Dict[str, Any]      # JSON Schema for inputs
    output_schema: Dict[str, Any]     # JSON Schema for outputs
    config_schema: Dict[str, Any]     # JSON Schema for config

@dataclass
class RegisteredOperator:
    name: str
    operator_class: Type[Operator]
    schema: OperatorSchema
    metadata: OperatorMetadata
```

#### API for Schema Discovery

```python
# GET /api/v1/registry/{component_type}/schema
{
  "component_type": "generator",
  "input_schema": {
    "type": "object",
    "properties": {
      "prompt": {"type": "string"},
      "model": {"type": "string"}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "result": {"type": "object"},
      "raw_text": {"type": "string"}
    }
  }
}

# GET /api/v1/pipelines/{pipeline}/stages/{stage}/inferred-schema
{
  "stage_id": "classify",
  "output_schema": {
    "type": "object",
    "properties": {
      "category": {"type": "string", "observed_values": ["billing", "technical"]},
      "priority": {"type": "string", "observed_values": ["low", "medium", "high"]}
    }
  },
  "sample_count": 47,
  "last_updated": "2025-12-13T10:30:00Z"
}
```

#### Frontend Components

```typescript
// studio/frontend/src/components/mapping/
├── FieldMapper.tsx           // Main mapping interface
├── SchemaTree.tsx            // Tree view of available fields
├── ConnectionLine.tsx        // SVG line between nodes
├── MappingPanel.tsx          // Detail panel for a mapping
├── TypeBadge.tsx             // Shows field type with color
└── ValidationIndicator.tsx   // Shows mapping validation status

// Key interfaces
interface FieldMapping {
  targetStageId: string;
  targetField: string;
  sourceExpression: string;  // Template expression
  sourceType: 'upstream' | 'input' | 'context' | 'variable';
  sourceStageId?: string;
  sourceField?: string;
  transform?: string;  // Optional JMESPath
}

interface StageSchema {
  stageId: string;
  componentType: string;
  inputs: JSONSchema;
  outputs: JSONSchema;
  inferredOutputs?: JSONSchema;  // From execution history
}
```

#### DAG Canvas Integration

```typescript
// Extend existing DAG canvas
interface NodeWithPorts extends PipelineNode {
  inputPorts: Port[];   // Derived from schema
  outputPorts: Port[];  // Derived from schema
}

interface Port {
  id: string;
  name: string;
  type: string;
  required: boolean;
  connected: boolean;
  position: { x: number; y: number };
}

// Connection is a visual line + underlying mapping
interface Connection {
  id: string;
  sourceNodeId: string;
  sourcePortId: string;
  targetNodeId: string;
  targetPortId: string;
  mapping: FieldMapping;
}
```

### User Flow

1. **Add a stage** → Component schema loaded from registry
2. **Expand stage** → See input/output ports with types
3. **Drag from output port** → Line follows cursor
4. **Drop on input port** → Mapping created (if types compatible)
5. **Click connection** → Open mapping panel for transforms
6. **Save pipeline** → Mappings converted to template expressions

### Generated Pipeline JSON

Visual mappings are stored as standard template expressions:

```json
{
  "id": "route-ticket",
  "component_type": "router",
  "config": {
    "value": "{{upstream.classify.result.priority}}"
  },
  "_visual_mappings": [
    {
      "target": "config.value",
      "source": {
        "stage": "classify",
        "path": "result.priority"
      }
    }
  ]
}
```

The `_visual_mappings` metadata is optional and used only by the visual editor to reconstruct the view.

---

## Notes

- Document created: 2025-12-13
- Last updated: 2025-12-13
- Features 12-22 added: 2025-12-13
- Feature 23 (Code Generation) added: 2025-12-13
- Feature 24 (Visual Field Mapping) added: 2025-12-13
