diff --git a/docs/source/developers/architecture.rst b/docs/source/developers/architecture.rst new file mode 100644 index 0000000000..1a12078437 --- /dev/null +++ b/docs/source/developers/architecture.rst @@ -0,0 +1,73 @@ +.. _architecture: + +Architecture Diagrams +===================== + +This page describes the Jupyter Server architecture and the main workflows. +This information is useful for developers who want to understand how Jupyter +Server components are connected and how the principal workflows look like. + +To make changes for these diagrams, use `the Draw.io `_ +open source tool to edit the png file. + + +Jupyter Server Architecture +--------------------------- + +The Jupyter Server system can be seen in figure below: + +.. image:: ../images/jupyter-server-architecture.drawio.png + :alt: Jupyter Server Architecture + :width: 100% + :align: center + +Jupyter Server contains the following components: + +- **ServerApp** is the main Tornado-based application which connects all + components together. + +- **Config Manager** initializes configuration for the ServerApp. You can define + custom classes for the Jupyter Server managers using this config and change + SererApp settings. Follow :ref:`the Config File Guide ` to + learn about configuration settings and how to build custom config. + +- **Custom Extensions** allow you to create the custom Server's REST API endpoints. + Follow :ref:`the Extension Guide ` to know more about extending + ServerApp with extra request handlers. + +- **Gateway Server** is a web server that, when configured, provides access to + Jupyter Kernels running on other hosts. There are different ways to create a + gateway server. If your ServerApp needs to communicate with remote Kernels + residing within resource-managed clusters, you can use + `Enterprise Gateway `_, + otherwise, you can use + `Kernel Gateway `_, where + Kernels run locally to the gateway server. + +- **Contents Manager and File Contents Manager** are responsible for serving + Notebook on the file system. Session Manager uses Contents Manager to receive + Kernel path. Follow :ref:`the Contents API guide ` to learn + about Contents Manager. + +- **Session Manager** processes users' Sessions. When a user starts a new Kernel, + Session Manager starts a process to provision Kernel for the user and generates + a new Session ID. Each opened Notebook has a separate Session, but different + Notebook Kernels can use the same Session. That is useful if the user wants to + share data across various opened Notebooks. Session Manager uses SQLite3 + DataBase to store the Session information. The database is stored in memory by + default, but can be configured to save to disk. + +- **Mapping Kernel Manager** is responsible for managing the lifecycles of the + Kernels running within the ServerApp. It starts a new Kernel for a user's Session + and facilitates interrupt, restart, and shutdown operations against the Kernel. + +- **Jupyter Client** library is used by Jupyter Server to work with the Notebook + Kernels. + + - **Kernel Manager** manages a single Kernel for the Notebook. To know more about + Kernel Manager, follow + `the Jupyter Client APIs documentation `_. + + - **Kernel Spec Manager** parses files with JSON specification for a Kernels, + and provides a list of available Kernel configurations. To learn about + Kernel Spec, check `the Jupyter Client guide `_. diff --git a/docs/source/developers/extensions.rst b/docs/source/developers/extensions.rst index b54b919cc4..f9e1178d26 100644 --- a/docs/source/developers/extensions.rst +++ b/docs/source/developers/extensions.rst @@ -1,3 +1,5 @@ +.. _extensions: + ================= Server Extensions ================= diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst index b8f5140dbb..10ab7e1d8b 100644 --- a/docs/source/developers/index.rst +++ b/docs/source/developers/index.rst @@ -8,6 +8,7 @@ These pages target people writing Jupyter Web applications and server extensions :maxdepth: 1 :name: developers + architecture dependency rest-api extensions diff --git a/docs/source/images/jupyter-server-architecture.drawio.png b/docs/source/images/jupyter-server-architecture.drawio.png new file mode 100644 index 0000000000..385a35bd1d Binary files /dev/null and b/docs/source/images/jupyter-server-architecture.drawio.png differ