How posit-dev/py-shiny works
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.