# aicyraa/prompt-flow architecture

> Architecture diagram of the GitHub repository aicyraa/prompt-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aicyraa/prompt-flow
- Repository: https://github.com/aicyraa/prompt-flow

## Overview

PromptFlow is a browser-based visual LLM workflow editor. Users create and connect Input, Prompt, Agent, Merge, and Output nodes, configure variables and models, then run the flow to stream results and inspect cost and per-step status. Saved flows, settings, history, reports, and editing tools support that workflow. The run store and execution engine form the central internal layer. Relationships below follow README workflow statements and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/store/runStore.ts`](https://github.com/aicyraa/prompt-flow/blob/main/src/store/runStore.ts) (Run Controller), [`src/store/graphStore.ts`](https://github.com/aicyraa/prompt-flow/blob/main/src/store/graphStore.ts) (Graph State), [`src/components/nodes/LLMNode.tsx`](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/LLMNode.tsx) (Agent Node), [`src/engine/executeFlow.ts`](https://github.com/aicyraa/prompt-flow/blob/main/src/engine/executeFlow.ts) (Flow Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_canvas["Canvas Editing"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_canvas_ui["Flow Canvas<br/>[Canvas.tsx]"]
  node_input_node["Input Node<br/>[InputNode.tsx]"]
  node_prompt_node["Prompt Node<br/>[PromptNode.tsx]"]
  node_agent_node["Agent Node<br/>[LLMNode.tsx]"]
  node_merge_node["Merge Node<br/>[MergeNode.tsx]"]
  node_output_node["Output Node<br/>[OutputNode.tsx]"]
end

subgraph group_execution["Run Execution"]
  node_run_store["Run Controller<br/>[runStore.ts]"]
  node_preflight["Run Preflight<br/>[preflight.ts]"]
  node_executor["Flow Executor<br/>[executeFlow.ts]"]
  node_cost_estimator["Cost Estimator<br/>[estimate.ts]"]
  node_retry["Retry Handler<br/>[retry.ts]"]
end

subgraph group_providers["Models and Providers"]
  node_provider_adapters["Provider Adapters"]
  node_openrouter_client["Streaming Client<br/>[client.ts]"]
  node_model_picker["Model Picker<br/>[ModelPicker.tsx]"]
end

subgraph group_state["Browser State"]
  node_graph_store[("Graph State<br/>[graphStore.ts]")]
  node_flow_store[("Saved Flows")]
  node_settings_store[("User Settings<br/>[settingsStore.ts]")]
  node_model_store[("Model Catalog<br/>[modelStore.ts]")]
  node_history_store[("Run History<br/>[historyStore.ts]")]
end

subgraph group_workflow_tools["Workflow Tools"]
  node_flow_files["Flow Import Export<br/>[useFlowFile.ts]"]
  node_variables["Flow Variables<br/>[variables.ts]"]
  node_reports["Run Reports<br/>[report.ts]"]
  node_command_palette["Command Palette<br/>[useCommands.ts]"]
end

node_user(("User"))
node_provider_services{{"LLM Providers"}}
node_browser_storage[("Browser Storage")]

node_user -->|"opens app"| node_app
node_app -->|"renders"| node_canvas_ui
node_user -->|"edits flow"| node_canvas_ui
node_canvas_ui -->|"updates graph"| node_graph_store
node_input_node -->|"provides text"| node_prompt_node
node_prompt_node -->|"supplies prompt"| node_agent_node
node_agent_node -->|"feeds branches"| node_merge_node
node_merge_node -->|"feeds text"| node_prompt_node
node_agent_node -->|"produces result"| node_output_node
node_agent_node -->|"reads node data"| node_graph_store
node_agent_node -->|"opens picker"| node_model_picker
node_app -->|"starts autosave"| node_flow_store
node_flow_store -->|"tracks canvas"| node_graph_store
node_graph_store -->|"persists state"| node_browser_storage
node_flow_store -->|"persists flows"| node_browser_storage
node_settings_store -->|"persists preferences"| node_browser_storage
node_user -->|"starts run"| node_run_store
node_run_store -->|"reads credentials"| node_settings_store
node_run_store -->|"reads catalog"| node_model_store
node_run_store -->|"reads flow"| node_graph_store
node_run_store -->|"checks flow"| node_preflight
node_run_store -->|"executes flow"| node_executor
node_run_store -->|"estimates cost"| node_cost_estimator
node_executor -->|"generates text"| node_provider_adapters
node_executor -->|"retries failures"| node_retry
node_provider_adapters -->|"uses client"| node_openrouter_client
node_openrouter_client -->|"sends requests"| node_provider_services
node_run_store -->|"records runs"| node_history_store
node_model_picker -->|"browses models"| node_model_store
node_model_store -->|"loads provider catalog"| node_provider_adapters
node_flow_files -->|"imports flow"| node_graph_store
node_flow_files -->|"downloads export"| node_browser_storage
node_executor -->|"resolves placeholders"| node_variables
node_user -->|"invokes actions"| node_command_palette
node_command_palette -->|"starts or stops run"| node_run_store
node_user -->|"downloads report"| node_reports
node_reports -->|"formats history run"| node_history_store

click node_app "https://github.com/aicyraa/prompt-flow/blob/main/src/App.tsx"
click node_canvas_ui "https://github.com/aicyraa/prompt-flow/blob/main/src/components/Canvas.tsx"
click node_input_node "https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/InputNode.tsx"
click node_prompt_node "https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/PromptNode.tsx"
click node_agent_node "https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/LLMNode.tsx"
click node_merge_node "https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/MergeNode.tsx"
click node_output_node "https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/OutputNode.tsx"
click node_graph_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/graphStore.ts"
click node_flow_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/flowLibraryStore.ts"
click node_settings_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/settingsStore.ts"
click node_model_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/modelStore.ts"
click node_history_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/historyStore.ts"
click node_run_store "https://github.com/aicyraa/prompt-flow/blob/main/src/store/runStore.ts"
click node_preflight "https://github.com/aicyraa/prompt-flow/blob/main/src/engine/preflight.ts"
click node_executor "https://github.com/aicyraa/prompt-flow/blob/main/src/engine/executeFlow.ts"
click node_cost_estimator "https://github.com/aicyraa/prompt-flow/blob/main/src/engine/estimate.ts"
click node_retry "https://github.com/aicyraa/prompt-flow/blob/main/src/engine/retry.ts"
click node_provider_adapters "https://github.com/aicyraa/prompt-flow/tree/main/src/lib/providers"
click node_openrouter_client "https://github.com/aicyraa/prompt-flow/blob/main/src/lib/openrouter/client.ts"
click node_model_picker "https://github.com/aicyraa/prompt-flow/blob/main/src/components/models/ModelPicker.tsx"
click node_flow_files "https://github.com/aicyraa/prompt-flow/blob/main/src/components/topbar/useFlowFile.ts"
click node_variables "https://github.com/aicyraa/prompt-flow/blob/main/src/lib/variables.ts"
click node_reports "https://github.com/aicyraa/prompt-flow/blob/main/src/lib/report.ts"
click node_command_palette "https://github.com/aicyraa/prompt-flow/blob/main/src/components/palette/useCommands.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_canvas_ui,node_input_node,node_prompt_node,node_agent_node,node_merge_node,node_output_node,node_user toneBlue
class node_run_store,node_preflight,node_executor,node_cost_estimator,node_retry,node_browser_storage toneAmber
class node_provider_adapters,node_openrouter_client,node_model_picker toneMint
class node_graph_store,node_flow_store,node_settings_store,node_model_store,node_history_store toneRose
class node_flow_files,node_variables,node_reports,node_command_palette,node_provider_services toneIndigo
```

