diff --git a/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md b/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md
new file mode 100644
index 0000000..9bae1fc
--- /dev/null
+++ b/state_machine_exporter/flow_renderer_plan/html_generator_architecture.md
@@ -0,0 +1,101 @@
+# Interactive HTML Generator: Architecture & Flow Definition Format
+
+Following the success of the interactive SVG PoC, this document outlines the proposed architecture for adding an **HTML Generator** to the State Machine Exporter, allowing users to define and visualize specific business flows dynamically.
+
+## 1. The Flow Definition Format (JSON & JSON Schema)
+
+To make the interactive HTML generator useful and intuitive, users need a way to define their business flows externally. Rather than reinventing the wheel, we looked at industry standards for defining graph paths, workflows, and execution traces:
+* **Workflow Definitions:** Tools like *Amazon States Language (ASL)*, *SCXML*, and *XState* are highly structured but define the *entire* machine's logic. They are too heavy for simply defining a "path" through an existing machine.
+* **Trace Formats:** *OpenTelemetry (OTel)* uses "Spans" to represent individual steps forming a "Trace". This is closer to what we want (a history of states).
+* **Graph Formats:** The *JSON Graph Format (JGF)* standardizes graph nodes and edges representation but is geared towards raw data modeling rather than human-readable business flows.
+
+**Conclusion on Format:** We will use a lightweight custom JSON format inspired by execution traces. It is designed to be highly readable for humans defining business flows, relying simply on ordered arrays of State names.
+
+### JSON Schema for IDE Autocomplete
+To make the format truly intuitive and prevent typos, we will publish a **JSON Schema** (`flow-schema.json`).
+By referencing this schema, developers writing `flows.json` in IDEs like VS Code or IntelliJ will get **instant autocomplete, hover tooltips, and real-time validation** for fields like `id`, `title`, and `color`.
+* *Future Enhancement:* The Java exporter could dynamically generate a project-specific JSON Schema on the fly that hardcodes the allowed `enum` values for the `path` array (e.g., restricted exactly to `"SUBMITTED"`, `"PAID"`, etc.), providing perfect autocomplete for state names!
+
+### Proposed Schema (`flows.json`)
+
+```json
+{
+ "$schema": "./flow-schema.json",
+ "stateMachine": "click.kamil.examples.statemachine.simple.SimpleEnumStateMachineConfiguration",
+ "flows": [
+ {
+ "id": "flow-happy-path",
+ "title": "Happy Path (Success)",
+ "description": "The standard flow for a successful order: Submitted -> Paid -> Fulfilled.",
+ "color": "#32CD32",
+ "path": [
+ ".start.",
+ "SUBMITTED",
+ "PAID",
+ "FULFILLED",
+ ".end."
+ ]
+ },
+ {
+ "id": "flow-cancel-post-pay",
+ "title": "Cancel Post-Payment",
+ "description": "Order is canceled after payment.",
+ "color": "#FF6347",
+ "path": [
+ ".start.",
+ "SUBMITTED",
+ "PAID",
+ "CANCELED",
+ ".end."
+ ]
+ }
+ ]
+}
+```
+
+### Format Details:
+* **`$schema`**: Points to the JSON schema for IDE tooling.
+* **`stateMachine`**: Links these flows to a specific state machine configuration in the codebase.
+* **`id`**: A unique identifier for the flow (used for DOM elements).
+* **`title` & `description`**: Rendered in the HTML sidebar for the user.
+* **`color` (Optional)**: Allows overriding the default highlight color (e.g., green for success, red for errors).
+* **`path`**: An ordered array of **State Names** (acting like an OpenTelemetry trace).
+ * *Note on Edges:* The user only needs to define the *states* they pass through. The generator will automatically calculate the edges (transitions) between these states to highlight the lines. Special tokens like `.start.` and `.end.` map to the initial and terminal pseudo-states.
+
+## 2. Robust Error Handling & Input Validation
+
+Before generating the HTML, the exporter **must validate** that the provided `flows.json` is logically sound against the actual codebase AST. If a user defines a flow that isn't physically possible in the state machine, the tool must fail fast with highly descriptive errors.
+
+### Validation Rules & Error Handling Strategy:
+1. **Schema Validation (Syntax):**
+ * *Check:* Is the JSON structurally correct (required fields present, correct types)?
+ * *Error:* "Invalid format in flows.json: 'title' is required for flow 'flow-cancel-post-pay'."
+2. **State Existence (Dangling Pointers):**
+ * *Check:* Every state listed in the `path` array must exist in the parsed `StateMachineModel`.
+ * *Error:* "Validation Error in 'Happy Path': State 'FULLFILLED' does not exist in StateMachine 'SimpleEnum'. Did you mean 'FULFILLED'?" (implementing a Levenshtein distance check for typos would be excellent here).
+3. **Transition Validity (Impossible Paths):**
+ * *Check:* For every adjacent pair in the `path` array (e.g., `["SUBMITTED", "PAID"]`), the validator must check the `StateMachineModel.getTransitions()` to ensure a valid transition exists where `source == "SUBMITTED"` and `target == "PAID"`.
+ * *Error:* "Validation Error in 'Happy Path': No transition exists from 'PAID' to 'SUBMITTED'. Please check your state machine configuration."
+4. **Ambiguous Transitions (Multiple Edges):**
+ * *Check:* If multiple transitions exist between the same two states (e.g., two different events trigger a move from A -> B).
+ * *Handling:* By default, highlight *all* edges between A and B to represent the general path.
+ * *Future Enhancement:* Expand the JSON format to allow specifying the exact `event` name in the path array (e.g., `["SUBMITTED", {"state": "PAID", "event": "PAY_CREDIT_CARD"}]`) to disambiguate.
+
+## 3. HTML Generation Strategy
+
+The HTML Exporter will be a new class implementing the `StateMachineExporter` interface (or a specialized decorator around the `PlantUml` exporter).
+
+### Steps for Generation:
+1. **Generate PlantUML SVG:** First, use the existing PlantUML engine to generate the raw SVG string in memory (using the modern CSS `
+
+
+
+
+
+
+
+
+
+
+
+