# dkapur17/streamlit-flow architecture

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

- Interactive diagram: https://gitdiagram.com/dkapur17/streamlit-flow
- Repository: https://github.com/dkapur17/streamlit-flow

## Overview

##### Project type and purpose
- Streamlit Flow is a hybrid full-stack component library: a Python package that wraps a React/React Flow front-end as a Streamlit custom component.

##### File structure
- Top-level:
- setup.py, MANIFEST.in, LICENSE, build_and_upload.sh, post_build_cleanup.sh → packaging and release scripts
- example.py → a sample Streamlit app demonstrating usage
- assets/ → demo videos and images
- Package root “streamlit_flow/”:
- __init__.py → component entry point, exports streamlit_flow()
- elements.py → Python classes modeling nodes & edges
- state.py → StreamlitFlowState class (state management)
- layouts.py → Python layout base classes
- frontend/ → React application for the UI
– package.json, .env → React build configuration
– public/index.html → host HTML
– src/StreamlitFlowComponent.jsx, StreamlitFlowApp.jsx, index.jsx → React component glue for Streamlit
– components/, layouts/ (ElkLayout.js), style.css → sub-components & styling

##### README for additional insights
- Description of the component’s features: node/edge creation, context menus, multiple layouts, markdown support, bidirectional state sync
- Usage patterns: how Python code constructs a StreamlitFlowState and passes it to streamlit_flow()
- Build & run instructions showing two processes: npm start for the front-end, streamlit run for the example

