# jupyter/nbgrader architecture

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

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

## Overview

##### Main Components
- Core nbgrader Library: This includes the fundamental Python modules (in the “nbgrader” directory) that encapsulate core functionalities such as the gradebook API, database utilities (using Alembic for migrations), validation and conversion pipelines, and the standardized notebook formats (nbgraderformat).
- Command Line Tools & Apps: Under “nbgrader/apps”, a number of CLI applications (e.g., assignapp, autogradeapp, collectapp, formgradeapp, etc.) are provided to perform tasks like generating assignments, releasing assignments, collecting submissions, performing autograding, and updating the database.
- Jupyter Notebook Extensions: There are several front-end components and integrations:
- The Instructor toolbar extension (visible in the screenshots in the README) that guides instructors in creation and grading that integrates with the Jupyter UI.
- The Formgrader extension that acts as a web interface running in the notebook server (supported by server_extensions in nbgrader).
- The Student assignment list which enables students to view, fetch, submit, and validate their assignments.
- Preprocessors and Plugins: Modules under “nbgrader/preprocessors” and “nbgrader/plugins” act as processing stages. They adjust notebooks by clearing outputs, validating metadata, limiting outputs, and so on before grading occurs.
- External Integrations & Configurations: There are integration points with JupyterHub (e.g., using “nbgrader/auth/jupyterhub.py”) for authentication. Configuration files delivered via the “binder” and “etc/jupyter/…” directories illustrate how external environments and deployment are set up.
- Frontend (TypeScript) Components: In the “src” folder we see directories such as assignment_list, course_list, create_assignment, formgrader, and validate_assignment that likely represent the newer or web-based UI portions that complement or extend the existing Jupyter notebook extensions.

##### Relationships and Interactions Among Components
- The user (instructor or student) interacts with the Jupyter Notebook interface. For instructors, this means using the toolbar to create and manage assignments and using the Formgrader extension for grading. For students, the UI starts with an assignment list.
- The command line apps serve as orchestrators that tie together tasks such as assignment generation, release, collection, and grading. They rely on various preprocessor tools and converters (which can be seen as a processing pipeline) to prepare notebooks.
- The plugins/preprocessors form part of the data processing layer where each notebook submission may pass through several transformation/validation steps before being recorded in the database.
- External tools and configurations (found in directories such as “binder”, “tools”, and “etc”) are used for deployment, demo purposes, and integration with continuous integration workflows (see the GitHub workflows).

##### Architectural Patterns and Design Principles
- Modular Design: The architecture is highly modular. Each “app” in nbgrader/apps represents a specific task (assign, collect, grade, etc.) and is decoupled. This makes it easier to add new functionalities without large-scale refactoring.
- Separation of Concerns: User interface aspects (Jupyter extensions, web UIs built in “src”) are neatly separated from the core grading logic and the database layer.
- Extensibility Through Plugins: The preprocessor and plugin systems make it straightforward to extend or modify the behavior for specific grading or processing needs.
- Pipeline and Workflow Orchestration: The command-line tools and processing pipelines show a clear flow from assignment creation to submission validation and grading; this can be represented as sequential stages.
- Integration with External Systems: Integration layers for authentication (JupyterHub), deployment demos (Binder configurations), and continuous integration (GitHub Workflows) show an ecosystem-oriented design.

##### Detail and Clarity
- Think about using a layered approach (front-end, middleware/processing, and data/persistence layers) to clearly separate concerns.

Good luck with your diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        IU["Instructor UI (Toolbar & Formgrader)"]:::ui
        SU["Student UI (Assignment List)"]:::ui
        FUI["Frontend UI Components"]:::ui
    end

    %% Backend Processing Layer
    subgraph "Backend Processing Layer"
        CL["Core nbgrader Library"]:::backend
        CLI["Command Line Tools & Apps"]:::backend
        PP["Preprocessors"]:::backend
        PL["Plugins"]:::backend
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        DB["Gradebook Database & Alembic Migrations"]:::db
    end

    %% External Integration & Deployment
    subgraph "External Integration & Deployment"
        JH["JupyterHub Authentication"]:::external
        DC["Deployment & Configuration"]:::external
    end

    %% UI to Core interactions
    IU -->|"ManageAssignments"| CL
    SU -->|"SubmitAssignments"| CL
    FUI -->|"WebUIRequests"| CL

    %% CLI Applications interaction
    CLI -->|"CLICommands"| CL

    %% Core processing interactions
    CL -->|"NotebookProcessing"| PP
    CL -->|"ExtensionProcessing"| PL
    CL -->|"RecordGrades"| DB

    %% Preprocessors and Plugins feeding DB
    PP -->|"ProcessedData"| DB
    PL -->|"ProcessedData"| DB

    %% External integration for authentication
    JH -->|"Auth"| IU
    JH -->|"Auth"| SU

    %% Deployment and configuration support
    DC -->|"DeploymentConfig"| CL
    DC -->|"DeploymentConfig"| CLI
    DC -->|"DeploymentSupport"| JH

    %% Styles
    classDef ui fill:#a3d5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d1ffd1,stroke:#333,stroke-width:2px;
    classDef db fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#333,stroke-width:2px;

    %% Click Events
    click IU "https://github.com/jupyter/nbgrader/tree/main/nbgrader/server_extensions/formgrader"
    click SU "https://github.com/jupyter/nbgrader/tree/main/nbgrader/server_extensions/assignment_list"
    click CL "https://github.com/jupyter/nbgrader/blob/main/nbgrader/__init__.py"
    click CLI "https://github.com/jupyter/nbgrader/blob/main/nbgrader/apps/assignapp.py"
    click PP "https://github.com/jupyter/nbgrader/tree/main/nbgrader/preprocessors"
    click PL "https://github.com/jupyter/nbgrader/tree/main/nbgrader/plugins"
    click JH "https://github.com/jupyter/nbgrader/blob/main/nbgrader/auth/jupyterhub.py"
    click DC "https://github.com/jupyter/nbgrader/tree/main/binder"
    click FUI "https://github.com/jupyter/nbgrader/tree/main/src/assignment_list"
```
