@tuongaz/seeflow 0.1.25 → 0.1.27

package/examples/ecommerce-platform/.seeflow/{seeflow.json → architecture.json}

@@ -1,30 +1,19 @@
 {
-  "version": 1,
+  "version": 2,
   "name": "E-Commerce Platform",
   "nodes": [
     {
       "id": "client",
       "type": "shapeNode",
-      "position": {
-        "x": 80,
-        "y": 215.5
-      },
       "data": {
         "shape": "user",
         "name": "Customer",
-        "description": "Web / Mobile / Partner",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "description": "Web / Mobile / Partner"
       }
     },
     {
       "id": "api-gateway",
       "type": "playNode",
-      "position": {
-        "x": 320,
-        "y": 227
-      },
       "data": {
         "name": "API Gateway",
         "kind": "gateway",
@@ -32,7 +21,7 @@
           "kind": "request"
         },
         "description": "Auth, rate-limiting, routing.",
-        "detail": "## API Gateway\n\nCentral ingress for every client.\n\n- JWT validation before forwarding\n- Token-bucket rate limiting per user and IP\n- Path-based routing to downstream services\n- OpenTelemetry spans for every request\n\n### Routes\n- `POST /auth/*` → Auth Service\n- `GET /products/*` → Product Catalog\n- `POST /cart/*` → Cart Service\n- `POST /orders` → Order Service",
+        "detail": "file://details/api-gateway.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -40,19 +29,12 @@
             "run"
           ],
           "scriptPath": "scripts/play.ts"
-        },
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        }
       }
     },
     {
       "id": "auth-service",
       "type": "stateNode",
-      "position": {
-        "x": 660,
-        "y": 50
-      },
       "data": {
         "name": "Auth Service",
         "kind": "service",
@@ -60,19 +42,12 @@
           "kind": "request"
         },
         "description": "JWT issuance + OAuth2 / OIDC.",
-        "detail": "## Auth Service\n\n- Password login (bcrypt), OAuth2 (Google, Apple), magic-link\n- Access token: 15-min TTL, RS256 signed\n- Refresh token: 30-day TTL in Redis\n\n### Events\n- `auth.login` on success\n- `auth.token_refreshed` on refresh",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "detail": "file://details/auth-service.md"
       }
     },
     {
       "id": "product-service",
       "type": "stateNode",
-      "position": {
-        "x": 660,
-        "y": 218
-      },
       "data": {
         "name": "Product Catalog",
         "kind": "service",
@@ -80,19 +55,12 @@
           "kind": "request"
         },
         "description": "SKUs, variants, pricing, full-text search.",
-        "detail": "## Product Catalog\n\nSingle source of truth for products and search.\n\n- Products, variants, tiered pricing (B2B / B2C / promo)\n- Elasticsearch full-text search with BM25 ranking\n- Faceted filtering (brand, price, rating, availability)\n\n### Events\n- `product.updated` → re-indexes search",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "detail": "file://details/product-service.md"
       }
     },
     {
       "id": "cart-service",
       "type": "playNode",
-      "position": {
-        "x": 660,
-        "y": 413
-      },
       "data": {
         "name": "Cart Service",
         "kind": "service",
@@ -100,7 +68,7 @@
           "kind": "request"
         },
         "description": "Add/remove items, apply coupons, checkout.",
-        "detail": "## Cart Service\n\nPer-user cart stored in Redis.\n\n- `addItem(sku, qty)` — validates stock, adds line item\n- `applyCoupon(code)` — validates and applies discount\n- `checkout()` — freezes cart, emits `cart.checkout`\n\n### Events Emitted\n- `cart.checkout` → Order Service",
+        "detail": "file://details/cart-service.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -108,27 +76,20 @@
             "run"
           ],
           "scriptPath": "scripts/play.ts"
