understanding-streamlit-architecture

name: understanding-streamlit-architecture description: Explains Streamlit's internal architecture including backend runtime, frontend rendering, and WebSocket communication. Use when debugging cross-layer issues, understanding how features work end-to-end, planning architectural changes, or onboarding to the codebase. Covers ForwardMsg/BackMsg protocol, script rerun model, element tree, widget state management, and more.

Understanding Streamlit architecture

Streamlit is a client-server application with bidirectional WebSocket communication using Protocol Buffers. Use this file as a quick mental model and navigation index; use references/backend.md, references/frontend.md, and references/communication.md for implementation details.

Concepts glossary

Core mental model

flowchart TB
    subgraph Backend["Backend (Python)"]
        Script[User Script]
        DG[DeltaGenerator]
        Runtime[Runtime/AppSession]
    end

    subgraph Protocol["WebSocket + Protobuf"]
        FM[ForwardMsg]
        BM[BackMsg]
    end

    subgraph Frontend["Frontend (React)"]
        App[App.tsx]
        Tree[AppRoot Tree]
        Renderer[ElementNodeRenderer]
        WSM[WidgetStateManager]
    end

    Script --> DG
    DG --> FM
    FM --> App
    App --> Tree
    Tree --> Renderer
    Renderer --> WSM
    WSM -->|User interaction| BM
    BM --> Runtime
    Runtime -->|Rerun| Script

Key insight: Script execution is rerun-driven: most widget interactions trigger reruns (full app or fragment-scoped). State persists via st.session_state and caching decorators.

Execution model

Streamlit's execution model differs from traditional web frameworks:

Rerun triggers:

1. Widget interaction: User clicks button, moves slider, etc.
2. Source code change: File watcher detects script modification
3. st.rerun(): Explicit programmatic rerun
4. Fragment timer: @st.fragment(run_every=...) periodic reruns

Execution order nuances:

• Scripts execute top-to-bottom on every rerun
• Callbacks first: on_change/on_click handlers run before the main script body
• Fragments typically isolate reruns: Widget interactions inside @st.fragment usually rerun only that fragment
• Control flow exceptions: st.stop(), st.rerun(), st.switch_page() raise exceptions to halt/redirect execution

Session isolation:

• Each browser tab = separate AppSession with its own SessionState
• Refreshing the page creates a new session (unless reconnecting within TTL)
• No shared state between sessions (use external storage for multi-user state)

What persists across reruns (within a session):

• st.session_state values
• Cached function results (@st.cache_data, @st.cache_resource)
• Uploaded files
• Fragment registrations

What resets on each rerun:

• Local variables in script
• Widget return values (re-read from SessionState)
• Element tree (rebuilt from scratch, then diffed)

Architecture layers

Backend (Python)

For backend deep dive: See references/backend.md

Frontend (TypeScript/React)

For frontend deep dive: See references/frontend.md

Communication (Protobuf)

Location: proto/streamlit/proto/

For protocol deep dive: See references/communication.md

Essential concepts (quick map)

• Script rerun model: Widget interaction -> BackMsg (ClientState) -> backend updates SessionState -> script rerun -> ForwardMsg deltas.
  • Deep dive: references/communication.md#widget-interaction-to-script-rerun
• Delta path system: Elements are addressed by delta paths (for example [0, 2, 3]) to support efficient tree updates.
  • Deep dive: references/communication.md#delta-ui-changes
• active_script_hash semantics: ForwardMsg.metadata.active_script_hash scopes node ownership across multipage and fragment reruns.
  • Deep dive: references/communication.md#forwardmsg-metadata-active_script_hash
• Element tree structure: Frontend AppRoot maintains main, sidebar, event, and bottom containers with BlockNode/ElementNode.
  • Deep dive: references/frontend.md#element-tree-frontendlibsrcrender-tree
• Fragments (@st.fragment): Fragment interactions usually trigger fragment-scoped reruns and update only affected regions.
  • Deep dive: references/backend.md

Key implementation patterns

• Backend mixin composition: DeltaGenerator composes st.* API via mixins.
  • Deep dive: references/backend.md#deltagenerator-libstreamlitdelta_generatorpy
• Frontend visitor pattern: Render-tree updates/staleness cleanup use visitors.
  • Deep dive: references/frontend.md#visitor-pattern
• Message deduplication: ForwardMsg.hash + ref_hash with frontend ForwardMsgCache reduces bandwidth.
  • Deep dive: references/communication.md#message-caching

Quick reference: adding features

1. Proto definition: proto/streamlit/proto/<Element>.proto
2. Register in Element.proto: Add to oneof type
3. Backend mixin: lib/streamlit/elements/<element>.py
4. Frontend component: frontend/lib/src/components/elements/<Element>/ or frontend/lib/src/components/widgets/<Element>/ (depending on element vs widget)
5. Register in ElementNodeRenderer: Add case to switch statement
6. Compile protos: make protobuf

See the implementing-new-features skill for a detailed implementation guide.

Maintaining this documentation

When making changes that impact any of the concepts documented here (Runtime, AppSession, DeltaGenerator, element tree, communication protocol, etc.), update the relevant sections in this skill's files (SKILL.md, references/backend.md, references/frontend.md, references/communication.md) to keep them accurate.