# iacopomasi/nlp architecture

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

- Interactive diagram: https://gitdiagram.com/iacopomasi/nlp
- Repository: https://github.com/iacopomasi/nlp

## Overview

##### Project type and purpose
- This is a static-site course website built with Jekyll (a Ruby-based static site generator) that hosts lecture materials (Jupyter notebooks, HTML slides, PDFs, figures) for an NLP course.
- The README describes the curriculum, links to NBViewer/Colab, and shows that lecture materials live under `course/AAxxxx/...` and `notebooks/`.

##### File-structure analysis
- Top-level:
- `.github/workflows/notebook_release.yaml` → CI/CD pipeline for building notebooks and site.
- `_config.yml`, `_layouts/`, `assets/css/` → Jekyll configuration, HTML templates, CSS/SCSS assets.
- `course/AA*` → Lecture-by-lecture content directories with `.ipynb`, `.html`, `.pdf`, data, figs.
- `notebooks/` → General notebooks for Part I.
- `requirements.txt`, `postBuild`, `setup.cfg`, `environment.yml` → Python/Jupyter environment specs (Binder, CI).
- Patterns:
- Static site generator (Jekyll)
- Notebook conversion (nbconvert)
- CI/CD via GitHub Actions
- Asset pipeline (SCSS → CSS)

##### README-driven insights
- Site is published to GitHub Pages
- Notebook links use NBViewer, Colab, and direct HTML exports
- No server-side code; fully static outputs

a. Main components
- Developer workstations (authors editing Markdown, HTML, SCSS, Jupyter notebooks)
- GitHub repository (source)
- GitHub Actions CI (`.github/workflows/notebook_release.yaml`)
- Build agents (Docker/Python environment with nbconvert + Jekyll)
- Jekyll engine (Ruby) + Notebook converter plugin
- Static assets (CSS, images, HTML slides, PDFs)
- GitHub Pages (web hosting/CDN)
- End users (students/instructors accessing site via browser, Colab, NBViewer)

b. Relationships & interactions
1. Developer → push to GitHub repo
2. GitHub Actions triggers on push → spins up container, installs Python env, runs nbconvert to export notebooks to HTML/PDF
3. Jekyll build step pulls in converted HTML, Markdown, layouts, SCSS → generates complete static site
4. CI commits build artifacts (if needed) or directly deploys to `gh-pages` branch
5. GitHub Pages serves final site to end users
6. External services: NBViewer/Colab badges link back to raw notebooks

c. Architectural patterns/design principles
- “GitOps” static-site workflow (source-of-truth in Git)
- CI/CD pipeline for reproducible content builds
- Clear separation: content source vs. build process vs. hosting
- Asset pipeline: SCSS → CSS, notebook conversion

d. Key technologies/frameworks
- Jekyll (Ruby)
- GitHub Actions (CI/CD)
- nbconvert (Python/Jupyter)
- SCSS/SASS (assets/css)
- GitHub Pages (hosting/CDN)
- Binder/requirements.yml (optional live environment)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        README["README.md"]:::content
        NotebooksSrc["notebooks/"]:::content
        CourseSrc["course/"]:::content
        AssetsSrc["assets/"]:::content
        LayoutsSrc["_layouts/"]:::content
        ConfigSrc["_config.yml"]:::content
    end

    %% Source Repository
    GitHubRepo["GitHub Repository"]:::storage

    %% CI/CD Pipeline
    CI["GitHub Actions CI"]:::compute

    %% Environment Specification
    subgraph "Environment Specs"
        direction TB
        Req["requirements.txt"]:::content
        PostBuild["postBuild"]:::content
        SetupCfg["setup.cfg"]:::content
        EnvYml["notebooks/environment.yml"]:::content
    end

    %% Build Steps
    subgraph "Build Agents"
        direction TB
        NBConvert["Notebook Conversion"]:::compute
        AssetPipeline["Asset Pipeline (SCSS→CSS)"]:::compute
        JekyllEngine["Jekyll Engine"]:::compute
    end

    %% Static Assets
    AssetsCSS["assets/css/"]:::content
    LayoutsSrc -->|used by| JekyllEngine
    ConfigSrc -->|configures| JekyllEngine
    AssetsCSS -->|compiled by| AssetPipeline

    %% Hosting
    GitHubPages["GitHub Pages Hosting"]:::hosting

    %% End Users and External Services
    User["End Users (Students/Instructors)"]:::external
    NBViewer["NBViewer"]:::external
    Colab["Colab"]:::external

    %% Connections
    README & NotebooksSrc & CourseSrc & AssetsSrc & LayoutsSrc & ConfigSrc -->|push| GitHubRepo
    GitHubRepo -->|trigger| CI
    CI -->|loads| Req & PostBuild & SetupCfg & EnvYml
    CI -->|runs| NBConvert
    CI -->|runs| AssetPipeline
    CI -->|runs| JekyllEngine
    JekyllEngine -->|deploy| GitHubPages
    GitHubPages -->|serves site| User

    %% External links
    User -->|click badge| NBViewer
    User -->|click badge| Colab

    %% Click Events
    click README "https://github.com/iacopomasi/nlp/blob/main/README.md"
    click NotebooksSrc "https://github.com/iacopomasi/nlp/tree/main/notebooks/"
    click CourseSrc "https://github.com/iacopomasi/nlp/tree/main/course/"
    click AssetsSrc "https://github.com/iacopomasi/nlp/tree/main/assets/"
    click LayoutsSrc "https://github.com/iacopomasi/nlp/tree/main/_layouts/"
    click ConfigSrc "https://github.com/iacopomasi/nlp/blob/main/_config.yml"
    click GitHubRepo "https://github.com/iacopomasi/nlp/blob/main/."
    click CI "https://github.com/iacopomasi/nlp/blob/main/.github/workflows/notebook_release.yaml"
    click Req "https://github.com/iacopomasi/nlp/blob/main/requirements.txt"
    click PostBuild "https://github.com/iacopomasi/nlp/tree/main/postBuild"
    click SetupCfg "https://github.com/iacopomasi/nlp/blob/main/setup.cfg"
    click EnvYml "https://github.com/iacopomasi/nlp/blob/main/notebooks/environment.yml"
    click AssetsCSS "https://github.com/iacopomasi/nlp/tree/main/assets/css/"
    classDef compute fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef storage fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef content fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef hosting fill:#d9d2e9,stroke:#333,stroke-width:1px
    classDef external fill:#f4cccc,stroke:#333,stroke-width:1px
```
