feat(docs): add Mermaid diagrams for state update, evaluation, and memory flows (#41)

Copilot · aepfli · web-flow · commit f2bb69d929ed · 2025-12-07T22:02:35.000+01:00
## Description Added visual documentation for the WASM module's internal operations. Three Mermaid diagrams illustrate how the evaluator processes flag configurations, evaluates flags, and manages memory across the host-WASM boundary. ### Diagrams Added - **State Update Flow** (sequence diagram after `update_state` API docs) - Validation modes (strict/permissive) with schema checking - JSON parsing and flag storage lifecycle - Error paths for UTF-8, validation, and parse failures - **Flag Evaluation Flow** (flowchart after `evaluate` API docs) - Complete evaluation paths: STATIC, DEFAULT, TARGETING_MATCH, DISABLED, ERROR, FLAG_NOT_FOUND - Context enrichment: `$flagd.flagKey`, `$flagd.timestamp`, `targetingKey` - JSON Logic targeting rule execution - **Memory Management Flow** (sequence diagram in Memory Model section) - alloc/dealloc lifecycle with pointer packing: `(ptr << 32) | len` - Host vs WASM memory ownership boundaries - Input, processing, and cleanup phases These complement existing text documentation by showing data flow and decision points visually. ## Related Issue Closes # ## Type of Change - [x] `docs`: Documentation only changes - [ ] `feat`: New feature (minor version bump) - [ ] `fix`: Bug fix (patch version bump) - [ ] `chore`: Maintenance tasks, dependency updates - [ ] `refactor`: Code refactoring without functional changes - [ ] `test`: Adding or updating tests - [ ] `ci`: CI/CD changes - [ ] `perf`: Performance improvements - [ ] `build`: Build system changes - [ ] `style`: Code style/formatting changes ## PR Title Format **IMPORTANT**: Since we use squash and merge, your PR title will become the commit message. Please ensure your PR title follows the [Conventional Commits](https://www.conventionalcommits.org/) format: ``` <type>(<optional-scope>): <description> ``` ### Examples: - `feat(operators): add new string comparison operator` - `fix(wasm): correct memory allocation bug` - `docs: update API examples in README` - `chore(deps): update rust dependencies` For breaking changes, use `!` after the type/scope or include `BREAKING CHANGE:` in the PR description: - `feat(api)!: redesign evaluation API` ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [ ] Manual testing performed - [ ] All tests pass (`cargo test`) - [ ] Code is formatted (`cargo fmt`) - [ ] Clippy checks pass (`cargo clippy -- -D warnings`) - [ ] WASM builds successfully (if applicable) **N/A** - Documentation-only changes ## Breaking Changes - [ ] This PR includes breaking changes - [ ] Documentation has been updated to reflect breaking changes - [ ] Migration guide included (if needed) ## Additional Notes Diagrams verified against source code: - `lib.rs::update_state_internal()` and `storage/mod.rs` → State Update Flow - `lib.rs::evaluate_internal()` and `evaluation.rs::evaluate_flag()` → Flag Evaluation Flow - `memory.rs` (wasm_alloc, wasm_dealloc, pack_ptr_len) → Memory Management Flow Total: 130 lines added, 3 diagrams, all using GitHub-compatible Mermaid syntax.  <details> <summary>Original prompt</summary> > ## Problem > > The README documentation currently lacks visual representations of the state update and evaluation flows, which makes it harder for developers to understand how the WASM module interacts with host applications and how the internal evaluation process works. > > ## Solution > > Add three Mermaid diagrams to the README.md to illustrate: > > 1. **State Update Flow** - Shows the sequence of operations when updating flag configuration state, including validation and storage > 2. **Flag Evaluation Flow** - Shows the complete evaluation process from flag retrieval through context enrichment to targeting rule evaluation > 3. **Memory Management Flow** - Shows the memory allocation/deallocation lifecycle for WASM calls > > ## Implementation Details > > ### 1. State Update Flow Diagram > > Add after the `update_state` API documentation (around line 306), showing: > - Host allocates memory and writes config JSON > - WASM parses JSON > - Schema validation (with strict/permissive mode handling) > - Storage of flag configuration > - Memory cleanup > > ### 2. Flag Evaluation Flow Diagram > > Add after the `evaluate` API documentation (around line 380), showing: > - Memory allocation for flag key and context > - Flag retrieval from storage > - Handling of DISABLED and STATIC flags > - Context enrichment (adding `$flagd.flagKey`, `$flagd.timestamp`, `targetingKey`) > - JSON Logic evaluation of targeting rules > - Variant resolution > - Memory cleanup > > ### 3. Memory Management Flow Diagram > > Add in the "Memory Model & Safety" section (around line 693), showing: > - Complete lifecycle from alloc to dealloc > - Pointer packing/unpacking > - Clear distinction between host and WASM responsibilities > > ## Acceptance Criteria > > - [ ] All three Mermaid diagrams are added to README.md > - [ ] Diagrams are placed in logical locations within the existing documentation structure > - [ ] Diagrams accurately represent the actual code flow > - [ ] Syntax is valid Mermaid that renders correctly on GitHub > - [ ] Existing documentation formatting is preserved > > ## Additional Context > > This enhancement will improve developer experience by providing visual documentation that complements the existing text-based API documentation. </details>  *This pull request was created as a result of the following prompt from Copilot chat.* > ## Problem > > The README documentation currently lacks visual representations of the state update and evaluation flows, which makes it harder for developers to understand how the WASM module interacts with host applications and how the internal evaluation process works. > > ## Solution > > Add three Mermaid diagrams to the README.md to illustrate: > > 1. **State Update Flow** - Shows the sequence of operations when updating flag configuration state, including validation and storage > 2. **Flag Evaluation Flow** - Shows the complete evaluation process from flag retrieval through context enrichment to targeting rule evaluation > 3. **Memory Management Flow** - Shows the memory allocation/deallocation lifecycle for WASM calls > > ## Implementation Details > > ### 1. State Update Flow Diagram > > Add after the `update_state` API documentation (around line 306), showing: > - Host allocates memory and writes config JSON > - WASM parses JSON > - Schema validation (with strict/permissive mode handling) > - Storage of flag configuration > - Memory cleanup > > ### 2. Flag Evaluation Flow Diagram > > Add after the `evaluate` API documentation (around line 380), showing: > - Memory allocation for flag key and context > - Flag retrieval from storage > - Handling of DISABLED and STATIC flags > - Context enrichment (adding `$flagd.flagKey`, `$flagd.timestamp`, `targetingKey`) > - JSON Logic evaluation of targeting rules > - Variant resolution > - Memory cleanup > > ### 3. Memory Management Flow Diagram > > Add in the "Memory Model & Safety" section (around line 693), showing: > - Complete lifecycle from alloc to dealloc > - Pointer packing/unpacking > - Clear distinction between host and WASM responsibilities > > ## Acceptance Criteria > > - [ ] All three Mermaid diagrams are added to README.md > - [ ] Diagrams are placed in logical locations within the existing documentation structure > - [ ] Diagrams accurately represent the actual code flow > - [ ] Syntax is valid Mermaid that renders correctly on GitHub > - [ ] Existing documentation formatting is preserved > > ## Additional Context > > This enhancement will improve developer experience by providing visual documentation that complements the existing text-based API documentation.  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aepfli <9987394+aepfli@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -304,6 +304,48 @@ The configuration should follow the [flagd flag definition schema](https://flagd
 }
 ```
 
+**State Update Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Host as Host Application
+    participant WASM as WASM Module
+    participant Storage as Flag Storage
+    
+    Host->>Host: Allocate memory using alloc()
+    Host->>Host: Write config JSON to memory
+    Host->>WASM: Call update_state(config_ptr, config_len)
+    
+    WASM->>WASM: Read JSON from memory
+    alt Invalid UTF-8
+        WASM-->>Host: Return error response
+    end
+    
+    WASM->>WASM: Validate against JSON Schema
+    
+    alt Strict Mode
+        alt Validation Failed
+            WASM-->>Host: Return validation error
+        end
+    else Permissive Mode
+        alt Validation Failed
+            WASM->>WASM: Log warning, continue
+        end
+    end
+    
+    WASM->>WASM: Parse JSON to FeatureFlag objects
+    alt Parse Error
+        WASM-->>Host: Return parse error
+    end
+    
+    WASM->>Storage: Store parsed flags (replace existing)
+    WASM->>WASM: Allocate memory for success response
+    WASM-->>Host: Return packed pointer (success)
+    
+    Host->>Host: Read response from memory
+    Host->>Host: Deallocate memory using dealloc()
+```
+
 ### evaluate
 
 Evaluates a feature flag from the previously stored configuration (set via `update_state`) against the provided context.
