# ai-yash/st-chat architecture

> Architecture diagram of the GitHub repository ai-yash/st-chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-yash/st-chat
- Repository: https://github.com/ai-yash/st-chat

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **Streamlit custom component** packaged as a Python library (`streamlit-chat`) that provides a **chat UI** (message bubbles, alignment, markdown/HTML/table rendering) for Streamlit apps. It’s not a full “system” with a backend/database; it’s a **reusable UI component** with:
- **Python API surface** (what the Streamlit developer imports: `from streamlit_chat import message`)
- A **frontend implementation** (TypeScript/React-style Streamlit component frontend under `streamlit_chat/frontend`)
- The **Streamlit component bridge/runtime** (Streamlit’s components mechanism that synchronizes Python ↔ iframe’d frontend via messages/props)

##### Python packaging / distribution
- `setup.py`, `MANIFEST.in`, `requirements*.txt`, `LICENSE`
- `streamlit_chat/__init__.py` (exposes the public API; likely defines `message()` and registers the component + points to frontend build assets)
- `test_component.py` (local testing harness for the component)

##### Frontend component (built + source)
- `streamlit_chat/frontend/src/*` (actual UI logic)
- `Chat.tsx`, `stChat.tsx` (main UI component(s))
- `message.tsx` (message bubble rendering)
- `avatar.tsx` (avatars)
- CSS: `stChat.css`, `index.css`
- `main.tsx` (frontend entry)
- `streamlit_chat/frontend/package.json`, `vite.config.ts`, `tsconfig*.json` (build toolchain)
- `streamlit_chat/frontend/build/*` (compiled static assets that get shipped with the Python package)

##### Docs / examples / CI
- `examples/chatbot.py` (consumer usage pattern; shows Streamlit app loop + session_state)
- `docs/*`, `mkdocs.yml`, `.github/workflows/*` (documentation site + CI publishing)

##### What the README implies architecturally
- The user calls `message("…", is_user=True, allow_html=True, is_table=...)` from a Streamlit script.
- The component renders chat messages, supports HTML-in-markdown when explicitly allowed, and can render a “table mode”.
- The component is **purely UI**; any “bot logic” is in the consuming app (e.g., `examples/chatbot.py`), not in this repo.

##### User Browser
- Contains Streamlit UI + the component iframe
##### Streamlit App (Python)
- The developer’s app code (e.g., `examples/chatbot.py`)
- Uses `st.session_state` and calls `streamlit_chat.message()`
##### streamlit_chat Python Package
- Public API: `message()`
- Component registration (Streamlit Components API)
- Serves/points to frontend build assets
##### streamlit_chat Frontend (TSX)
- Chat UI components: `stChat.tsx`, `message.tsx`, `avatar.tsx`
- Styling: `stChat.css`
##### Streamlit Component Bridge
- The bidirectional message/props channel between Python and frontend (Streamlit’s component protocol over websocket)

- *Streamlit App → streamlit_chat (Python)*: function call `message(text, is_user, allow_html, is_table, key, ...)`
- *streamlit_chat (Python) → Streamlit Component Bridge*: sends **props** (message text, flags, styling choices, keys)
- *Component Bridge → Frontend iframe*: delivers props to the TS frontend
- *Frontend → Browser DOM*: renders chat bubbles, markdown/table/html

**Important annotation to include:**
- The frontend runs in an **iframe** (standard Streamlit custom component model).
- `allow_html` is a **security toggle** (trusted content only).
- The chat “history” isn’t maintained by the component; it’s typically maintained in **`st.session_state`** in the consumer app.

This repo includes both TS source and compiled assets; for accuracy, show the pipeline.

- Developer workstation / CI
- Frontend build system: `vite` (from `vite.config.ts`, `package.json`)
- Output: `streamlit_chat/frontend/build/*`
- Python packaging: `setup.py` + `MANIFEST.in`
- Artifact: PyPI package `streamlit-chat`
- Consumer environment: `pip install streamlit-chat`

- `frontend/src` → (Vite build) → `frontend/build`
- `frontend/build` + `streamlit_chat/*.py` → (python sdist/wheel) → PyPI
- PyPI → pip install → user’s Streamlit app imports

- `main.tsx` → mounts root component
- `stChat.tsx` / `Chat.tsx` → container layout
- `message.tsx` → bubble renderer (user vs bot)
- `avatar.tsx` → avatar rendering
- CSS modules/files → styling