## Components

### Canvas Editing

- [Application Shell](https://github.com/aicyraa/prompt-flow/blob/main/src/App.tsx): `src/App.tsx`
- [Flow Canvas](https://github.com/aicyraa/prompt-flow/blob/main/src/components/Canvas.tsx): `src/components/Canvas.tsx`
- [Input Node](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/InputNode.tsx): `src/components/nodes/InputNode.tsx`
- [Prompt Node](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/PromptNode.tsx): `src/components/nodes/PromptNode.tsx`
- [Agent Node](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/LLMNode.tsx): `src/components/nodes/LLMNode.tsx`
- [Merge Node](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/MergeNode.tsx): `src/components/nodes/MergeNode.tsx`
- [Output Node](https://github.com/aicyraa/prompt-flow/blob/main/src/components/nodes/OutputNode.tsx): `src/components/nodes/OutputNode.tsx`

### Run Execution

- [Run Controller](https://github.com/aicyraa/prompt-flow/blob/main/src/store/runStore.ts): `src/store/runStore.ts`
- [Run Preflight](https://github.com/aicyraa/prompt-flow/blob/main/src/engine/preflight.ts): `src/engine/preflight.ts`
- [Flow Executor](https://github.com/aicyraa/prompt-flow/blob/main/src/engine/executeFlow.ts): `src/engine/executeFlow.ts`
- [Cost Estimator](https://github.com/aicyraa/prompt-flow/blob/main/src/engine/estimate.ts): `src/engine/estimate.ts`
- [Retry Handler](https://github.com/aicyraa/prompt-flow/blob/main/src/engine/retry.ts): `src/engine/retry.ts`

### Models and Providers

- [Provider Adapters](https://github.com/aicyraa/prompt-flow/tree/main/src/lib/providers): `src/lib/providers`
- [Streaming Client](https://github.com/aicyraa/prompt-flow/blob/main/src/lib/openrouter/client.ts): `src/lib/openrouter/client.ts`
- [Model Picker](https://github.com/aicyraa/prompt-flow/blob/main/src/components/models/ModelPicker.tsx): `src/components/models/ModelPicker.tsx`

### Browser State

- [Graph State](https://github.com/aicyraa/prompt-flow/blob/main/src/store/graphStore.ts): `src/store/graphStore.ts`
- [Saved Flows](https://github.com/aicyraa/prompt-flow/blob/main/src/store/flowLibraryStore.ts): `src/store/flowLibraryStore.ts`
- [User Settings](https://github.com/aicyraa/prompt-flow/blob/main/src/store/settingsStore.ts): `src/store/settingsStore.ts`
- [Model Catalog](https://github.com/aicyraa/prompt-flow/blob/main/src/store/modelStore.ts): `src/store/modelStore.ts`
- [Run History](https://github.com/aicyraa/prompt-flow/blob/main/src/store/historyStore.ts): `src/store/historyStore.ts`

### Workflow Tools

- [Flow Import Export](https://github.com/aicyraa/prompt-flow/blob/main/src/components/topbar/useFlowFile.ts): `src/components/topbar/useFlowFile.ts`
- [Flow Variables](https://github.com/aicyraa/prompt-flow/blob/main/src/lib/variables.ts): `src/lib/variables.ts`
- [Run Reports](https://github.com/aicyraa/prompt-flow/blob/main/src/lib/report.ts): `src/lib/report.ts`
- [Command Palette](https://github.com/aicyraa/prompt-flow/blob/main/src/components/palette/useCommands.ts): `src/components/palette/useCommands.ts`

### Other components

- **User**
- **LLM Providers**
- **Browser Storage**

## Connections

- User → Application Shell: opens app (evidence: `src/App.tsx`)
- Application Shell → Flow Canvas: renders (evidence: `src/App.tsx`)
- User → Flow Canvas: edits flow (evidence: `README.md`)
- Flow Canvas → Graph State: updates graph
- Input Node → Prompt Node: provides text (evidence: `README.md`)
- Prompt Node → Agent Node: supplies prompt (evidence: `README.md`)
- Agent Node → Merge Node: feeds branches (evidence: `README.md`)
- Merge Node → Prompt Node: feeds text (evidence: `README.md`)
- Agent Node → Output Node: produces result (evidence: `README.md`)
- Agent Node → Graph State: reads node data (evidence: `src/components/nodes/LLMNode.tsx`)
- Agent Node → Model Picker: opens picker (evidence: `src/components/nodes/LLMNode.tsx`)
- Application Shell → Saved Flows: starts autosave (evidence: `src/App.tsx`)
- Saved Flows → Graph State: tracks canvas (evidence: `src/store/flowLibraryStore.ts`)
- Graph State → Browser Storage: persists state (evidence: `src/store/graphStore.ts`)
- Saved Flows → Browser Storage: persists flows (evidence: `src/store/flowLibraryStore.ts`)
- User Settings → Browser Storage: persists preferences (evidence: `README.md`)
- User → Run Controller: starts run (evidence: `README.md`)
- Run Controller → User Settings: reads credentials (evidence: `src/store/runStore.ts`)
- Run Controller → Model Catalog: reads catalog (evidence: `src/store/runStore.ts`)
- Run Controller → Graph State: reads flow (evidence: `src/store/runStore.ts`)
- Run Controller → Run Preflight: checks flow (evidence: `src/store/runStore.ts`)
- Run Controller → Flow Executor: executes flow (evidence: `src/store/runStore.ts`)
- Run Controller → Cost Estimator: estimates cost (evidence: `src/store/runStore.ts`)
- Flow Executor → Provider Adapters: generates text (evidence: `src/engine/executeFlow.ts`)
- Flow Executor → Retry Handler: retries failures (evidence: `src/engine/executeFlow.ts`)
- Provider Adapters → Streaming Client: uses client (evidence: `src/lib/providers/client.ts`)
- Streaming Client → LLM Providers: sends requests (evidence: `src/lib/openrouter/client.ts`)
- Run Controller → Run History: records runs (evidence: `src/store/runStore.ts`)
- Model Picker → Model Catalog: browses models
- Model Catalog → Provider Adapters: loads provider catalog (evidence: `src/store/modelStore.ts`)
- Flow Import Export → Graph State: imports flow (evidence: `src/components/topbar/useFlowFile.ts`)
- Flow Import Export → Browser Storage: downloads export (evidence: `src/components/topbar/useFlowFile.ts`)
- Flow Executor → Flow Variables: resolves placeholders (evidence: `src/engine/executeFlow.ts`)
- User → Command Palette: invokes actions (evidence: `README.md`)
- Command Palette → Run Controller: starts or stops run (evidence: `src/components/palette/useCommands.ts`)
- User → Run Reports: downloads report (evidence: `README.md`)
- Run Reports → Run History: formats history run (evidence: `src/lib/report.ts`)