@@ -379,6 +421,51 @@ dealloc.apply(contextPtr, contextBytes.length);
 dealloc.apply(resultPtr, resultLen);
 ```
 
+**Flag Evaluation Flow:**
+
+```mermaid
+flowchart TD
+    Start([Host calls evaluate]) --> AllocMem[Host allocates memory for flag key and context]
+    AllocMem --> WriteData[Host writes data to WASM memory]
+    WriteData --> CallEval[Call evaluate with pointers]
+    
+    CallEval --> ReadMem[WASM reads flag key and context from memory]
+    ReadMem --> ParseCtx{Parse context JSON}
+    ParseCtx -->|Error| ReturnError[Return PARSE_ERROR]
+    
+    ParseCtx -->|Success| GetFlag{Retrieve flag from storage}
+    GetFlag -->|Not Found| ReturnNotFound[Return FLAG_NOT_FOUND]
+    GetFlag -->|Found| CheckState{Check flag state}
+    
+    CheckState -->|DISABLED| ReturnDisabled[Return default variant with DISABLED reason]
+    CheckState -->|ENABLED| CheckTargeting{Has targeting rules?}
+    
+    CheckTargeting -->|No| ReturnStatic[Return default variant with STATIC reason]
+    CheckTargeting -->|Yes| EnrichContext[Enrich context with:<br/>- $flagd.flagKey<br/>- $flagd.timestamp<br/>- targetingKey default]
+    
+    EnrichContext --> EvalRule[Evaluate targeting rule using JSON Logic]
+    EvalRule --> EvalResult{Evaluation result}
+    
+    EvalResult -->|Error| ReturnParseError[Return PARSE_ERROR]
+    EvalResult -->|Success| GetVariant{Variant exists?}
+    
+    GetVariant -->|Yes| ReturnMatch[Return variant value with TARGETING_MATCH]
+    GetVariant -->|No| ReturnDefault[Return default variant with DEFAULT reason]
+    
+    ReturnError --> PackResult[Pack result into memory]
+    ReturnNotFound --> PackResult
+    ReturnDisabled --> PackResult
+    ReturnStatic --> PackResult
+    ReturnParseError --> PackResult
+    ReturnMatch --> PackResult
+    ReturnDefault --> PackResult
+    
+    PackResult --> ReturnPacked[Return packed pointer to host]
+    ReturnPacked --> HostRead[Host reads result from memory]
+    HostRead --> HostDealloc[Host deallocates all memory]
+    HostDealloc --> End([Evaluation complete])
+```
+
 ### Context Enrichment
 
 The evaluator automatically enriches the evaluation context with standard `$flagd` properties according to the [flagd provider specification](https://flagd.dev/reference/specifications/providers/#in-process-resolver). These properties are available in targeting rules via JSON Logic's `var` operator.
@@ -704,6 +791,48 @@ The library uses a simple linear memory allocation model:
 - Freeing input memory after `evaluate_logic` returns
 - Freeing the result memory after reading it
 
+**Memory Management Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Host as Host Application
+    participant WASM as WASM Module
+    participant Heap as WASM Heap
+    
+    Note over Host,Heap: Input Phase
+    Host->>WASM: Call alloc(input_len)
+    WASM->>Heap: Allocate input_len bytes
+    Heap-->>WASM: Return pointer or null
+    WASM-->>Host: Return input_ptr
+    
+    Host->>WASM: Write input data to memory[input_ptr]
+    
+    Note over Host,Heap: Processing Phase
+    Host->>WASM: Call function(input_ptr, input_len, ...)
+    WASM->>WASM: Read data from memory[input_ptr]
+    WASM->>WASM: Process data
+    
+    WASM->>WASM: Call alloc(result_len) internally
+    WASM->>Heap: Allocate result_len bytes
+    Heap-->>WASM: Return result_ptr
+    WASM->>WASM: Write result to memory[result_ptr]
+    
+    WASM->>WASM: Pack pointer and length:<br/>packed = (result_ptr << 32) | result_len
+    WASM-->>Host: Return packed u64
+    
+    Note over Host,Heap: Cleanup Phase
+    Host->>Host: Unpack u64:<br/>result_ptr = packed >> 32<br/>result_len = packed & 0xFFFFFFFF
+    Host->>WASM: Read result from memory[result_ptr]
+    
+    Host->>WASM: Call dealloc(input_ptr, input_len)
+    WASM->>Heap: Free input memory
+    
+    Host->>WASM: Call dealloc(result_ptr, result_len)
+    WASM->>Heap: Free result memory
+    
+    Note over Host,Heap: Memory lifecycle complete
+```
+
 ### Pointer Packing
 
 Results are returned as a packed 64-bit integer:
