1 files changed, 126 insertions, 0 deletions
diff --git a/js/scripting-lang/design/implementation/FLOW_DIAGRAM.md b/js/scripting-lang/design/implementation/FLOW_DIAGRAM.md
new file mode 100644
index 0000000..56e1275
--- /dev/null
+++ b/js/scripting-lang/design/implementation/FLOW_DIAGRAM.md
@@ -0,0 +1,126 @@
+# Data Flow Diagram: ..listen and ..emit System
+
+## Overview
+This diagram shows how data flows through the functional scripting language with `..listen` and `..emit` IO words.
+
+## Flow Diagram
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   External      │    │     Adapter     │    │   Functional    │
+│   System        │    │   (WebSocket/   │    │    Harness      │
+│                 │    │    HTTP/etc)    │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         │ 1. Send Data          │                       │
+         │ (JSON state)          │                       │
+         │──────────────────────▶│                       │
+         │                       │                       │
+         │                       │ 2. processState()     │
+         │                       │──────────────────────▶│
+         │                       │                       │
+         │                       │                       │ 3. Script Execution
+         │                       │                       │   ┌─────────────┐
+         │                       │                       │   │   Script    │
+         │                       │                       │   │             │
+         │                       │                       │   │ ..listen    │
+         │                       │                       │   │ (get state) │
+         │                       │                       │   │             │
+         │                       │                       │   │ ..emit      │
+         │                       │                       │   │ (commands)  │
+         │                       │                       │   └─────────────┘
+         │                       │                       │
+         │                       │ 4. Return {model,     │
+         │                       │    commands, results} │
+         │                       │◀──────────────────────│
+         │                       │                       │
+         │ 5. Send Response      │                       │
+         │ (model + emitted      │                       │
+         │  data)                │                       │
+         │◀──────────────────────│                       │
+         │                       │                       │
+```
+
+## Detailed Flow
+
+### 1. External System Sends Data
+```
+WebSocket Client → WebSocket Server
+HTTP Client → HTTP Server
+Game Client → Game Server
+```
+
+### 2. Adapter Receives and Processes
+```javascript
+// WebSocket example
+ws.on('message', async (data) => {
+  const state = JSON.parse(data);
+  const result = await harness.processState(state, { ws });
+  // Handle result...
+});
+```
+
+### 3. Harness Processes State
+```javascript
+// FunctionalHarness.processState()
+async processState(newState, context = {}) {
+  const { model, commands } = await this.update(newState);
+  const results = await this.processCommands(commands, context);
+  return { model, commands, results };
+}
+```
+
+### 4. Script Execution
+```javascript
+// Script runs with environment
+game_state : ..listen;           // Gets current state
+new_score : game_state.score + 10;
+..emit { score: new_score };     // Creates command
+```
+
+### 5. Commands Processed
+```javascript
+// Adapter processes commands
+for (const result of results) {
+  if (result.type === 'emit') {
+    ws.send(JSON.stringify({ 
+      type: 'emitted', 
+      data: result.value 
+    }));
+  }
+}
+```
+
+### 6. Response Sent
+```javascript
+// Send updated model and emitted data
+ws.send(JSON.stringify({ 
+  type: 'model', 
+  data: model 
+}));
+```
+
+## Key Points
+
+1. **Unidirectional Flow**: Data flows in one direction through the system
+2. **Pure Scripts**: Scripts are pure functions (state in → commands out)
+3. **Side Effects Isolated**: Only adapters handle side effects
+4. **Command Batching**: Multiple `..emit` calls become multiple commands
+5. **Context Passing**: Adapters can pass context for command processing
+
+## Example: Game State Update
+
+```
+1. Game Client sends: { action: "collect_coin", player: "player1" }
+2. WebSocket Adapter receives
+3. Harness processes with game script
+4. Script: ..listen gets state, ..emit { score: 110, coins: 5 }
+5. Adapter sends: { type: "emitted", data: { score: 110, coins: 5 } }
+6. Game Client receives updated state
+```
+
+This flow ensures that:
+- Scripts remain pure and functional
+- Side effects are isolated to adapters
+- Data flows predictably through the system
+- The system is easy to reason about and test 
\ No newline at end of file