-        },
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        }
       }
     },
     {
       "id": "order-service",
       "type": "playNode",
-      "position": {
-        "x": 1000,
-        "y": 413
-      },
       "data": {
         "name": "Order Service",
         "kind": "worker",
         "stateSource": {
           "kind": "event"
         },
-        "description": "pending → confirmed → shipped → delivered.",
-        "detail": "## Order Service\n\nOwns the order record and drives the downstream pipeline.\n\n### State Machine\n```\npending → confirmed → processing → shipped → delivered\n       ↘ cancelled\n```\n\n### Triggered by\n- `cart.checkout` event\n\n### Events Emitted\n- `order.created` → Payment Service\n- `order.cancelled` → Notification Service",
+        "description": "pending \u2192 confirmed \u2192 shipped \u2192 delivered.",
+        "detail": "file://details/order-service.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -136,19 +97,12 @@
             "run"
           ],
           "scriptPath": "scripts/play.ts"
-        },
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        }
       }
     },
     {
       "id": "payment-service",
       "type": "stateNode",
-      "position": {
-        "x": 1340,
-        "y": 349
-      },
       "data": {
         "name": "Payment Service",
         "kind": "worker",
@@ -156,19 +110,12 @@
           "kind": "event"
         },
         "description": "Stripe + PayPal gateway integration.",
-        "detail": "## Payment Service\n\nCharges the customer and records the transaction.\n\n### Triggered by\n- `order.created`\n\n### Steps\n1. Retrieve saved payment method\n2. Authorise charge via Stripe\n3. Capture funds\n4. Persist charge record\n\n### Events Emitted\n- `payment.captured` → Notification Service\n- `payment.failed` → Notification Service",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "detail": "file://details/payment-service.md"
       }
     },
     {
       "id": "notification-service",
       "type": "stateNode",
-      "position": {
-        "x": 1680,
-        "y": 339
-      },
       "data": {
         "name": "Notification Service",
         "kind": "worker",
@@ -176,26 +123,16 @@
           "kind": "event"
         },
         "description": "Email + SMS + push via AWS SES / SNS.",
-        "detail": "## Notification Service\n\nDelivers transactional messages.\n\n### Channels\n- **Email** — AWS SES with DKIM/DMARC\n- **SMS** — Twilio for OTP and shipping alerts\n- **Push** — Firebase Cloud Messaging\n\n### Triggered by\n- `payment.captured` — order confirmation\n- `payment.failed` — retry prompt\n- `order.cancelled` — refund notification",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "detail": "file://details/notification-service.md"
       }
     },
     {
       "id": "postgresql",
       "type": "shapeNode",
-      "position": {
-        "x": 1720,
-        "y": 507
-      },
       "data": {
         "shape": "database",
         "name": "PostgreSQL",
-        "description": "Orders, users, products — primary OLTP store",
-        "fontSize": 15,
-        "borderColor": "green",
-        "borderSize": 1
+        "description": "Orders, users, products \u2014 primary OLTP store"
       }
     }
   ],

package/examples/ecommerce-platform/.seeflow/details/api-gateway.md

@@ -0,0 +1,14 @@
+## API Gateway
+
+Central ingress for every client.
+
+- JWT validation before forwarding
+- Token-bucket rate limiting per user and IP
+- Path-based routing to downstream services
+- OpenTelemetry spans for every request
+
+### Routes
+- `POST /auth/*` → Auth Service
+- `GET /products/*` → Product Catalog
+- `POST /cart/*` → Cart Service
+- `POST /orders` → Order Service

package/examples/ecommerce-platform/.seeflow/details/auth-service.md

@@ -0,0 +1,9 @@
+## Auth Service
+
+- Password login (bcrypt), OAuth2 (Google, Apple), magic-link
+- Access token: 15-min TTL, RS256 signed
+- Refresh token: 30-day TTL in Redis
+
+### Events
+- `auth.login` on success
+- `auth.token_refreshed` on refresh

package/examples/ecommerce-platform/.seeflow/details/cart-service.md

@@ -0,0 +1,10 @@
+## Cart Service
+
+Per-user cart stored in Redis.
+
+- `addItem(sku, qty)` — validates stock, adds line item
+- `applyCoupon(code)` — validates and applies discount
+- `checkout()` — freezes cart, emits `cart.checkout`
+
+### Events Emitted
+- `cart.checkout` → Order Service

package/examples/ecommerce-platform/.seeflow/details/notification-service.md

@@ -0,0 +1,13 @@
+## Notification Service
+
+Delivers transactional messages.
+
+### Channels
+- **Email** — AWS SES with DKIM/DMARC
+- **SMS** — Twilio for OTP and shipping alerts
+- **Push** — Firebase Cloud Messaging
+
+### Triggered by
+- `payment.captured` — order confirmation
+- `payment.failed` — retry prompt
+- `order.cancelled` — refund notification

package/examples/ecommerce-platform/.seeflow/details/order-service.md