- **Wrapper + embedded frontend**: Python façade (`message()`) wraps a web UI delivered as static assets.
- **Unidirectional props flow** (likely): Python computes state (session_state), frontend renders.
- **Consumer-owned state**: Chat transcript is managed by the Streamlit app, not the library.
- **Separation of concerns**:
- Python: API ergonomics + Streamlit component registration
- Frontend: presentation + rendering modes (markdown/html/table)

##### Labels (be explicit)
- “`streamlit_chat/__init__.py` (Python API: message())”
- “Frontend: `frontend/src/stChat.tsx`, `message.tsx`”
- “Built assets: `frontend/build/*`”
- “props: {text, is_user, allow_html, is_table, key}”
- “renders DOM/CSS”
- “component protocol (Streamlit)”

- Browser (Streamlit UI + iframe)
- Streamlit server (Python app)
- streamlit_chat Python wrapper
- Component bridge
- streamlit_chat frontend renderer
- Data flow: message props → rendered chat bubbles

- TS source → vite build → static assets
- static assets + python package → PyPI → pip install → used by Streamlit apps

That pair will be the most accurate representation of this repo’s actual architecture and how it is used in practice.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% RUNTIME ARCHITECTURE
%% =======================
subgraph "Runtime: Streamlit Custom Component Integration"
direction TB

subgraph "Client (Browser)"
direction TB
U["End User"]:::external
B["Browser: Streamlit UI"]:::runtime
IF["Component iframe: streamlit_chat frontend"]:::runtime
DOM["Rendered DOM/CSS\n(chat bubbles, markdown/table/html)"]:::runtime
U -->|"interacts"| B
B -->|"embeds"| IF
IF -->|"renders"| DOM
end

subgraph "Streamlit Runtime"
direction TB
STS["Streamlit Server (Python)\nwebsocket + component protocol"]:::runtime
BR["Streamlit Component Bridge\n(props ⇄ value/events)"]:::runtime
STS -->|"component-protocol"| BR
end

subgraph "Consumer App (external to library)"
direction TB
APP["Streamlit App Script\n(e.g., chatbot)"]:::external
STATE["st.session_state\n(chat history owned by app)"]:::external
APP -->|"reads/writes"| STATE
end

subgraph "streamlit-chat Python Package"
direction TB
PYAPI["Python API\nmessage(text, is_user, allow_html, is_table, key, ...)"]:::pkg
PYREG["Component registration\npoints to built frontend assets"]:::pkg
PYAPI -->|"registers/uses"| PYREG
end

subgraph "streamlit-chat Frontend (TSX + CSS)"
direction TB
FEENTRY["main.tsx\nmount root"]:::frontend
FEST["stChat.tsx\nprimary component"]:::frontend
FECHAT["Chat.tsx\nlayout/container"]:::frontend
FEMSG["message.tsx\nbubble renderer"]:::frontend
FEAV["avatar.tsx\navatar renderer"]:::frontend
CSSCHAT["stChat.css\nchat styling"]:::frontend
CSSBASE["index.css\nbase styling"]:::frontend

FEENTRY -->|"mounts"| FEST
FEST -->|"composes"| FECHAT
FECHAT -->|"renders"| FEMSG
FEMSG -->|"uses"| FEAV
FEST -->|"styles"| CSSCHAT
FEENTRY -->|"styles"| CSSBASE
end

%% Runtime data flows
APP -->|"calls message()"| PYAPI
PYREG -->|"declares component"| BR
PYAPI -->|"props:{text,is_user,allow_html,is_table,key}"| BR
BR -->|"delivers props"| IF
IF -->|"loads & runs"| FEENTRY

NOTEHTML["Note: allow_html is a security toggle\n(trusted content only)"]:::note
NOTESTATE["Note: chat history is maintained in st.session_state\n(component is presentational)"]:::note
PYAPI -.->|"guardrail"| NOTEHTML
STATE -.->|"ownership"| NOTESTATE

end

%% =======================
%% BUILD / PACKAGE / RELEASE
%% =======================
subgraph "Build & Packaging: Source → Artifacts → Distribution"
direction TB

subgraph "Frontend Build"
direction TB
FESRC["frontend/src/\n(TypeScript/TSX sources)"]:::frontend
VITE["Vite build toolchain\n(package.json + vite.config + tsconfig)"]:::build
FEBUILD[("frontend/build/*\n(static compiled assets)")]:::artifact
ASSETM["asset-manifest.json\n(asset mapping)"]:::artifact

