# 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:


*\[Rich HTML output -- view on the documentation site\]*


`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`](https://mjfrigaard.github.io/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:


``` python
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()](../reference/create_app.md#shypermaid.create_app), not [run_app()](../reference/run_app.md#shypermaid.run_app). [run_app()](../reference/run_app.md#shypermaid.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()](../reference/create_app.md#shypermaid.create_app) calls `app_ui()` and `server()`, those call the modules, and only [viewer_server()](../reference/viewer_server.md#shypermaid.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:


``` python
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()](../reference/render_config.md#shypermaid.render_config) and [set_direction()](../reference/set_direction.md#shypermaid.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()](../reference/create_app.md#shypermaid.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`:

``` python
from .app import app, create_app, run_app
```

The 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](02.02-explanation-render-cycle.md) page follows one edit through all three layers.
