# gabrieltempass/streamlit-navigation-bar architecture

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

- Interactive diagram: https://gitdiagram.com/gabrieltempass/streamlit-navigation-bar
- Repository: https://github.com/gabrieltempass/streamlit-navigation-bar

## Overview

##### Project Type and Purpose
- This is a full-stack component library for Streamlit: a Python package (“streamlit-navigation-bar”) that bundles a Vue/Vite front-end widget and exposes it via Streamlit’s component API.
- Purpose: Provide a customizable navigation bar widget in Streamlit apps, with examples demonstrating multipage setups.

##### High-Level Architecture
- User’s Browser: Renders the Streamlit UI including the navigation bar component (Vue app).
- Streamlit Server/Runtime: Runs user app code (the examples), hosts the component, and manages the WebSocket connection.
- Python Component Backend:
- streamlit_navigation_bar/__init__.py, __main__.py, match_navbar.py, errors.py – define the Streamlit component function `st_navbar()` and logic to match pages.
- templates/ and frontend assets: CSS templates and built JS/HTML from the Vue/Vite project.
- Front-End Widget (Vue/Vite):
- `frontend/src` containing App.vue, StNavbar.vue, Streamlit connection helpers.
- package.json, vite.config.ts orchestrate build, generating static assets.
- Examples Suite: Python scripts under examples/* show how to import and use `st_navbar()` in different Streamlit multipage structures.
- External Dependencies:
- Streamlit itself (1.33+) with component API.
- CSS `:has` pseudo‐class support.
- Optional external URLs (docs, community links).

a. Components
- User Browser (Client)
- Streamlit Server
- Python Package (streamlit_navigation_bar)
- Vue Front-End Assets
- Example App Code
- External Services (e.g., documentation links, PyPI)
b. Interactions & Data Flows
1. User loads example Streamlit app in browser.
2. Browser establishes WebSocket to Streamlit Server.
3. Example App calls `st_navbar()` → Streamlit component API loads the Vue widget.
4. Vue widget (StNavbar.vue) renders nav items; user clicks.
5. Vue captures click, sends event back via Streamlit’s component protocol.
6. Python backend (`match_navbar.py`) receives selection, returns updated page name.
7. Example App uses returned value to render appropriate Streamlit page.
c. Architectural Patterns
- Component-based UI (Vue) within a Python backend.
- Single Page App approach for the navigation bar.
- Streamlit’s Reactive model: front-end events trigger Python callbacks.
d. Key Technologies
- Python 3.8+, Streamlit ≥1.33 (component API)
- Vue.js + TypeScript + Vite (frontend build)
- CSS templates using `:has` pseudo-class
- Packaging via setup.py, wheel distribution

##### Detailed Elements to Capture
- `streamlit_navigation_bar/frontend/src` → Vue components (App.vue, StNavbar.vue)
- Build config files (package.json, vite.config.ts)
- Python entrypoints (`__main__.py`, `__init__.py`, `match_navbar.py`)
- Example folder hierarchy demonstrating multipage patterns
- CSS templates folder for style overrides

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Browser["User Browser"]:::external

    %% Streamlit Server
    Server["Streamlit Server / Runtime"]:::python

    %% Python Component Backend
    subgraph "Python Component Backend"
        pkg["streamlit_navigation_bar/"]:::python
        init["__init__.py"]:::python
        main["__main__.py"]:::python
        match["match_navbar.py"]:::python
        err["errors.py"]:::python
        exmod["example.py"]:::python
        subgraph "templates/"
            tdir["templates/"]:::python
            base["base.css"]:::python
            opt["options.css"]:::python
        end
    end

    %% Front-End Widget
    subgraph "Vue Front-End (streamlit_navigation_bar/frontend/)"
        fe_root["frontend/"]:::js
        pkgjson["package.json"]:::js
        vitecfg["vite.config.ts"]:::js
        html["index.html"]:::js
        subgraph "src/"
            appvue["App.vue"]:::js
            navvue["StNavbar.vue"]:::js
            maints["main.ts"]:::js
            subgraph "streamlit/"
                svue["StreamlitVue.ts"]:::js
                wconn["WithStreamlitConnection.vue"]:::js
                idx["index.ts"]:::js
            end
        end
        subgraph "tsconfig/"
            tscapp["tsconfig.app.json"]:::js
            tsccfg["tsconfig.json"]:::js
            tscnode["tsconfig.node.json"]:::js
        end
    end

    %% Packaging
    setup["setup.py"]:::python
    manifest["MANIFEST.in"]:::python
    requirements["requirements.txt"]:::python

    %% Examples Suite
    subgraph "Examples"
        subgraph "mpa_button/"
            eb_app["app.py"]:::python
            eb_pages["pages/"]:::python
        end
        subgraph "mpa_recommended/"
            er_app["app.py"]:::python
            er_pages["pages/"]:::python
        end
        subgraph "mpa_streamlit/"
            es_home["home.py"]:::python
            es_pages["pages/"]:::python
        end
        overview["overview/streamlit_app.py"]:::python
        st1["st_navbar_1/streamlit_app.py"]:::python
        st2["st_navbar_2/streamlit_app.py"]:::python
        subgraph "st_navbar_3/"
            st3_app["streamlit_app.py"]:::python
            st3_pages["pages/"]:::python
        end
    end

    %% External Services
    ext["External Docs / PyPI"]:::external

    %% Flows
    Browser -->|"WebSocket\n(Streamlit Component API)"| Server
    Server -->|"Serves Vue widget\nstatic assets"| Browser
    Server -->|"calls st_navbar()"| init
    init --> match
    match --> init
    init --> err
    init --> exmod
    pkg --> init
    pkg --> main
    pkg --> match
    pkg --> err
    pkg --> exmod
    pkg --> tdir
    fe_root --> pkgjson
    fe_root --> vitecfg
    fe_root --> html
    fe_root --> appvue
    fe_root --> navvue
    fe_root --> maints
    fe_root --> svue
    fe_root --> wconn
    fe_root --> idx
    pkg --> fe_root
    vitecfg -->|"Build"| fe_root
    fe_root -->|"Generates static\nassets"| pkg
    setup --> pkg
    manifest --> pkg
    requirements --> pkg
    pkg --> ext
    %% Example usage flow
    overview -->|imports| init
    eb_app -->|imports| init
    er_app -->|imports| init
    es_home -->|imports| init
    st1 -->|imports| init
    st2 -->|imports| init
    st3_app -->|imports| init

    Browser -->|click nav item| navvue
    navvue -->|event| svue
    svue -->|message| init
    init -->|response| svue
    svue -->|update UI| navvue

    %% Click Events
    click pkg "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/streamlit_navigation_bar/"
    click init "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/__init__.py"
    click main "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/__main__.py"
    click match "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/match_navbar.py"
    click err "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/errors.py"
    click exmod "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/example.py"
    click tdir "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/streamlit_navigation_bar/templates/"
    click base "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/templates/base.css"
    click opt "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/templates/options.css"
    click fe_root "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/streamlit_navigation_bar/frontend/"
    click pkgjson "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/package.json"
    click vitecfg "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/vite.config.ts"
    click html "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/index.html"
    click appvue "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/App.vue"
    click navvue "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/StNavbar.vue"
    click maints "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/main.ts"
    click svue "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/streamlit/StreamlitVue.ts"
    click wconn "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/streamlit/WithStreamlitConnection.vue"
    click idx "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/src/streamlit/index.ts"
    click tscapp "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/tsconfig.app.json"
    click tsccfg "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/tsconfig.json"
    click tscnode "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/streamlit_navigation_bar/frontend/tsconfig.node.json"
    click setup "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/setup.py"
    click manifest "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/MANIFEST.in"
    click requirements "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/requirements.txt"
    click eb_app "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/mpa_button/app.py"
    click eb_pages "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/examples/mpa_button/pages/"
    click er_app "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/mpa_recommended/app.py"
    click er_pages "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/examples/mpa_recommended/pages/"
    click es_home "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/mpa_streamlit/home.py"
    click es_pages "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/examples/mpa_streamlit/pages/"
    click overview "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/overview/streamlit_app.py"
    click st1 "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/st_navbar_1/streamlit_app.py"
    click st2 "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/st_navbar_2/streamlit_app.py"
    click st3_app "https://github.com/gabrieltempass/streamlit-navigation-bar/blob/main/examples/st_navbar_3/streamlit_app.py"
    click st3_pages "https://github.com/gabrieltempass/streamlit-navigation-bar/tree/main/examples/st_navbar_3/pages/"

    %% Styles
    classDef python fill:#AED6F1,stroke:#1F618D,color:#1B4F72
    classDef js fill:#ABEBC6,stroke:#196F3D,color:#145A32
    classDef external fill:#D5DBDB,stroke:#7F8C8D,color:#424949
```
