How ekourlit/scipy2024-tutorial-thinking-in-arrays works
Project Context and Type
• This repository is not a traditional application backend or a microservice architecture but rather a content and environment setup for an interactive tutorial. It hosts Jupyter notebooks (across parts 1, 2, and 3) that provide lectures, exercises, and solutions.
• The project is intended to be executed by participants either via a cloud-based environment (Nebari) or locally using conda/mamba. The artifacts include slides, workbooks, projects, and solution notebooks.
Main Components
a. Tutorial Content Modules:
• Three main module groups: part-1, part-2, and part-3.
• Within each group, delineate the following notebooks:
▪ lecture-slides (presentation component)
▪ lecture-workbook (interactive exercise space)
▪ project (guided exercises or class projects)
▪ solutions (discussions and solution walkthroughs)
b. Execution Environment:
• JupyterLab: The primary interactive environment for running the notebooks.
▪ Note that the notebooks are launched in JupyterLab, which is either started directly on the user's machine or provided through the Nebari platform.
• Environment Setup:
▪ environment.yml represents the dependency management and library versions.
▪ The included .devcontainer with its configuration (devcontainer.json and postCreateCommand.sh) supports a containerized development environment.
c. External/Supporting Infrastructure:
• Nebari Cloud Platform: This is mentioned for the live tutorial day, where participants run Jupyter notebooks in the cloud.
• Conda/Mamba/Miniforge: Tools for local environment setup using environment.yml.
• GitHub Repository and Git for version control and distribution of content.
Relationships and Interactions
• A clear separation between the content (the three parts with their respective notebooks) and the runtime environment.
• How users retrieve the repository (via Git clone).
• Set up their environment (using environment.yml or devcontainer configuration).
• Launch JupyterLab to interact with the notebooks.
• Optionally, the flow from opening lecture-workbook when live instructions are ongoing while lecture-slides are displayed on a projected screen.
• Feedback loop during the live session with tutors’ support and shared progress via the external Slido service.
Architectural Patterns and Design Principles
• Modularity: Each tutorial part is self-contained but follows a consistent structure (slides, workbook, project, solutions).
• Environment Abstraction: Separation between the content and the execution environment (local/conda vs Nebari/cloud vs containerized development), aligning with best practices for reproducible computational environments.
• Simplicity and Reusability: The content layout and environmental configuration (via devcontainer and environment.yml) is arranged so that the tutorial can be run reliably across different platforms.
Final Assembly
• At the top, show the GitHub repository as the starting point for users who clone the code.
• Then branch out the deployment options:
• One branch leading to a “Local Environment” (conda/Miniforge) that connects to “JupyterLab.”
• An alternative branch via “Container (devcontainer)” which also leads to “JupyterLab.”
• A “Cloud Execution” branch pointing to Nebari.
• “JupyterLab” node to a grouped component that represents all tutorial parts (illustrate with a container that has three sections: part-1, part-2, part-3) with their respective notebooks.
• Optionally, represent the "live event" feedback loop where the Slido service is integrated during the live tutorial session.
• Don’t forget to add small notes for configuration files (environment.yml, devcontainer.json, postCreateCommand.sh) as key supporting components.