%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%%
flowchart TD
subgraph App["<strong>app.py</strong>"]
run(["<code>run_app()</code>"])
create("<code>create_app()</code>")
appui("<code>app_ui()</code>")
srv("<code>server()</code>")
end
subgraph Modules["<strong>modules.py</strong>"]
editor("<code>editor_ui()</code><br><code>editor_server()</code>")
viewer("<code>viewer_ui()</code><br><code>viewer_server()</code>")
end
subgraph Diagram["<strong>diagram.py</strong>"]
dir[["<code>set_direction()</code>"]]
cfg[["<code>render_config()</code>"]]
consts[("<code>THEMES</code>, <code>LOOKS</code>,<br><code>DIRECTIONS</code>, <code>DEFAULT_CODE</code>")]
end
www[("<code>www/</code><br>binding, styles, libraries")]
run --> create --> appui & srv
create -.-> www
appui --> editor & viewer
srv --> editor & viewer
viewer --> dir & cfg
editor & viewer --> consts
style App fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
style Modules fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
style Diagram fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
style run fill:#2A6F77,color:#FFFFFF
style create fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style appui fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style srv fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style editor fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style viewer fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
Package Layout
This page explains how shypermaid is split into files and why. It won’t tell you how to do something; the How-To guides cover that.
Three layers
The package has three layers, and each one only calls the layer below it. The diagram below shows the files in each layer and the calls between them:
app.py assembles the page and launches the server. modules.py holds the two Shiny modules. diagram.py holds plain Python functions and the menu choices.
The call tree from the source
The diagram above is drawn by hand, so it can drift from the code. callgrove reads the source files and builds the same tree without running the app. The cell below runs on every docs build, so the tree always matches the package:
from pathlib import Path
import shypermaid
from callgrove import call_tree_dir
pkg = Path(shypermaid.__file__).parent
call_tree_dir(pkg, root="create_app")█─create_app
├─█─app_ui
│ ├─editor_ui
│ └─█─viewer_ui
│ └─_tool
└─█─server
├─editor_server
└─█─viewer_server
├─code_theme
├─█─set_direction
│ ├─_declaration
│ └─_set_statement
└─render_config
The tree starts at create_app(), not run_app(). run_app() passes the app to Shiny as the string "shypermaid.app:app", so there is no call for callgrove to follow, and its tree is a single node.
Each layer shows up one level below the last. create_app() calls app_ui() and server(), those call the modules, and only viewer_server() reaches into diagram.py. _tool() is a private helper that builds the buttons in the viewer’s tool rail.
modules_only=True keeps only the functions decorated with @module.ui or @module.server. The wrappers in between are removed, and the modules move up to take their place:
call_tree_dir(pkg, root="create_app", modules_only=True)█─create_app
├─editor_ui
├─viewer_ui
├─editor_server
└─viewer_server
Why the helpers are Shiny free
diagram.py never imports shiny. Its two functions take strings and return a string or a dictionary, so the tests call them directly without starting a session. That’s why diagram.py has full test coverage while the module servers do not.
The same split keeps the menu choices in one place. THEMES, LOOKS, and DIRECTIONS fill the viewer’s menus and also validate the arguments to render_config() and set_direction(). A new theme only needs a new dictionary entry.
Why the drawing happens in the browser
Mermaid is a JavaScript library, so the diagram is drawn in the browser, not in Python. The files in www/ handle that side. mermaid-binding.js receives the code from the server, draws it, and runs the pan, zoom, fullscreen, and download tools. styles.css lays out the editor and canvas. vendor/ holds pinned copies of Mermaid and svg-pan-zoom, so the app never reaches out to a CDN.
create_app() serves www/ at /shypermaid through the static_assets argument. The folder ships inside the package, so the paths work after a regular install as well as an editable one.
A name to watch: shypermaid.app
__init__.py re-exports the App object named app from app.py:
from .app import app, create_app, run_appThe re-exported name matches the submodule name, so after import shypermaid the attribute shypermaid.app is the App object, not the module. shiny run shypermaid.app:app still works because it imports the module by its full name. Plain attribute access does not, so code that needs app_ui() or WWW should use from shypermaid.app import app_ui, WWW.
Recap
The package keeps the app, the modules, and the helpers in separate files, and each layer calls only the one below it. The helpers stay free of Shiny so they’re easy to test, and the drawing lives in www/ because Mermaid runs in the browser. The Render Cycle page follows one edit through all three layers.