# jupyter/jupyter_core architecture

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

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

## Overview

##### Project type and purpose
- This is an open‑source Python library called “Jupyter Core.”
- It provides core common functionality (base application classes, configuration, path management, migration and troubleshooting utilities) for the wider Jupyter ecosystem.
- It exposes a CLI entrypoint (`jupyter`) and a set of reusable modules that other Jupyter subprojects import and extend.

##### File structure
- Top‑level files:
- `jupyter.py` – the main CLI entrypoint;
- `pyproject.toml` – build and packaging configuration;
- `.github/` and workflow YAMLs – CI/CD and release automation;
- `docs/` – Sphinx documentation;
- `examples/` – shell wrappers and completion scripts;
- `scripts/` – thin wrappers invoking the CLI;
- `tests/` – unit tests for each module.
- Core package `jupyter_core/` contains:
- `application.py` – base `JupyterApp` class and CLI bootstrap;
- `command.py` – command‐line dispatch and subcommands;
- `migrate.py` – profile/config migration logic;
- `paths.py` – resolution of Jupyter directories;
- `troubleshoot.py` – diagnostics collector;
- `utils/` – shared helper functions;
- `version.py` – package version management.

##### README for additional insights
- Confirms that Jupyter Core “doesn’t do much on its own” but underpins all other Jupyter projects.
- Emphasizes editable installs, testing with pytest, Sphinx docs, and pre‑commit formatting.

- Clear, concise labels for each component (e.g., “CLI Entry,” “Application Bootstrap,” “Path Resolver”).
- Layering: CLI layer at top, library core in middle, external integrations at bottom.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLIEntrypoint["jupyter.py (CLI Entrypoint)"]:::core
        WrapperScripts["scripts/jupyter, scripts/jupyter-migrate"]:::core
        ShellCompletions["examples/jupyter-completion.bash, examples/completions-zsh"]:::core
    end

    %% Core Library
    subgraph "Core Library (jupyter_core)" 
        direction TB
        AppBootstrap["application.py (App Bootstrap)"]:::core
        CommandDispatch["command.py (Command Dispatch)"]:::core
        PathResolver["paths.py (Path Management)"]:::core
        MigrationEngine["migrate.py (Migration Engine)"]:::core
        Diagnostics["troubleshoot.py (Diagnostics Collector)"]:::core
        Utilities["utils/ (Utilities)"]:::core
        VersionMgmt["version.py (Version Management)"]:::core
        MainModule["__main__.py (CLI Module)"]:::core
        TypedStub["py.typed (Typed Indicator)"]:::core
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        FileSystem["Filesystem (Config Dirs)"]:::external
        OtherJupyter["Other Jupyter Projects"]:::external
        PackageInstaller["pip/setuptools"]:::external
        DocsBuild["Sphinx Docs"]:::external
    end

    %% Support Pipelines
    subgraph "Support Processes"
        direction TB
        Tests["tests/ (Test Suite)"]:::core
        CI[".github/workflows/ (CI/CD)"]:::external
        DocsSource["docs/ (Documentation)"]:::external
    end

    %% Relationships
    CLIEntrypoint -->|"invokes"| AppBootstrap
    WrapperScripts -->|wraps CLI| CLIEntrypoint
    ShellCompletions -->|provides completions| CLIEntrypoint

    AppBootstrap -->|"dispatches"| CommandDispatch
    CommandDispatch -->|"uses"| PathResolver
    CommandDispatch -->|"uses"| MigrationEngine
    CommandDispatch -->|"uses"| Diagnostics
    AppBootstrap -->|"imports"| Utilities
    CommandDispatch -->|"imports"| Utilities
    PathResolver -->|"imports"| Utilities
    MigrationEngine -->|"imports"| Utilities
    Diagnostics -->|"imports"| Utilities

    AppBootstrap -->|"entrypoint"| MainModule
    MainModule -->|"typed marker"| TypedStub

    CommandDispatch -->|subclassed by| OtherJupyter
    PathResolver -->|reads/writes| FileSystem
    MigrationEngine -->|reads old configs| FileSystem
    Diagnostics -->|collects from| FileSystem

    Tests -->|tests modules| AppBootstrap
    Tests -->|tests modules| CommandDispatch
    Tests -->|tests modules| PathResolver
    Tests -->|tests modules| MigrationEngine
    Tests -->|tests modules| Diagnostics
    Tests -->|tests modules| Utilities

    DocsSource -->|builds| DocsBuild
    DocsSource -->|includes| AppBootstrap
    DocsSource -->|includes| Utilities

    CI -.->|automates tests/docs/releases| CI
    CI -.->|runs| Tests
    CI -.->|builds| DocsBuild

    %% Click Events
    click CLIEntrypoint "https://github.com/jupyter/jupyter_core/blob/main/jupyter.py"
    click WrapperScripts "https://github.com/jupyter/jupyter_core/tree/main/scripts/jupyter"
    click WrapperScripts "https://github.com/jupyter/jupyter_core/tree/main/scripts/jupyter-migrate"
    click ShellCompletions "https://github.com/jupyter/jupyter_core/blob/main/examples/jupyter-completion.bash"
    click ShellCompletions "https://github.com/jupyter/jupyter_core/tree/main/examples/completions-zsh"
    click AppBootstrap "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/application.py"
    click CommandDispatch "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/command.py"
    click PathResolver "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/paths.py"
    click MigrationEngine "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/migrate.py"
    click Diagnostics "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/troubleshoot.py"
    click Utilities "https://github.com/jupyter/jupyter_core/tree/main/jupyter_core/utils/"
    click VersionMgmt "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/version.py"
    click MainModule "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/__main__.py"
    click TypedStub "https://github.com/jupyter/jupyter_core/blob/main/jupyter_core/py.typed"
    click DocsSource "https://github.com/jupyter/jupyter_core/tree/main/docs/"
    click Tests "https://github.com/jupyter/jupyter_core/tree/main/tests/"
    click CI "https://github.com/jupyter/jupyter_core/tree/main/ .github/workflows/"
    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef external fill:#90EE90,stroke:#000
    classDef pipeline stroke-dasharray: 5 5,color:#666
    class CI pipeline
    class DocsBuild external
```
