# holoviz/panel architecture

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

- Interactive diagram: https://gitdiagram.com/holoviz/panel
- Repository: https://github.com/holoviz/panel

## Overview

##### Main Components
- Core Library: The “panel” package is the heart of the framework and includes many submodules. This includes core functionalities like reactive programming (panel/reactive.py), widget models (panel/models/*), layout management (panel/layout/*), and viewable components (panel/viewable.py).
- I/O & Server Modules: Modules under panel/io (e.g., panel/io/server.py, panel/io/embed.py, panel/io/rest.py) handle the communication between Python and the browser. They manage callback handling, caching, and embedding into different environments.
- Templates and Themes: In directories like panel/_templates, panel/template, and panel/theme – these support rendering different front-end layouts, integration with CSS, JavaScript resources, and theming (including support for fast and material templates).
- Command and Build Tools: Components such as panel/command (with serve, compile, and convert commands) integrate with tools to bundle resources or create standalone web apps. Also include build scripts (e.g., scripts/build_pyodide_wheels.py, scripts/bundle_resources.py) that showcase how Panel supports multiple deployment types.
- External Integrations: Although not a “module” per se, the README and examples illustrate integrations with visualization libraries (Bokeh, Vega, Altair, Plotly, etc.), as well as compatibility with Jupyter environments, Pyodide/PyScript, and even custom components (supported in dedicated directories).

##### Relationships & Interactions
- Core “Panel” Module interacts with the I/O modules, which then interface with the web server frameworks. For instance, the serve command (panel/command/serve.py) configures the server environment, launches the application (typically using Tornado by default), and interacts with the layout and template modules.
- The Model and Widget Layers: Illustrate how widget models (in panel/models) are bound to the data and reactive logic (via panel/reactive and panel/param). These connect to UI panes (in panel/pane) that are eventually rendered on the front end.

##### Architectural Patterns & Design Principles
- Reactive and Declarative Programming: Emphasize that the core design revolves around a reactive user interface system where state changes in Python automatically trigger updates in the user interface.
- Extensibility: Note the clear extension points—custom components (in panel/custom.py & panel/models/react_component.ts), and integration with various web backends.

##### Final Touches for Detail & Clarity
- Every component should be labeled with both its directory or module name and its purpose (e.g., “panel/io – Handles browser-server communication”).
- Avoid over-complicating by trying to include every single file; instead, focus on the major architectural parts (for instance, grouping tests, documentation, and examples separately from the production code).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    subgraph "User Interaction"
        U["User Browser"]:::user
    end

    %% Integration Layer
    subgraph "Integration Layer (I/O & External)"
        subgraph "I/O & Server Modules"
            C1["panel/io/server.py"]:::io
            C2["panel/io/embed.py"]:::io
            C3["panel/io/rest.py"]:::io
        end
        subgraph "External Integrations"
            D1["panel/io/django.py (Django Adapter)"]:::ext
            D2["panel/io/fastapi.py (FastAPI Adapter)"]:::ext
            D3["examples/apps/django (Django Example)"]:::ext
            D4["examples/apps/fastApi (FastAPI Example)"]:::ext
        end
    end

    %% Logic Layer
    subgraph "Logic Layer (Core Library)"
        B1["panel/reactive.py (Reactive)"]:::logic
        B2["panel/models (Widget Models)"]:::logic
        B3["panel/layout (Layouts)"]:::logic
        B4["panel/viewable.py (Viewable Components)"]:::logic
    end

    %% Presentation Layer
    subgraph "Presentation Layer (Templates & Themes)"
        A1["panel/_templates (Templates)"]:::frontend
        A2["panel/template (Template Engine)"]:::frontend
        A3["panel/theme (Themes)"]:::frontend
    end

    %% Deployment & Build Tools
    subgraph "Deployment & Build Tools"
        E1["panel/command (CLI Commands)"]:::deploy
        E2["scripts/build_pyodide_wheels.py (Pyodide Build)"]:::deploy
        E3["scripts/bundle_resources.py (Resource Bundling)"]:::deploy
    end

    %% Connections
    U -->|"sends_request"| C1

    C1 -->|"triggers"| B1
    C1 -->|"triggers"| B2
    C1 -->|"triggers"| B3
    C1 -->|"triggers"| B4

    B1 -->|"updates"| A1
    B2 -->|"updates"| A2
    B3 -->|"updates"| A2
    B4 -->|"updates"| A3

    D1 -->|"integrates"| C1
    D2 -->|"integrates"| C1
    D3 -->|"integrates"| C1
    D4 -->|"integrates"| C1

    E1 -->|"launches"| C1
    E1 -->|"invokes"| B1
    E2 -->|"bundles"| A1
    E3 -->|"bundles"| A2

    %% Click Events
    click B1 "https://github.com/holoviz/panel/blob/main/panel/reactive.py"
    click B2 "https://github.com/holoviz/panel/tree/main/panel/models"
    click B3 "https://github.com/holoviz/panel/tree/main/panel/layout"
    click B4 "https://github.com/holoviz/panel/blob/main/panel/viewable.py"

    click C1 "https://github.com/holoviz/panel/blob/main/panel/io/server.py"
    click C2 "https://github.com/holoviz/panel/blob/main/panel/io/embed.py"
    click C3 "https://github.com/holoviz/panel/blob/main/panel/io/rest.py"

    click A1 "https://github.com/holoviz/panel/tree/main/panel/_templates"
    click A2 "https://github.com/holoviz/panel/tree/main/panel/template"
    click A3 "https://github.com/holoviz/panel/tree/main/panel/theme"

    click E1 "https://github.com/holoviz/panel/tree/main/panel/command"
    click E2 "https://github.com/holoviz/panel/blob/main/scripts/build_pyodide_wheels.py"
    click E3 "https://github.com/holoviz/panel/blob/main/scripts/bundle_resources.py"

    click D1 "https://github.com/holoviz/panel/blob/main/panel/io/django.py"
    click D2 "https://github.com/holoviz/panel/blob/main/panel/io/fastapi.py"
    click D3 "https://github.com/holoviz/panel/tree/main/examples/apps/django"
    click D4 "https://github.com/holoviz/panel/tree/main/examples/apps/fastApi"

    %% Styles
    classDef user fill:#f9c,stroke:#333,stroke-width:2px;
    classDef io fill:#ccf,stroke:#333,stroke-width:2px;
    classDef ext fill:#cfc,stroke:#333,stroke-width:2px;
    classDef logic fill:#fcf,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cff,stroke:#333,stroke-width:2px;
    classDef deploy fill:#ff9,stroke:#333,stroke-width:2px;
```
