# posit-dev/py-shiny architecture

> Architecture diagram of the GitHub repository posit-dev/py-shiny, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/posit-dev/py-shiny
- Repository: https://github.com/posit-dev/py-shiny

## Overview

##### Main Components
- Server/Framework Core – Represented by the “shiny” package. This includes modules for handling sessions (shiny/session), routing, request handling (shiny/_app.py, shiny/_main.py, shiny/express, etc.), and the reactive engine (shiny/reactive, shiny/render).
- User Interface Components – Under “shiny/ui”, these encapsulate UI controls, layout functions, and helper functions that create reactive web elements.
- Frontend/Static Assets – The “js” folder and “shiny/www” directory house the JavaScript (e.g., for dynamic table manipulation, chat components, markdown streaming, etc.), CSS, and other static resources crucial for rendering the client-side interface.
- Examples & Templates – In folders like “examples”, “shiny/api-examples”, and “shiny/templates”, which demonstrate how to build complete apps. This shows how the framework is consumed to build real applications.
- Development & Testing Infrastructure – CI/CD configuration files (inside “.github/workflows”), Makefile, pre-commit configurations, extensive tests (both unit tests in “tests” and end-to-end tests in “tests/playwright”). These support quality and automation.

##### Relationships & Interactions
- The backend framework (Python modules in shiny/) acts as the web server that starts the app (via the CLI “shiny create” or “shiny run”) and handles HTTP/websocket connections.
- The reactive programming engine sits at the core, managing state updates and triggering UI re-renders when input values change.
- Template examples and API examples illustrate how client apps plug into the core system, which might be depicted as “Application Templates” consuming the framework’s APIs.
- The testing and CI infrastructure validates changes in every layer—from the backend modules to the JavaScript interactions.

##### Architectural Patterns & Design Principles
- Modular & Pluggable Design – The framework distinguishes between core engine (reactivity, session management), UI building blocks (input/output components), and express mode (simplified rapid prototyping). Represent these as separate modules that interact.

##### Relevant Technologies
- Python – The core programming language for the server, with modules handling request routing, reactive programming, and templating.
- JavaScript/TypeScript – Managed in the “js” directory, this layer provides the client-side interactions coupled with static assets in “shiny/www”.
- CSS & Sass – The styling system including Bootstrap themes and custom SCSS code found in various “sass” directories.
- GitHub Actions & Testing Tools – Represent the testing pipelines (Pytest, Playwright) that ensure robustness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend - Shiny Core
    subgraph "Backend - Shiny Core"
        S1["Session Management (shiny/session)"]:::backend
        S2["Routing & Request Handling (shiny/_app.py, shiny/_main.py, shiny/express)"]:::backend
        S3["Reactive Engine (shiny/reactive, shiny/render)"]:::backend
    end

    %% UI Components
    subgraph "UI Components"
        UI["UI Components (shiny/ui)"]:::ui
    end

    %% Frontend Assets
    subgraph "Frontend Assets"
        F1["JavaScript (js)"]:::frontend
        F2["Static Files (shiny/www)"]:::frontend
    end

    %% Examples & Templates
    subgraph "Examples & Templates"
        E1["Examples (examples)"]:::examples
        E2["API Examples (shiny/api-examples)"]:::examples
        E3["Templates (shiny/templates)"]:::examples
    end

    %% Development & Testing
    subgraph "Dev & Testing"
        D1["CI/CD (.github/workflows)"]:::dev
        D2["Build Script (Makefile)"]:::dev
        D3["Tests (tests)"]:::dev
    end

    %% Interactions between Backend and UI
    UI -->|"triggers"| S3
    S3 -->|"updates"| UI

    %% UI and Frontend interaction
    UI -->|"renders_output"| F2
    F1 -->|"handles_client_events"| UI

    %% Backend serving static assets
    S2 -->|"delivers_HTML/CSS/JS"| F2

    %% Examples utilizing core framework and UI
    E1 -->|"built_with"| S2
    E1 -->|"built_with"| UI
    E2 -->|"built_with"| S2
    E2 -->|"built_with"| UI
    E3 -->|"built_with"| S2
    E3 -->|"built_with"| UI

    %% Dev & Testing verifying components
    D3 -->|"tests"| S2
    D3 -->|"tests"| UI
    D3 -->|"tests"| F1
    D3 -->|"tests"| F2
    D1 -->|"CI_pipeline"| S2
    D2 -->|"builds"| S2

    %% Click Events
    click S2 "https://github.com/posit-dev/py-shiny/tree/main/shiny/"
    click UI "https://github.com/posit-dev/py-shiny/tree/main/shiny/ui/"
    click F1 "https://github.com/posit-dev/py-shiny/tree/main/js/"
    click F2 "https://github.com/posit-dev/py-shiny/tree/main/shiny/www/"
    click E1 "https://github.com/posit-dev/py-shiny/tree/main/examples/"
    click E2 "https://github.com/posit-dev/py-shiny/tree/main/shiny/api-examples/"
    click E3 "https://github.com/posit-dev/py-shiny/tree/main/shiny/templates/"
    click D1 "https://github.com/posit-dev/py-shiny/tree/main/.github/workflows/"
    click D2 "https://github.com/posit-dev/py-shiny/tree/main/Makefile"
    click D3 "https://github.com/posit-dev/py-shiny/tree/main/tests/"

    %% Styles
    classDef backend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef ui fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef frontend fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef examples fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef dev fill:#D2B4DE,stroke:#78281F,stroke-width:2px;
```