- Streamlit App (example.py or any user script)
- Streamlit Server / Python runtime (hosts the component)
- streamlit_flow Python module (elements.py, state.py, layouts.py)
- Streamlit Components API (RPC channel between Python and JS)
- React/React Flow front-end (frontend/src…)
- External dependencies: npm/Node.js, pip packages
b. Relationships and data flows:
1. User writes a Python script and runs `streamlit run example.py`.
2. Streamlit Server imports streamlit_flow and invokes the custom component function.
3. The Python side serializes the initial state (nodes, edges) and sends it via the Streamlit Components API to the React front-end.
5. On each interaction, the front-end posts updated state back through the Components API.
6. Python side (StreamlitFlowState) receives updates, stores them in st.session_state, and may trigger a rerun.
7. If Python code mutates the state programmatically (e.g., calls a layout algorithm in layouts.py), it sends the new state back to the front-end on the next render.
c. Architectural patterns and principles:
- Clear separation of concerns: Python backend vs. React UI
- Bidirectional state synchronization via a component API bridge
- Pluggable layout strategy (Strategy pattern) implemented in both Python and JS
- Component packaging: Python wheel containing prebuilt React assets
d. Key technologies and libraries:
- Python 3.x, Streamlit, pip, setuptools
- React, React Flow, JSX, webpack (via create-react-app)
- npm, Node.js for front-end build
- Streamlit Components API for RPC between Python and JavaScript

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Tools and Scripts
    subgraph "External & Packaging" 
        direction TB
        NPM["npm/Node.js"]:::external
        PIP["pip/setuptools"]:::external
        BuildScripts["Packaging & Release Scripts"]:::external
        exampleApp["Streamlit App (example.py)"]:::backend
    end

    %% Python Backend
    subgraph "Python Backend (Streamlit & Module)" 
        direction TB
        StreamlitServer["Streamlit Server / Python Runtime"]:::backend
        PythonModule["streamlit_flow Python Module"]:::backend
        Elements["elements.py (Models)"]:::backend
        State["state.py (StreamlitFlowState)"]:::backend
        LayoutsPy["layouts.py (Layout Strategy)"]:::backend
    end

    %% Component Bridge
    StreamlitAPI["Streamlit Components API"]:::external

    %% React Frontend
    subgraph "React Frontend" 
        direction TB
        FEConfig["package.json, .env"]:::frontend
        HTMLHost["public/index.html"]:::frontend
        EntryIndex["index.jsx"]:::frontend
        ComponentGlue["StreamlitFlowComponent.jsx"]:::frontend
        AppRoot["StreamlitFlowApp.jsx"]:::frontend
        subgraph "Components"
            direction TB
            EdgeMenu["EdgeContextMenu.jsx"]:::frontend
            NodeMenu["NodeContextMenu.jsx"]:::frontend
            PaneMenu["PaneContextMenu.jsx"]:::frontend
            MarkdownNode["MarkdownNode.jsx"]:::frontend
        end
        subgraph "Layouts"
            direction TB
            ElkLayout["ElkLayout.js"]:::frontend
        end
        Style["style.css"]:::frontend
    end

    %% Assets
    subgraph "Demo Assets" 
        direction TB
        AssetsDir["assets/"]:::assets
        CanvasVid["CanvasControl.mp4"]:::assets
        ElementVid["ElementToStreamlit.mp4"]:::assets
        FastBuildVid["FastBuild.mp4"]:::assets
        FastLayoutVid["FastLayout.mp4"]:::assets
    end

    %% Flows
    exampleApp -->|"runs"| StreamlitServer
    StreamlitServer -->|"imports streamlit_flow() call"| PythonModule
    PythonModule -->|uses| Elements
    PythonModule -->|uses| State
    PythonModule -->|uses| LayoutsPy
    PythonModule -->|"serialize state"| StreamlitAPI
    StreamlitAPI -->|"initial state"| EntryIndex
    EntryIndex -->|bootstraps| ComponentGlue
    ComponentGlue -->|renders| AppRoot
    AppRoot -->|includes| EdgeMenu
    AppRoot -->|includes| NodeMenu
    AppRoot -->|includes| PaneMenu
    AppRoot -->|includes| MarkdownNode
    AppRoot -->|uses| ElkLayout
    AppRoot -->|applies styles| Style
    ComponentGlue -->|hosts| HTMLHost
    FEConfig -->|build assets| ComponentGlue
    FEConfig -->|read env| ComponentGlue
    NPM -->|build frontend| FEConfig
    PIP -->|install package| PythonModule
    BuildScripts -->|package assets| PythonModule
    AssetsDir --> AssetsDir
    AssetsDir --> CanvasVid
    AssetsDir --> ElementVid
    AssetsDir --> FastBuildVid
    AssetsDir --> FastLayoutVid

    %% State Sync Loop
    AppRoot -->|"user interaction events"| StreamlitAPI
    StreamlitAPI -->|"updated state"| State
    State -->|stores in st.session_state| StreamlitServer
    StreamlitServer -->|"rerender pipeline"| StreamlitAPI
    StreamlitAPI -->|"updated props"| AppRoot

    %% Click Events
    click exampleApp "https://github.com/dkapur17/streamlit-flow/blob/master/example.py"
    click BuildScripts "https://github.com/dkapur17/streamlit-flow/blob/master/setup.py"
    click BuildScripts "https://github.com/dkapur17/streamlit-flow/blob/master/MANIFEST.in"
    click BuildScripts "https://github.com/dkapur17/streamlit-flow/blob/master/build_and_upload.sh"
    click BuildScripts "https://github.com/dkapur17/streamlit-flow/blob/master/post_build_cleanup.sh"
    click PythonModule "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/__init__.py"
    click Elements "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/elements.py"
    click State "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/state.py"
    click LayoutsPy "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/layouts.py"
    click FEConfig "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/package.json"
    click FEConfig "https://github.com/dkapur17/streamlit-flow/blob/master/.env"
    click HTMLHost "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/public/index.html"
    click EntryIndex "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/index.jsx"
    click ComponentGlue "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/StreamlitFlowComponent.jsx"
    click AppRoot "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/StreamlitFlowApp.jsx"
    click EdgeMenu "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/components/EdgeContextMenu.jsx"
    click NodeMenu "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/components/NodeContextMenu.jsx"
    click PaneMenu "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/components/PaneContextMenu.jsx"
    click MarkdownNode "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/components/MarkdownNode.jsx"
    click ElkLayout "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/layouts/ElkLayout.js"
    click Style "https://github.com/dkapur17/streamlit-flow/blob/master/streamlit_flow/frontend/src/style.css"
    click AssetsDir "https://github.com/dkapur17/streamlit-flow/tree/master/assets/"
    click CanvasVid "https://github.com/dkapur17/streamlit-flow/blob/master/assets/CanvasControl.mp4"
    click ElementVid "https://github.com/dkapur17/streamlit-flow/blob/master/assets/ElementToStreamlit.mp4"
    click FastBuildVid "https://github.com/dkapur17/streamlit-flow/blob/master/assets/FastBuild.mp4"
    click FastLayoutVid "https://github.com/dkapur17/streamlit-flow/blob/master/assets/FastLayout.mp4"

    %% Styles
    classDef backend fill:#cfe2f3,stroke:#6fa8dc
    classDef frontend fill:#d9ead3,stroke:#6aa84f
    classDef external fill:#f4cccc,stroke:#e06666
    classDef assets fill:#fce5cd,stroke:#e69138
```