@@ -0,0 +1,16 @@
+## Order Service
+
+Owns the order record and drives the downstream pipeline.
+
+### State Machine
+```
+pending → confirmed → processing → shipped → delivered
+       ↘ cancelled
+```
+
+### Triggered by
+- `cart.checkout` event
+
+### Events Emitted
+- `order.created` → Payment Service
+- `order.cancelled` → Notification Service

package/examples/ecommerce-platform/.seeflow/details/payment-service.md

@@ -0,0 +1,16 @@
+## Payment Service
+
+Charges the customer and records the transaction.
+
+### Triggered by
+- `order.created`
+
+### Steps
+1. Retrieve saved payment method
+2. Authorise charge via Stripe
+3. Capture funds
+4. Persist charge record
+
+### Events Emitted
+- `payment.captured` → Notification Service
+- `payment.failed` → Notification Service

package/examples/ecommerce-platform/.seeflow/details/product-service.md

@@ -0,0 +1,10 @@
+## Product Catalog
+
+Single source of truth for products and search.
+
+- Products, variants, tiered pricing (B2B / B2C / promo)
+- Elasticsearch full-text search with BM25 ranking
+- Faceted filtering (brand, price, rating, availability)
+
+### Events
+- `product.updated` → re-indexes search

package/examples/ecommerce-platform/.seeflow/style.json

