@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-07-deployment.md

@@ -1,731 +1,731 @@
-# Module 7: Deployment, Monitoring & Operations
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 7 of 8** | **Level**: Advanced | **Time**: 30 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Deploy connectors to Versori Platform
-- ✅ Monitor workflow execution and logs
-- ✅ Implement CI/CD pipelines for automated deployment
-- ✅ Manage environment-specific configurations
-- ✅ Handle versioning and rollback strategies
-- ✅ Debug production issues effectively
-- ✅ Optimize deployment for performance
-
----
-
-## Deployment Workflow
-
-### Pre-Deployment Checklist
-
-Before deploying to Versori, ensure:
-
-- [ ] All TypeScript code compiles without errors
-- [ ] Connections configured in Versori UI
-- [ ] Connector variables set (secrets, config)
-- [ ] `package.json` has correct `versori.workflows` entry
-- [ ] Environment-specific settings verified
-- [ ] Test workflows validated locally
-- [ ] Documentation updated
-
----
-
-## Local Development & Testing
-
-### Project Structure
-
-```
-my-fluent-connector/
-├── src/
-│   ├── index.ts                    # Main entry point
-│   ├── workflows/
-│   │   ├── inventory-sync.ts       # Scheduled workflows
-│   │   ├── order-webhook.ts        # Webhook receivers
-│   │   └── query-api.ts            # HTTP workflows
-│   ├── config/
-│   │   ├── mappings.json           # Field mappings
-│   │   └── constants.ts            # Configuration constants
-│   └── utils/
-│       ├── transformers.ts         # Data transformation helpers
-│       └── validators.ts           # Validation utilities
-├── dist/                           # Build output (gitignored)
-├── node_modules/                   # Dependencies (gitignored)
-├── package.json                    # Package configuration
-├── tsconfig.json                   # TypeScript configuration
-├── .env.example                    # Environment variable template
-└── readme.md                       # Connector documentation
-```
-
-### Package.json Configuration
-
-```json
-{
-  "name": "fluent-inventory-connector",
-  "version": "1.0.0",
-  "description": "Fluent Commerce inventory integration",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "deploy": "npm run build && versori deploy",
-    "logs": "versori logs --follow",
-    "validate": "tsc --noEmit",
-    "test": "jest",
-    "lint": "eslint src/**/*.ts"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "latest",
-    "@versori/run": "^0.4.4"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0",
-    "eslint": "^8.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "jest": "^29.0.0"
-  },
-  "versori": {
-    "workflows": "dist/index.js"
-  }
-}
-```
-
-**CRITICAL**: The `versori.workflows` field tells Versori where to find exported workflows.
-
-### TypeScript Build
-
-```bash
-# Compile TypeScript
-npm run build
-
-# Validate without building
-npm run validate
-
-# Watch mode for development
-tsc --watch
-```
-
----
-
-## Deploying to Versori
-
-### Manual Deployment
-
-```bash
-# 1. Build TypeScript
-npm run build
-
-# 2. Deploy to Versori
-versori deploy
-
-# Expected output:
-# ✓ Building project...
-# ✓ Uploading to Versori...
-# ✓ Deployment successful
-#
-# Workflows deployed:
-#   - query-inventory (HTTP)
-#     URL: https://{workspace}.versori.run/query-inventory
-#   - receive-order (Webhook)
-#     URL: https://{workspace}.versori.run/receive-order
-#   - daily-sync (Scheduled)
-#     Schedule: 0 2 * * *
-```
-
-### Deploy Script
-
-```bash
-# Combined build + deploy
-npm run deploy
-```
-
-### Deployment Output
-
-Versori deployment creates:
-- **HTTP endpoints** for `http()` workflows
-- **Webhook URLs** for `webhook()` workflows
-- **Scheduled jobs** for `schedule()` workflows
-- **Internal functions** (not exposed) for `fn()` workflows
-
----
-
-## Environment Management
-
-### Environment-Specific Configurations
-
-Maintain separate configurations per environment:
-
-```typescript
-// src/config/environments.ts
-export const environments = {
-  development: {
-    fluentConnection: 'fluent_commerce_dev',
-    s3Bucket: 'inventory-dev',
-    logLevel: 'debug',
-    batchSize: 10
-  },
-  staging: {
-    fluentConnection: 'fluent_commerce_staging',
-    s3Bucket: 'inventory-staging',
-    logLevel: 'info',
-    batchSize: 50
-  },
-  production: {
-    fluentConnection: 'fluent_commerce_prod',
-    s3Bucket: 'inventory-prod',
-    logLevel: 'warn',
-    batchSize: 100
-  }
-};
-
-export function getConfig(env: string = 'production') {
-  return environments[env as keyof typeof environments] || environments.production;
-}
-```
-
-### Using Environment Configuration
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import { getConfig } from './config/environments';
-
-export const envAwareWorkflow = http('env-aware', async (ctx) => {
-  // Get environment from connector variable or default to production
-  const env = ctx.vars?.ENVIRONMENT || 'production';
-  const config = getConfig(env);
-
-  ctx.log('info', 'Running in environment', { env, config });
-
-  // Use environment-specific connection
-  const client = await createClient({
-    connection: ctx.connections?.[config.fluentConnection],
-    log: ctx.log
-  });
-
-  // Use environment-specific settings
-  const batchSize = config.batchSize;
-
-  // ... rest of workflow
-});
-```
-
-### Connector Variables in Versori
-
-Set environment-specific variables in Versori UI:
-
-**Development**:
-```
-ENVIRONMENT=development
-FLUENT_RETAILER_ID=1
-LOG_LEVEL=debug
-AWS_S3_BUCKET=inventory-dev
-```
-
-**Production**:
-```
-ENVIRONMENT=production
-FLUENT_RETAILER_ID=1
-LOG_LEVEL=warn
-AWS_S3_BUCKET=inventory-prod
-FLUENT_WEBHOOK_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...
-```
-
----
-
-## Monitoring & Logging
-
-### Viewing Logs
-
-#### Versori Dashboard
-
-1. Navigate to **Workflows** tab
-2. Select workflow
-3. Click **Executions** tab
-4. View:
-   - Execution timestamp
-   - Duration (ms)
-   - Status (success/error)
-   - Logs (`ctx.log()` calls)
-   - Input/output data
-
-#### CLI Logs
-
-```bash
-# Follow logs in real-time
-versori logs --follow
-
-# Filter by workflow
-versori logs --workflow query-inventory
-
-# Filter by level
-versori logs --level error
-
-# Show last N entries
-versori logs --tail 100
-
-# Filter by date range
-versori logs --since 2025-01-15 --until 2025-01-16
-```
-
-### Structured Logging Best Practices
-
-```typescript
-export const wellLogged = http('well-logged', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Log workflow start with context
-  ctx.log('info', 'Workflow started', {
-    workflow: 'well-logged',
-    executionId: ctx.executionId,
-    timestamp: new Date().toISOString()
-  });
-
-  const startTime = Date.now();
-
-  try {
-    const client = await createClient(ctx);
-
-    // Log before expensive operations
-    ctx.log('debug', 'Fetching data from Fluent API');
-
-    const result = await client.graphql({
-      query: `query { products(first: 100) { edges { node { id ref } } } }`
-    });
-
-    const duration = Date.now() - startTime;
-
-    // Log success with metrics
-    ctx.log('info', 'Workflow completed successfully', {
-      duration,
-      recordCount: result.data.products.edges.length,
-      status: 'success'
-    });
-
-    return result.data;
-
-  } catch (error) {
-    const duration = Date.now() - startTime;
-
-    // Log error with full context
-    ctx.log('error', 'Workflow failed', {
-      duration,
-      error: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-      status: 'error'
-    });
-
-    throw error;
-  }
-});
-```
-
-### Log Levels
-
-| Level | Use Case | Example |
-|-------|----------|---------|
-| **debug** | Detailed diagnostics | Variable values, flow control |
-| **info** | General information | Workflow start/end, record counts |
-| **warn** | Potentially harmful situations | Rate limits approaching, fallback used |
-| **error** | Error events | API failures, validation errors |
-
----
-
-## Performance Monitoring
-
-### Execution Metrics
-
-```typescript
-import { http } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const monitoredWorkflow = http('monitored', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  const startTime = Date.now();
-  const metricsKey = `metrics:${ctx.workflow?.name}`;
-
-  try {
-    // Execute workflow
-    const result = await executeWorkflow(ctx);
-
-    const duration = Date.now() - startTime;
-
-    // Store metrics
-    const metrics = await adapter.get(metricsKey) || { executions: [] };
-    metrics.executions.push({
-      timestamp: Date.now(),
-      duration,
-      status: 'success',
-      recordCount: result.count
-    });
-
-    // Keep last 100 executions
-    if (metrics.executions.length > 100) {
-      metrics.executions = metrics.executions.slice(-100);
-    }
-
-    await adapter.set(metricsKey, metrics);
-
-    // Calculate stats
-    const avgDuration = metrics.executions.reduce((sum, e) => sum + e.duration, 0) / metrics.executions.length;
-    const successRate = metrics.executions.filter(e => e.status === 'success').length / metrics.executions.length;
-
-    ctx.log('info', 'Workflow metrics', {
-      duration,
-      avgDuration: Math.round(avgDuration),
-      successRate: (successRate * 100).toFixed(2) + '%',
-      totalExecutions: metrics.executions.length
-    });
-
-    return result;
-
-  } catch (error) {
-    const duration = Date.now() - startTime;
-
-    // Store error metrics
-    const metrics = await adapter.get(metricsKey) || { executions: [] };
-    metrics.executions.push({
-      timestamp: Date.now(),
-      duration,
-      status: 'error',
-      error: error instanceof Error ? error.message : String(error)
-    });
-
-    await adapter.set(metricsKey, metrics);
-
-    throw error;
-  }
-});
-```
-
-### Health Check Endpoint
-
-```typescript
-export const healthCheck = http('health', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const checks = {
-    fluentConnection: false,
-    kvStorage: false,
-    environment: ctx.vars?.ENVIRONMENT || 'unknown'
-  };
-
-  // Check Fluent connection
-  try {
-    const client = await createClient(ctx);
-    await client.graphql({ query: `query { __typename }` });
-    checks.fluentConnection = true;
-  } catch (error) {
-    ctx.log('error', 'Fluent connection check failed', { error });
-  }
-
-  // Check KV storage
-  try {
-    const kv = ctx.openKv(':project:');
-    await kv.set('health:check', Date.now(), { ttl: 60000 });
-    const value = await kv.get('health:check');
-    checks.kvStorage = !!value;
-  } catch (error) {
-    ctx.log('error', 'KV storage check failed', { error });
-  }
-
-  const healthy = checks.fluentConnection && checks.kvStorage;
-
-  return {
-    status: healthy ? 'healthy' : 'unhealthy',
-    timestamp: new Date().toISOString(),
-    checks
-  };
-});
-```
-
----
-
-## CI/CD Integration
-
-### GitHub Actions Example
-
-```yaml
-# .github/workflows/deploy-versori.yml
-name: Deploy to Versori
-
-on:
-  push:
-    branches:
-      - main
-      - staging
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint code
-        run: npm run lint
-
-      - name: Type check
-        run: npm run validate
-
-      - name: Run tests
-        run: npm test
-
-      - name: Build project
-        run: npm run build
-
-      - name: Deploy to Versori (Production)
-        if: github.ref == 'refs/heads/main'
-        env:
-          VERSORI_API_KEY: ${{ secrets.VERSORI_API_KEY_PROD }}
-        run: versori deploy --env production
-
-      - name: Deploy to Versori (Staging)
-        if: github.ref == 'refs/heads/staging'
-        env:
-          VERSORI_API_KEY: ${{ secrets.VERSORI_API_KEY_STAGING }}
-        run: versori deploy --env staging
-
-      - name: Notify deployment
-        if: success()
-        run: |
-          echo "Deployment successful to ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}"
-```
-
-### GitLab CI Example
-
-```yaml
-# .gitlab-ci.yml
-stages:
-  - build
-  - test
-  - deploy
-
-variables:
-  NODE_VERSION: "20"
-
-build:
-  stage: build
-  image: node:${NODE_VERSION}
-  script:
-    - npm ci
-    - npm run build
-  artifacts:
-    paths:
-      - dist/
-    expire_in: 1 hour
-
-test:
-  stage: test
-  image: node:${NODE_VERSION}
-  script:
-    - npm ci
-    - npm run lint
-    - npm run validate
-    - npm test
-
-deploy_staging:
-  stage: deploy
-  image: node:${NODE_VERSION}
-  only:
-    - staging
-  script:
-    - npm ci
-    - versori deploy --env staging
-  environment:
-    name: staging
-
-deploy_production:
-  stage: deploy
-  image: node:${NODE_VERSION}
-  only:
-    - main
-  script:
-    - npm ci
-    - versori deploy --env production
-  environment:
-    name: production
-  when: manual
-```
-
----
-
-## Versioning & Rollback
-
-### Versioning Strategy
-
-Use semantic versioning in `package.json`:
-
-```json
-{
-  "version": "1.2.3"
-}
-```
-
-- **Major** (1.x.x): Breaking changes
-- **Minor** (x.2.x): New features, maintains API stability
-- **Patch** (x.x.3): Bug fixes
-
-### Deployment Tags
-
-Tag deployments in Git:
-
-```bash
-# Create version tag
-git tag v1.2.3
-
-# Push tag
-git push origin v1.2.3
-
-# Deploy specific version
-git checkout v1.2.3
-npm run deploy
-```
-
-### Rollback Strategy
-
-```bash
-# 1. Identify last known good version
-git log --oneline
-
-# 2. Checkout previous version
-git checkout v1.2.2
-
-# 3. Redeploy
-npm run build
-versori deploy
-
-# 4. Verify deployment
-versori logs --tail 50
-
-# 5. Tag rollback (optional)
-git tag v1.2.3-rollback
-git push origin v1.2.3-rollback
-```
-
----
-
-## Troubleshooting Production Issues
-
-### Debug Workflow Execution
-
-```typescript
-export const debugExecution = http('debug-execution', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Log all context information
-  const req = ctx.request();
-  ctx.log('debug', 'Full context dump', {
-    executionId: ctx.executionId,
-    workflow: ctx.workflow?.name,
-    query: ctx.query,
-    data: ctx.data,
-    headers: req?.headers || {},
-    vars: Object.keys(ctx.vars || {}),  // Don't log secret values
-    connectionNames: Object.keys(ctx.connections || {})
-  });
-
-  // Test connection
-  try {
-    const client = await createClient(ctx);
-    ctx.log('debug', 'Client created successfully');
-
-    const result = await client.graphql({
-      query: `query { __typename }`
-    });
-
-    ctx.log('debug', 'GraphQL test successful', result);
-
-  } catch (error) {
-    ctx.log('error', 'Debug test failed', {
-      error: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined
-    });
-  }
-
-  return { debug: 'complete' };
-});
-```
-
-### Common Production Issues
-
-| Issue | Symptoms | Solution |
-|-------|----------|----------|
-| **Timeout errors** | Workflow exceeds time limit | Optimize queries, use pagination, increase timeout |
-| **Memory errors** | Out of memory failures | Process in smaller batches, use streaming |
-| **Rate limiting** | 429 errors from Fluent API | Implement backoff, reduce request frequency |
-| **Connection failures** | Authentication errors | Verify credentials, check token expiration |
-| **Duplicate processing** | Files processed multiple times | Use VersoriFileTracker, implement idempotency |
-
----
-
-## Key Takeaways
-
-- 🎯 **Package.json** must have `versori.workflows` entry pointing to built JS
-- 🎯 **Environment management** via connector variables and environment-specific connections
-- 🎯 **Structured logging** with ctx.log() provides visibility into workflow execution
-- 🎯 **CI/CD pipelines** automate build, test, and deployment processes
-- 🎯 **Versioning strategy** enables controlled releases and rollbacks
-- 🎯 **Health checks** ensure system readiness and component status
-- 🎯 **Monitoring metrics** track performance and identify issues
-
----
-
-## Practice Exercise
-
-Create a deployment pipeline that:
-1. Validates TypeScript compilation
-2. Runs automated tests
-3. Deploys to staging on push to `staging` branch
-4. Deploys to production on manual approval
-5. Implements health check endpoint
-6. Tracks deployment metrics in KV storage
-7. Provides rollback capability
-
-**Hints**:
-- Use GitHub Actions or GitLab CI
-- Implement environment-specific configurations
-- Add health check workflow
-- Store deployment history in KV
-- Tag releases in Git
-
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
-
----
-
-## Next Steps
-
-Now that you understand deployment and monitoring, let's explore production best practices and advanced patterns.
-
-Continue to [Module 8: Best Practices →](./platforms-versori-08-best-practices.md) to learn about production patterns, error handling, security hardening, and troubleshooting.
-
----
-
-## Related Documentation
-
-- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management for monitoring
-- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Production patterns
-- [Getting Started Guide](../../../../00-START-HERE/getting-started.md) - SDK basics
-- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
-
----
-
-[← Previous: Module 6](./platforms-versori-06-kv-storage.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 8: Best Practices →](./platforms-versori-08-best-practices.md)
+# Module 7: Deployment, Monitoring & Operations
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 7 of 8** | **Level**: Advanced | **Time**: 30 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Deploy connectors to Versori Platform
+- ✅ Monitor workflow execution and logs
+- ✅ Implement CI/CD pipelines for automated deployment
+- ✅ Manage environment-specific configurations
+- ✅ Handle versioning and rollback strategies
+- ✅ Debug production issues effectively
+- ✅ Optimize deployment for performance
+
+---
+
+## Deployment Workflow
+
+### Pre-Deployment Checklist
+
+Before deploying to Versori, ensure:
+
+- [ ] All TypeScript code compiles without errors
+- [ ] Connections configured in Versori UI
+- [ ] Connector variables set (secrets, config)
+- [ ] `package.json` has correct `versori.workflows` entry
+- [ ] Environment-specific settings verified
+- [ ] Test workflows validated locally
+- [ ] Documentation updated
+
+---
+
+## Local Development & Testing
+
+### Project Structure
+
+```
+my-fluent-connector/
+├── src/
+│   ├── index.ts                    # Main entry point
+│   ├── workflows/
+│   │   ├── inventory-sync.ts       # Scheduled workflows
+│   │   ├── order-webhook.ts        # Webhook receivers
+│   │   └── query-api.ts            # HTTP workflows
+│   ├── config/
+│   │   ├── mappings.json           # Field mappings
+│   │   └── constants.ts            # Configuration constants
+│   └── utils/
+│       ├── transformers.ts         # Data transformation helpers
+│       └── validators.ts           # Validation utilities
+├── dist/                           # Build output (gitignored)
+├── node_modules/                   # Dependencies (gitignored)
+├── package.json                    # Package configuration
+├── tsconfig.json                   # TypeScript configuration
+├── .env.example                    # Environment variable template
+└── readme.md                       # Connector documentation
+```
+
+### Package.json Configuration
+
+```json
+{
+  "name": "fluent-inventory-connector",
+  "version": "1.0.0",
+  "description": "Fluent Commerce inventory integration",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "deploy": "npm run build && versori deploy",
+    "logs": "versori logs --follow",
+    "validate": "tsc --noEmit",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "latest",
+    "@versori/run": "^0.4.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "jest": "^29.0.0"
+  },
+  "versori": {
+    "workflows": "dist/index.js"
+  }
+}
+```
+
+**CRITICAL**: The `versori.workflows` field tells Versori where to find exported workflows.
+
+### TypeScript Build
+
+```bash
+# Compile TypeScript
+npm run build
+
+# Validate without building
+npm run validate
+
+# Watch mode for development
+tsc --watch
+```
+
+---
+
+## Deploying to Versori
+
+### Manual Deployment
+
+```bash
+# 1. Build TypeScript
+npm run build
+
+# 2. Deploy to Versori
+versori deploy
+
+# Expected output:
+# ✓ Building project...
+# ✓ Uploading to Versori...
+# ✓ Deployment successful
+#
+# Workflows deployed:
+#   - query-inventory (HTTP)
+#     URL: https://{workspace}.versori.run/query-inventory
+#   - receive-order (Webhook)
+#     URL: https://{workspace}.versori.run/receive-order
+#   - daily-sync (Scheduled)
+#     Schedule: 0 2 * * *
+```
+
+### Deploy Script
+
+```bash
+# Combined build + deploy
+npm run deploy
+```
+
+### Deployment Output
+
+Versori deployment creates:
+- **HTTP endpoints** for `http()` workflows
+- **Webhook URLs** for `webhook()` workflows
+- **Scheduled jobs** for `schedule()` workflows
+- **Internal functions** (not exposed) for `fn()` workflows
+
+---
+
+## Environment Management
+
+### Environment-Specific Configurations
+
+Maintain separate configurations per environment:
+
+```typescript
+// src/config/environments.ts
+export const environments = {
+  development: {
+    fluentConnection: 'fluent_commerce_dev',
+    s3Bucket: 'inventory-dev',
+    logLevel: 'debug',
+    batchSize: 10
+  },
+  staging: {
+    fluentConnection: 'fluent_commerce_staging',
+    s3Bucket: 'inventory-staging',
+    logLevel: 'info',
+    batchSize: 50
+  },
+  production: {
+    fluentConnection: 'fluent_commerce_prod',
+    s3Bucket: 'inventory-prod',
+    logLevel: 'warn',
+    batchSize: 100
+  }
+};
+
+export function getConfig(env: string = 'production') {
+  return environments[env as keyof typeof environments] || environments.production;
+}
+```
+
+### Using Environment Configuration
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import { getConfig } from './config/environments';
+
+export const envAwareWorkflow = http('env-aware', async (ctx) => {
+  // Get environment from connector variable or default to production
+  const env = ctx.vars?.ENVIRONMENT || 'production';
+  const config = getConfig(env);
+
+  ctx.log('info', 'Running in environment', { env, config });
+
+  // Use environment-specific connection
+  const client = await createClient({
+    connection: ctx.connections?.[config.fluentConnection],
+    log: ctx.log
+  });
+
+  // Use environment-specific settings
+  const batchSize = config.batchSize;
+
+  // ... rest of workflow
+});
+```
+
+### Connector Variables in Versori
+
+Set environment-specific variables in Versori UI:
+
+**Development**:
+```
+ENVIRONMENT=development
+FLUENT_RETAILER_ID=1
+LOG_LEVEL=debug
+AWS_S3_BUCKET=inventory-dev
+```
+
+**Production**:
+```
+ENVIRONMENT=production
+FLUENT_RETAILER_ID=1
+LOG_LEVEL=warn
+AWS_S3_BUCKET=inventory-prod
+FLUENT_WEBHOOK_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...
+```
+
+---
+
+## Monitoring & Logging
+
+### Viewing Logs
+
+#### Versori Dashboard
+
+1. Navigate to **Workflows** tab
+2. Select workflow
+3. Click **Executions** tab
+4. View:
+   - Execution timestamp
+   - Duration (ms)
+   - Status (success/error)
+   - Logs (`ctx.log()` calls)
+   - Input/output data
+
+#### CLI Logs
+
+```bash
+# Follow logs in real-time
+versori logs --follow
+
+# Filter by workflow
+versori logs --workflow query-inventory
+
+# Filter by level
+versori logs --level error
+
+# Show last N entries
+versori logs --tail 100
+
+# Filter by date range
+versori logs --since 2025-01-15 --until 2025-01-16
+```
+
+### Structured Logging Best Practices
+
+```typescript
+export const wellLogged = http('well-logged', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Log workflow start with context
+  ctx.log('info', 'Workflow started', {
+    workflow: 'well-logged',
+    executionId: ctx.executionId,
+    timestamp: new Date().toISOString()
+  });
+
+  const startTime = Date.now();
+
+  try {
+    const client = await createClient(ctx);
+
+    // Log before expensive operations
+    ctx.log('debug', 'Fetching data from Fluent API');
+
+    const result = await client.graphql({
+      query: `query { products(first: 100) { edges { node { id ref } } } }`
+    });
+
+    const duration = Date.now() - startTime;
+
+    // Log success with metrics
+    ctx.log('info', 'Workflow completed successfully', {
+      duration,
+      recordCount: result.data.products.edges.length,
+      status: 'success'
+    });
+
+    return result.data;
+
+  } catch (error) {
+    const duration = Date.now() - startTime;
+
+    // Log error with full context
+    ctx.log('error', 'Workflow failed', {
+      duration,
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      status: 'error'
+    });
+
+    throw error;
+  }
+});
+```
+
+### Log Levels
+
+| Level | Use Case | Example |
+|-------|----------|---------|
+| **debug** | Detailed diagnostics | Variable values, flow control |
+| **info** | General information | Workflow start/end, record counts |
+| **warn** | Potentially harmful situations | Rate limits approaching, fallback used |
+| **error** | Error events | API failures, validation errors |
+
+---
+
+## Performance Monitoring
+
+### Execution Metrics
+
+```typescript
+import { http } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const monitoredWorkflow = http('monitored', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  const startTime = Date.now();
+  const metricsKey = `metrics:${ctx.workflow?.name}`;
+
+  try {
+    // Execute workflow
+    const result = await executeWorkflow(ctx);
+
+    const duration = Date.now() - startTime;
+
+    // Store metrics
+    const metrics = await adapter.get(metricsKey) || { executions: [] };
+    metrics.executions.push({
+      timestamp: Date.now(),
+      duration,
+      status: 'success',
+      recordCount: result.count
+    });
+
+    // Keep last 100 executions
+    if (metrics.executions.length > 100) {
+      metrics.executions = metrics.executions.slice(-100);
+    }
+
+    await adapter.set(metricsKey, metrics);
+
+    // Calculate stats
+    const avgDuration = metrics.executions.reduce((sum, e) => sum + e.duration, 0) / metrics.executions.length;
+    const successRate = metrics.executions.filter(e => e.status === 'success').length / metrics.executions.length;
+
+    ctx.log('info', 'Workflow metrics', {
+      duration,
+      avgDuration: Math.round(avgDuration),
+      successRate: (successRate * 100).toFixed(2) + '%',
+      totalExecutions: metrics.executions.length
+    });
+
+    return result;
+
+  } catch (error) {
+    const duration = Date.now() - startTime;
+
+    // Store error metrics
+    const metrics = await adapter.get(metricsKey) || { executions: [] };
+    metrics.executions.push({
+      timestamp: Date.now(),
+      duration,
+      status: 'error',
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    await adapter.set(metricsKey, metrics);
+
+    throw error;
+  }
+});
+```
+
+### Health Check Endpoint
+
+```typescript
+export const healthCheck = http('health', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const checks = {
+    fluentConnection: false,
+    kvStorage: false,
+    environment: ctx.vars?.ENVIRONMENT || 'unknown'
+  };
+
+  // Check Fluent connection
+  try {
+    const client = await createClient(ctx);
+    await client.graphql({ query: `query { __typename }` });
+    checks.fluentConnection = true;
+  } catch (error) {
+    ctx.log('error', 'Fluent connection check failed', { error });
+  }
+
+  // Check KV storage
+  try {
+    const kv = ctx.openKv(':project:');
+    await kv.set('health:check', Date.now(), { ttl: 60000 });
+    const value = await kv.get('health:check');
+    checks.kvStorage = !!value;
+  } catch (error) {
+    ctx.log('error', 'KV storage check failed', { error });
+  }
+
+  const healthy = checks.fluentConnection && checks.kvStorage;
+
+  return {
+    status: healthy ? 'healthy' : 'unhealthy',
+    timestamp: new Date().toISOString(),
+    checks
+  };
+});
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/deploy-versori.yml
+name: Deploy to Versori
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint code
+        run: npm run lint
+
+      - name: Type check
+        run: npm run validate
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build project
+        run: npm run build
+
+      - name: Deploy to Versori (Production)
+        if: github.ref == 'refs/heads/main'
+        env:
+          VERSORI_API_KEY: ${{ secrets.VERSORI_API_KEY_PROD }}
+        run: versori deploy --env production
+
+      - name: Deploy to Versori (Staging)
+        if: github.ref == 'refs/heads/staging'
+        env:
+          VERSORI_API_KEY: ${{ secrets.VERSORI_API_KEY_STAGING }}
+        run: versori deploy --env staging
+
+      - name: Notify deployment
+        if: success()
+        run: |
+          echo "Deployment successful to ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}"
+```
+
+### GitLab CI Example
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - build
+  - test
+  - deploy
+
+variables:
+  NODE_VERSION: "20"
+
+build:
+  stage: build
+  image: node:${NODE_VERSION}
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 hour
+
+test:
+  stage: test
+  image: node:${NODE_VERSION}
+  script:
+    - npm ci
+    - npm run lint
+    - npm run validate
+    - npm test
+
+deploy_staging:
+  stage: deploy
+  image: node:${NODE_VERSION}
+  only:
+    - staging
+  script:
+    - npm ci
+    - versori deploy --env staging
+  environment:
+    name: staging
+
+deploy_production:
+  stage: deploy
+  image: node:${NODE_VERSION}
+  only:
+    - main
+  script:
+    - npm ci
+    - versori deploy --env production
+  environment:
+    name: production
+  when: manual
+```
+
+---
+
+## Versioning & Rollback
+
+### Versioning Strategy
+
+Use semantic versioning in `package.json`:
+
+```json
+{
+  "version": "1.2.3"
+}
+```
+
+- **Major** (1.x.x): Breaking changes
+- **Minor** (x.2.x): New features, maintains API stability
+- **Patch** (x.x.3): Bug fixes
+
+### Deployment Tags
+
+Tag deployments in Git:
+
+```bash
+# Create version tag
+git tag v1.2.3
+
+# Push tag
+git push origin v1.2.3
+
+# Deploy specific version
+git checkout v1.2.3
+npm run deploy
+```
+
+### Rollback Strategy
+
+```bash
+# 1. Identify last known good version
+git log --oneline
+
+# 2. Checkout previous version
+git checkout v1.2.2
+
+# 3. Redeploy
+npm run build
+versori deploy
+
+# 4. Verify deployment
+versori logs --tail 50
+
+# 5. Tag rollback (optional)
+git tag v1.2.3-rollback
+git push origin v1.2.3-rollback
+```
+
+---
+
+## Troubleshooting Production Issues
+
+### Debug Workflow Execution
+
+```typescript
+export const debugExecution = http('debug-execution', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Log all context information
+  const req = ctx.request();
+  ctx.log('debug', 'Full context dump', {
+    executionId: ctx.executionId,
+    workflow: ctx.workflow?.name,
+    query: ctx.query,
+    data: ctx.data,
+    headers: req?.headers || {},
+    vars: Object.keys(ctx.vars || {}),  // Don't log secret values
+    connectionNames: Object.keys(ctx.connections || {})
+  });
+
+  // Test connection
+  try {
+    const client = await createClient(ctx);
+    ctx.log('debug', 'Client created successfully');
+
+    const result = await client.graphql({
+      query: `query { __typename }`
+    });
+
+    ctx.log('debug', 'GraphQL test successful', result);
+
+  } catch (error) {
+    ctx.log('error', 'Debug test failed', {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined
+    });
+  }
+
+  return { debug: 'complete' };
+});
+```
+
+### Common Production Issues
+
+| Issue | Symptoms | Solution |
+|-------|----------|----------|
+| **Timeout errors** | Workflow exceeds time limit | Optimize queries, use pagination, increase timeout |
+| **Memory errors** | Out of memory failures | Process in smaller batches, use streaming |
+| **Rate limiting** | 429 errors from Fluent API | Implement backoff, reduce request frequency |
+| **Connection failures** | Authentication errors | Verify credentials, check token expiration |
+| **Duplicate processing** | Files processed multiple times | Use VersoriFileTracker, implement idempotency |
+
+---
+
+## Key Takeaways
+
+- 🎯 **Package.json** must have `versori.workflows` entry pointing to built JS
+- 🎯 **Environment management** via connector variables and environment-specific connections
+- 🎯 **Structured logging** with ctx.log() provides visibility into workflow execution
+- 🎯 **CI/CD pipelines** automate build, test, and deployment processes
+- 🎯 **Versioning strategy** enables controlled releases and rollbacks
+- 🎯 **Health checks** ensure system readiness and component status
+- 🎯 **Monitoring metrics** track performance and identify issues
+
+---
+
+## Practice Exercise
+
+Create a deployment pipeline that:
+1. Validates TypeScript compilation
+2. Runs automated tests
+3. Deploys to staging on push to `staging` branch
+4. Deploys to production on manual approval
+5. Implements health check endpoint
+6. Tracks deployment metrics in KV storage
+7. Provides rollback capability
+
+**Hints**:
+- Use GitHub Actions or GitLab CI
+- Implement environment-specific configurations
+- Add health check workflow
+- Store deployment history in KV
+- Tag releases in Git
+
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+
+---
+
+## Next Steps
+
+Now that you understand deployment and monitoring, let's explore production best practices and advanced patterns.
+
+Continue to [Module 8: Best Practices →](./platforms-versori-08-best-practices.md) to learn about production patterns, error handling, security hardening, and troubleshooting.
+
+---
+
+## Related Documentation
+
+- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management for monitoring
+- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Production patterns
+- [Getting Started Guide](../../../../00-START-HERE/getting-started.md) - SDK basics
+- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
+
+---
+
+[← Previous: Module 6](./platforms-versori-06-kv-storage.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 8: Best Practices →](./platforms-versori-08-best-practices.md)