# jrieke/streamlit-image-select architecture

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

- Interactive diagram: https://gitdiagram.com/jrieke/streamlit-image-select
- Repository: https://github.com/jrieke/streamlit-image-select

## Overview

##### Project type and purpose
- This is not a standalone full‐stack web app but a Streamlit “custom component” library. It provides a Python API (`image_select`) that under the hood spins up a small React/TypeScript front end to render a gallery of images and capture the user’s selection. A demo Streamlit app shows how to integrate and test it.

##### File structure
- Top level:
- `pyproject.toml`, `README.md`, license, demo directory
- Python package `streamlit_image_select/`
- Inside `streamlit_image_select/`:
- `__init__.py` – entry point, sets `_RELEASE`
- `frontend/` – React app (package.json, src/, public/)
- Demo: a minimal Streamlit app (`demo/streamlit_app.py`) with its own requirements.txt
- Build & configuration files: `poetry`, `npm` scripts, `.env`, `.prettierrc`

##### README for additional insights
- The component follows the pattern of Streamlit’s [component template](): Python side defines the API, and the JS side runs in an isolated iframe on port 3001 (dev) or as a built bundle.
- Development workflow: start frontend dev server → run Streamlit with `_RELEASE = False` → see hot reload of both sides.

a. Main components
1. Streamlit “Demo App” (Python script)
2. Streamlit Server (Python runtime + Tornado web server)
3. `streamlit-image-select` Python package
4. Custom Component Bridge (the JSON‐RPC channel over HTTP/websocket between Python and JS)
5. React/TypeScript Frontend (served from local dev server or built bundle)
6. Browser (iframe host)
7. Optional External Services (PyPI for distribution)

b. Relationships and interactions
- The user opens the Demo App in their browser → Streamlit Server renders the page.
- When `image_select()` is called, Streamlit negotiates with the Custom Component Bridge to load the React frontend into an iframe.
- The frontend fetches image URLs, renders them, and listens for clicks.
- On selection, the frontend calls back via the component RPC into Python → Python returns the selected index or URL to the Streamlit app.
- For development, an `npm start` server on port 3001 serves the frontend; in production, a static bundle is used.

c. Architectural patterns and design principles
- Plugin‐style extension: clean separation of host app (Streamlit) and component code (frontend + Python wrapper).
- Client‐server split: Python (server) ↔ JavaScript (client) with a messaging bridge.
- Standard build pipeline: npm scripts for build/dev, Poetry for packaging.

d. Key technologies & libraries
- Python 3.x, Streamlit
- React + TypeScript, npm, webpack (under the hood)
- Poetry (dependency management)
- Streamlit component protocol (iframe + RPC)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Demo Layer
    subgraph "Demo Application" 
        direction TB
        DemoApp["Streamlit Demo App"]:::python
        DemoReq["Demo App Requirements"]:::infra
    end

    %% Python Package Layer
    subgraph "Python Package & Server" 
        direction TB
        PyPackage["streamlit-image-select Python API"]:::python
        StreamlitServer["Streamlit Server (Python)"]:::python
        PoetryConfig["Poetry Configuration"]:::infra
        PyPI["PyPI Distribution"]:::infra
    end

    %% JS Frontend Layer
    subgraph "JavaScript Frontend" 
        direction TB
        DevServer["npm start @3001 (Frontend Dev Server)"]:::js
        FrontendRoot["React/TypeScript Frontend (src/public)"]:::js
        EnvConfig[".env & .prettierrc"]:::js
        PackageJSON["package.json & package-lock.json"]:::js
        BuiltBundle["Built JS Bundle (static assets)"]:::js
    end

    Browser["User Browser (iframe host)"]:::external
    Bridge["Component Bridge (RPC channel)"]:::bridge

    %% Flow connections
    DemoApp -->|"imports image_select() API"| PyPackage
    DemoApp -->|"runs with"| StreamlitServer
    StreamlitServer -->|"renders UI"| Browser
    StreamlitServer -->|"invokes RPC"| Bridge
    Browser -->|"loads iframe from DevServer or BuiltBundle"| DevServer
    Browser -->|"loads iframe from DevServer or BuiltBundle"| BuiltBundle
    Browser -->|"user selects image"| FrontendRoot
    FrontendRoot -->|"RPC message"| Bridge
    Bridge -->|"RPC response"| StreamlitServer
    StreamlitServer -->|"returns selection"| DemoApp

    %% Build & Deploy Pipeline (dashed)
    PackageJSON -.->|"npm build"| BuiltBundle
    BuiltBundle -.->|"embed into Python package"| PyPackage
    PoetryConfig -.->|"poetry build & publish"| PyPI

    %% Click Events
    click DemoApp "https://github.com/jrieke/streamlit-image-select/blob/main/demo/streamlit_app.py"
    click DemoReq "https://github.com/jrieke/streamlit-image-select/blob/main/demo/requirements.txt"
    click PyPackage "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/__init__.py"
    click PoetryConfig "https://github.com/jrieke/streamlit-image-select/blob/main/pyproject.toml"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/tree/main/streamlit_image_select/frontend/"
    click EnvConfig "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/.env"
    click EnvConfig "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/.prettierrc"
    click PackageJSON "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/package.json"
    click PackageJSON "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/package-lock.json"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/public/index.html"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/public/styles.css"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/src/index.tsx"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/src/react-app-env.d.ts"
    click FrontendRoot "https://github.com/jrieke/streamlit-image-select/blob/main/streamlit_image_select/frontend/tsconfig.json"
    click README "https://github.com/jrieke/streamlit-image-select/blob/main/README.md"
    click LICENSE "https://github.com/jrieke/streamlit-image-select/tree/main/LICENSE"
    click GitIgnore "https://github.com/jrieke/streamlit-image-select/blob/main/.gitignore"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#339,stroke-width:1px;
    classDef js fill:#DFFFD0,stroke:#393,stroke-width:1px;
    classDef infra fill:#F0F0F0,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#FFE0E0,stroke:#933,stroke-width:1px;
    classDef bridge fill:#FFF4C1,stroke:#CC9,stroke-width:1px;
```