FESRC -.->|"npm run build"| VITE
VITE -.->|"outputs"| FEBUILD
FEBUILD -.->|"includes"| ASSETM
end

subgraph "Python Packaging"
direction TB
SETUP["setup.py\n(build sdist/wheel)"]:::build
MANI["MANIFEST.in\n(include build assets)"]:::build
REQ["requirements.txt\n(runtime deps)"]:::build
WHEEL[("sdist/wheel artifact\nstreamlit-chat")]:::artifact
end

subgraph "Distribution & Consumption"
direction TB
CI["CI Workflows\n(build/test/publish)"]:::build
PYPI["PyPI"]:::external
PIP["pip install streamlit-chat"]:::external
CONS["Consumer Environment\nimports + runs Streamlit app"]:::external
end

%% Build-time flows (dashed)
FEBUILD -.->|"packaged with"| SETUP
MANI -.->|"controls files in"| SETUP
REQ -.->|"declares deps for"| SETUP
SETUP -.->|"produces"| WHEEL
CI -.->|"publishes"| PYPI
WHEEL -.->|"uploaded to"| PYPI
PYPI -.->|"download"| PIP
PIP -.->|"installs into"| CONS
CONS -.->|"runs"| APP

end

%% =======================
%% REPO UTILITIES / DOCS
%% =======================
subgraph "Repo Utilities (Docs / Examples / Tests)"
direction TB
EX["examples/chatbot.py\n(example consumer usage)"]:::external
TEST["test_component.py\n(local component harness)"]:::build
DOCS["docs/\n(documentation content)"]:::build
MK["mkdocs.yml\n(docs build config)"]:::build

EX -.->|"demonstrates usage of"| PYAPI
TEST -.->|"exercises"| PYAPI
DOCS -.->|"documents"| PYAPI
MK -.->|"builds"| DOCS
CI -.->|"builds/publishes"| DOCS
end

%% =======================
%% Click Events (from component_mapping)
%% =======================
click PYAPI "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/__init__.py"
click SETUP "https://github.com/ai-yash/st-chat/blob/main/setup.py"
click MANI "https://github.com/ai-yash/st-chat/blob/main/MANIFEST.in"
click REQ "https://github.com/ai-yash/st-chat/blob/main/requirements.txt"
click TEST "https://github.com/ai-yash/st-chat/blob/main/test_component.py"
click EX "https://github.com/ai-yash/st-chat/blob/main/examples/chatbot.py"
click FESRC "https://github.com/ai-yash/st-chat/tree/main/streamlit_chat/frontend/src/"
click FEENTRY "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/main.tsx"
click FECHAT "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/Chat.tsx"
click FEST "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/stChat.tsx"
click FEMSG "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/message.tsx"
click FEAV "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/avatar.tsx"
click CSSCHAT "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/stChat.css"
click CSSBASE "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/src/index.css"
click VITE "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/vite.config.ts"
click VITE "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/package.json"
click VITE "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/tsconfig.json"
click FEBUILD "https://github.com/ai-yash/st-chat/tree/main/streamlit_chat/frontend/build/"
click ASSETM "https://github.com/ai-yash/st-chat/blob/main/streamlit_chat/frontend/build/asset-manifest.json"
click DOCS "https://github.com/ai-yash/st-chat/tree/main/docs/"
click MK "https://github.com/ai-yash/st-chat/blob/main/mkdocs.yml"
click CI "https://github.com/ai-yash/st-chat/tree/main/.github/workflows/"

%% =======================
%% Styles
%% =======================
classDef runtime fill:#E8F4FF,stroke:#1E5AA8,stroke-width:1.4,color:#0B2545;
classDef frontend fill:#EFFFF4,stroke:#1B7F3A,stroke-width:1.4,color:#0B2E13;
classDef pkg fill:#FFF4E6,stroke:#B85C00,stroke-width:1.4,color:#4A2A00;
classDef build fill:#F2F0FF,stroke:#5B4CC4,stroke-width:1.4,color:#1D174C;
classDef artifact fill:#FFF0F6,stroke:#B0005A,stroke-width:1.4,color:#4A0025;
classDef external fill:#F7F7F7,stroke:#616161,stroke-width:1.2,color:#1F1F1F;
classDef note fill:#FFFDE7,stroke:#C9B200,stroke-width:1.2,color:#3B3300;
```