@@ -0,0 +1,85 @@
+{
+  "nodes": {
+    "client": {
+      "position": {
+        "x": 80,
+        "y": 215.5
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "api-gateway": {
+      "position": {
+        "x": 320,
+        "y": 227
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "auth-service": {
+      "position": {
+        "x": 660,
+        "y": 50
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "product-service": {
+      "position": {
+        "x": 660,
+        "y": 218
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "cart-service": {
+      "position": {
+        "x": 660,
+        "y": 413
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "order-service": {
+      "position": {
+        "x": 1000,
+        "y": 413
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "payment-service": {
+      "position": {
+        "x": 1340,
+        "y": 349
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "notification-service": {
+      "position": {
+        "x": 1680,
+        "y": 339
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "postgresql": {
+      "position": {
+        "x": 1720,
+        "y": 507
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    }
+  }
+}

package/examples/order-pipeline/.seeflow/architecture.json

@@ -0,0 +1,93 @@
+{
+  "version": 2,
+  "name": "Order Pipeline",
+  "nodes": [
+    {
+      "id": "post-orders",
+      "type": "playNode",
+      "data": {
+        "name": "POST /orders",
+        "kind": "service",
+        "stateSource": {
+          "kind": "request"
+        },
+        "description": "Creates order, kicks off the pipeline.",
+        "detail": "file://details/post-orders.md",
+        "playAction": {
+          "kind": "script",
+          "interpreter": "bun",
+          "args": [
+            "run"
+          ],
+          "scriptPath": "scripts/play.ts"
+        }
+      }
+    },
+    {
+      "id": "inventory-service",
+      "type": "stateNode",
+      "data": {
+        "name": "Inventory Service",
+        "kind": "worker",
+        "stateSource": {
+          "kind": "event"
+        },
+        "description": "Reserves stock.",
+        "detail": "file://details/inventory-service.md",
+        "icon": "a-arrow-down-icon"
+      }
+    },
+    {
+      "id": "payment-service",
+      "type": "stateNode",
+      "data": {
+        "name": "Payment Service",
+        "kind": "worker",
+        "stateSource": {
+          "kind": "event"
+        },
+        "description": "Charges card.",
+        "detail": "file://details/payment-service.md"
+      }
+    },
+    {
+      "id": "fulfillment-service",
+      "type": "stateNode",
+      "data": {
+        "name": "Fulfillment Service",
+        "kind": "worker",
+        "stateSource": {
+          "kind": "event"
+        },
+        "description": "Enqueues shipment.",
+        "detail": "file://details/fulfillment-service.md"
+      }
+    }
+  ],
+  "connectors": [
+    {
+      "id": "c1",
+      "source": "post-orders",
+      "target": "inventory-service",
+      "kind": "event",
+      "eventName": "order.created",
+      "label": "order.created"
+    },
+    {
+      "id": "c2",
+      "source": "inventory-service",
+      "target": "payment-service",
+      "kind": "event",
+      "eventName": "stock.reserved",
+      "label": "stock.reserved"
+    },
+    {
+      "id": "c3",
+      "source": "payment-service",
+      "target": "fulfillment-service",
+      "kind": "event",
+      "eventName": "payment.captured",
+      "label": "payment.captured"
+    }
+  ]
+}

package/examples/order-pipeline/.seeflow/details/fulfillment-service.md

@@ -0,0 +1,21 @@
+## Fulfillment Service
+
+Listens for `payment.captured` and enqueues a shipment job for the warehouse to pick, pack, and dispatch the order. Assigns a tracking ID and notifies the customer.
+
+### Triggered by
+- `payment.captured`
+
+### Logic
+1. Convert the stock reservation into a pick list
+2. Assign a carrier and service level
+3. Generate a shipment ID and tracking number
+4. Push the job to the warehouse queue
+5. Send dispatch confirmation to the customer
+
+### Payload
+```json
+{
+  "shipmentId": "shp_1234567890",
+  "orderId": "ord_1234567890"
+}
+```

package/examples/order-pipeline/.seeflow/details/inventory-service.md

@@ -0,0 +1,23 @@
+## Inventory Service
+
+Listens for `order.created` and attempts to reserve the requested stock in the warehouse. Checks available quantity, places a hold on the items, and records the warehouse location.
+
+### Triggered by
+- `order.created`
+
+### Logic
+1. Look up each SKU in the warehouse
+2. Verify sufficient quantity is available
+3. Place a reservation hold
+4. Record the fulfilling warehouse ID
+
+### Emits
+- `stock.reserved` → Payment Service
+
+### Payload
+```json
+{
+  "reserved": true,
+  "warehouseId": "wh_sydney"
+}
+```

package/examples/order-pipeline/.seeflow/details/payment-service.md

@@ -0,0 +1,23 @@
+## Payment Service
+
+Listens for `stock.reserved` and charges the customer's card on file. Integrates with the payment gateway to authorise and capture funds for the order total.
+
+### Triggered by
+- `stock.reserved`
+
+### Logic
+1. Retrieve customer's saved payment method
+2. Calculate order total (items + tax + shipping)
+3. Authorise charge with payment gateway
+4. Capture funds and record the charge ID
+
+### Emits
+- `payment.captured` → Fulfillment Service
+
+### Payload
+```json
+{
+  "chargeId": "ch_1234567890",
+  "amount": 4999
+}
+```

package/examples/order-pipeline/.seeflow/details/post-orders.md

@@ -0,0 +1,19 @@
+## POST /orders
+
+Entry point for the order pipeline. Accepts a customer ID and list of line items, creates an order record, and publishes the `order.created` event to kick off downstream processing.
+
+### Request
+```json
+{
+  "customerId": "cust_123",
+  "items": [{ "sku": "WIDGET-1", "qty": 2 }]
+}
+```
+
+### Response
+```json
+{ "orderId": "ord_1234567890" }
+```
+
+### Emits
+- `order.created` → Inventory Service

package/examples/order-pipeline/.seeflow/scripts/play.ts

@@ -1,4 +1,4 @@
-const demoId = process.env.SEEFLOW_DEMO_ID ?? '';
+const flowId = process.env.SEEFLOW_DEMO_ID ?? '';
 const runId = process.env.SEEFLOW_RUN_ID ?? '';
 const studioUrl = (process.env.SEEFLOW_STUDIO_URL ?? 'http://localhost:4321').replace(/\/+$/, '');
 
@@ -6,7 +6,7 @@ const res = await fetch(`${studioUrl}/demo/orders`, {
   method: 'POST',
   headers: {
     'content-type': 'application/json',
-    'x-seeflow-demo-id': demoId,
+    'x-seeflow-demo-id': flowId,
     'x-seeflow-run-id': runId,
   },
   body: JSON.stringify({ customerId: 'cust_123', items: [{ sku: 'WIDGET-1', qty: 2 }] }),

package/examples/order-pipeline/.seeflow/style.json

@@ -0,0 +1,42 @@
+{
+  "nodes": {
+    "post-orders": {
+      "position": {
+        "x": -181.96549037838943,
+        "y": 138.95644990042385
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "inventory-service": {
+      "position": {
+        "x": 66.21484197841792,
+        "y": -126.31035925520507
+      },
+      "width": 201,
+      "height": 118,
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    },
+    "payment-service": {
+      "position": {
+        "x": 469.1422114437386,
+        "y": 206.48855752663212
+      },
+      "borderSize": 1,
+      "fontSize": 15,
+      "borderColor": "green"
+    },
+    "fulfillment-service": {
+      "position": {
+        "x": 747.51321046746,
+        "y": -37.78865629343234
+      },
+      "fontSize": 15,
+      "borderColor": "green",
+      "borderSize": 1
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",