# jupyter-server/jupyter_server architecture

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

- Interactive diagram: https://gitdiagram.com/jupyter-server/jupyter_server
- Repository: https://github.com/jupyter-server/jupyter_server

## Overview

##### Project type and purpose
- Jupyter Server is a backend framework that provides core services, REST endpoints, and WebSocket support for Jupyter web applications (Notebook, Lab, Voilà).
- It is not a full‐stack UI application itself but a modular server “engine” that client UIs talk to over HTTP/WebSocket.

##### File structure
- Top-level module “jupyter_server/”: the monolithic server package.
- subpackages for authentication (auth), base handlers (base), extension hooks (extension), file services (files), gateway support (gateway), internationalization (i18n), kernelspec management (kernelspecs), nbconvert endpoints (nbconvert), Prometheus metrics (prometheus), general services (services/*), static assets (static), templates (templates), terminal support (terminal), view endpoints (view).
- “jupyter_server/serverapp.py” and “__main__.py” define the application entrypoint.
- “services/…” subdirectory implements a service-layer API for contents, kernels, sessions, events, config, nbconvert, security, etc.
- “handlers.py” files define HTTP request handlers, tied to Tornado routing.
- “tests/” covers unit and integration tests for each component.
- “examples/” show extension usage and configuration.
- Configuration files (pyproject.toml, package.json) and CI/workflows indicate Python package + npm static builds, ReadTheDocs docs.

##### README for additional insights
- Confirms purpose as a backend server for Jupyter frontends.
- Mentions REST endpoints, core services, versioning, installation and launch via “jupyter server”.
- No database: uses local filesystem for contents, in-memory for session and kernel state.

##### Elements
- Clear labels (e.g., “Tornado HTTP Server”, “ContentsService”, “KernelService”, “Auth Decorator”).
- Transport Layer (blue)
- Handler Layer (green)
- Service Layer (orange)
- Resource Managers (yellow)
- Extensions & Plugins (purple)
- External systems (gray)

##### Be detailed but focused
- Do not attempt to show every Python module file.
- Logical component (Auth, Contents, Kernels, Sessions, Nbconvert, Gateway, Extensions, Metrics).
- How they plug together in the running server process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser["Browser (Lab / Notebook / Voilà)"]:::external

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        HTTPServer["Tornado HTTP Server"]:::transport
        WebSocketServer["Tornado WebSocket"]:::transport
    end

    %% Handler Layer
    subgraph "Handler Layer"
        direction TB
        AuthLogin["Login Handler"]:::handler
        AuthLogout["Logout Handler"]:::handler
        APIHandlers["API Handlers"]:::handler
        ContentsHandlers["Contents Handlers"]:::handler
        KernelHandlers["Kernel Handlers"]:::handler
        SessionHandlers["Session Handlers"]:::handler
        EventsHandlers["Events Handlers"]:::handler
        ConfigHandlers["Config Handlers"]:::handler
        SecurityHandlers["Security Handlers"]:::handler
        KernelspecHandlers["Kernelspec Handlers"]:::handler
        NbconvertHandlers["Nbconvert Handlers"]:::handler
        GatewayHandlers["Gateway Handlers"]:::handler
        StaticHandler["Static File Handler"]:::handler
        TemplateHandler["Template Handler"]:::handler
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AuthService["Auth Service"]:::service
        ContentsService["Contents Service"]:::service
        KernelService["Kernel Service"]:::service
        SessionService["Session Service"]:::service
        EventsService["Events Service"]:::service
        ConfigService["Config Service"]:::service
        SecurityService["Security REST Service"]:::service
        KernelspecService["Kernelspec Service"]:::service
        NbconvertService["Nbconvert Service"]:::service
        APIService["OpenAPI Schema Service"]:::service
        GatewayService["Gateway Client Service"]:::service
        MetricsService["Prometheus Metrics Exporter"]:::service
    end

    %% Resource Managers
    subgraph "Resource Managers"
        direction TB
        FileManager["File Manager"]:::resource
        KernelManager["Kernel Manager"]:::resource
        SessionManager["Session Manager"]:::resource
        Checkpoints["Checkpoints Manager"]:::resource
    end

    %% Extensions & Plugins
    subgraph "Extension Manager"
        direction TB
        ExtensionManager["Extension Manager"]:::extension
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FileSystem["Local Filesystem"]:::external
        Gateway["Remote Kernel Gateway"]:::external
    end

    %% Application Entrypoint
    MainApp["jupyter_server Application"]:::transport

    %% Connections
    Browser --> HTTPServer
    Browser --> WebSocketServer

    HTTPServer --> AuthLogin
    HTTPServer --> AuthLogout
    HTTPServer --> APIHandlers
    HTTPServer --> ContentsHandlers
    HTTPServer --> KernelHandlers
    HTTPServer --> SessionHandlers
    HTTPServer --> EventsHandlers
    HTTPServer --> ConfigHandlers
    HTTPServer --> SecurityHandlers
    HTTPServer --> KernelspecHandlers
    HTTPServer --> NbconvertHandlers
    HTTPServer --> GatewayHandlers
    HTTPServer --> StaticHandler
    HTTPServer --> TemplateHandler

    WebSocketServer --> KernelHandlers

    AuthLogin --> AuthService
    AuthLogout --> AuthService
    APIHandlers --> APIService
    ContentsHandlers --> ContentsService
    KernelHandlers --> KernelService
    SessionHandlers --> SessionService
    EventsHandlers --> EventsService
    ConfigHandlers --> ConfigService
    SecurityHandlers --> SecurityService
    KernelspecHandlers --> KernelspecService
    NbconvertHandlers --> NbconvertService
    GatewayHandlers --> GatewayService

    ContentsService --> FileManager
    ContentsService --> Checkpoints
    KernelService --> KernelManager
    SessionService --> SessionManager

    FileManager --> FileSystem
    KernelManager --> Gateway
    GatewayService --> Gateway

    ExtensionManager --> HTTPServer
    ExtensionManager --> AuthService
    ExtensionManager --> ContentsService

    MetricsService --> HTTPServer

    MainApp --> HTTPServer
    MainApp --> WebSocketServer
    MainApp --> ExtensionManager
    MainApp --> MetricsService

    %% Click Events
    click MainApp "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/__main__.py"
    click MainApp "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/serverapp.py"
    click AuthLogin "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/auth/login.py"
    click AuthLogout "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/auth/logout.py"
    click AuthService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/auth/authorizer.py"
    click AuthService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/auth/decorator.py"
    click APIService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/api/api.yaml"
    click APIHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/api/handlers.py"
    click ContentsService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/contents/manager.py"
    click FileManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/contents/filemanager.py"
    click FileManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/contents/fileio.py"
    click Checkpoints "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/contents/checkpoints.py"
    click ContentsHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/contents/handlers.py"
    click KernelManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/kernelmanager.py"
    click KernelService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/connection/base.py"
    click KernelService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/connection/channels.py"
    click KernelHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/handlers.py"
    click GatewayService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/gateway/gateway_client.py"
    click GatewayHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/gateway/handlers.py"
    click GatewayService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/gateway/managers.py"
    click SessionManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/sessions/sessionmanager.py"
    click SessionHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/sessions/handlers.py"
    click EventsHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/events/handlers.py"
    click ConfigService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/config/manager.py"
    click ConfigHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/config/handlers.py"
    click NbconvertHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/nbconvert/handlers.py"
    click NbconvertHandlers "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/nbconvert/handlers.py"
    click SecurityService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/security/handlers.py"
    click KernelspecService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernelspecs/handlers.py"
    click StaticHandler "https://github.com/jupyter-server/jupyter_server/tree/main/jupyter_server/static/"
    click TemplateHandler "https://github.com/jupyter-server/jupyter_server/tree/main/jupyter_server/templates/"
    click MetricsService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/prometheus/metrics.py"
    click MetricsService "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/prometheus/log_functions.py"
    click HTTPServer "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/base/handlers.py"
    click HTTPServer "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/base/zmqhandlers.py"
    click WebSocketServer "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/base/websocket.py"
    click ExtensionManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/extension/manager.py"
    click ExtensionManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/extension/application.py"
    click ExtensionManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/extension/handler.py"
    click ExtensionManager "https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/extension/serverextension.py"

    %% Styles
    classDef transport fill:#cce5ff,stroke:#004085,color:#004085
    classDef handler fill:#d4edda,stroke:#155724,color:#155724
    classDef service fill:#ffeeba,stroke:#856404,color:#856404
    classDef resource fill:#fff3cd,stroke:#856404,color:#856404
    classDef extension fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
