# swcarpentry/git-novice architecture

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

- Interactive diagram: https://gitdiagram.com/swcarpentry/git-novice
- Repository: https://github.com/swcarpentry/git-novice

## Overview

##### Project Type and Purpose
- The project is an educational lesson for Git novices created by the Carpentries. It’s designed to teach version control concepts using Git.
- Its content is organized as lesson materials (episodes, instructor notes, learners’ guides, and profiles) along with configurations for automated workflows and static site generation.

##### Analyzing the File Structure
- Key Directories and Files:
- Root-level files such as .editorconfig, .gitignore, LICENSE.md, CONTRIBUTING.md, and config.yaml provide standard repository configuration and governance.
- The episodes folder contains markdown files (e.g., 01-basics.md, 02-setup.md, etc.) that comprise the core instructional content.
- The instructors, learners, and profiles directories hold supplementary materials such as instructor notes, setup instructions for learners, and reference profiles.
- The site directory (with its own README.md) and config.yaml point to static site generation and possible lesson rendering components, which are hinted at in the README’s reference to “sandpaper” (the lesson template documentation).
- The .github/workflows directory houses numerous GitHub Actions YAML files which demonstrate that CI/CD pipelines (for pre-checks, managing PRs, updating caches, etc.) are heavily integrated into the project. These workflows help automate building, testing, and possibly deploying the generated teaching material.

##### Key Architectural Components
a. Lesson Content Repository:
- Components: episodes (core lesson content), instructors, learners, and profiles directories.
- Relationship: These markdown-based content pieces interact to form a complete lesson package, each catering to different audiences (learner vs instructor).

b. CI/CD Pipeline (GitHub Workflows):
- Components: All the YAML files under the .github/workflows directory.

c. Static Site Generation/Rendering:
- Components: The 'site' directory and related configuration (config.yaml).
- Relationship: This part of the system takes the lesson content from the episodes and renders it as a static site (as indicated by the rendered version at swcarpentry.github.io/git-novice/).

d. External Integration:
- Components: Communication and collaboration tools such as the Slack channel (as per the badges in the README).
- Relationship: The external community and collaboration tools are connected to the project via links and API calls (if automated notifications or integrations are in place).

##### Architectural Patterns and Design Principles
- Clear separation of concerns — content (episodes, instructors, learners), site generation, and continuous integration (workflows) are maintained as distinct components.
- Emphasis on automated processes via GitHub Actions ensures consistent lesson quality and streamlined contributions.
- The structure follows a modular design that permits independent updating of lesson content and supporting material.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Lesson Content Repository
    subgraph "Lesson Content Repository"
        E["Episodes"]:::content
        I["Instructors"]:::content
        L["Learners"]:::content
        P["Profiles"]:::content
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        W["GitHub Workflows"]:::automation
    end

    %% Static Site Renderer
    subgraph "Static Site Renderer"
        S["Site"]:::static
        C["Configuration"]:::static
    end

    %% External Integrations
    EI["External Integrations"]:::integration

    %% Connections
    E -->|"triggers"| W
    W -->|"deploys"| S
    C -->|"configures"| S
    W -->|"notifies"| EI

    %% Click Events
    click E "https://github.com/swcarpentry/git-novice/tree/main//episodes"
    click I "https://github.com/swcarpentry/git-novice/tree/main//instructors"
    click L "https://github.com/swcarpentry/git-novice/tree/main//learners"
    click P "https://github.com/swcarpentry/git-novice/tree/main//profiles"
    click W "https://github.com/swcarpentry/git-novice/tree/main//github/workflows"
    click S "https://github.com/swcarpentry/git-novice/tree/main//site"
    click C "https://github.com/swcarpentry/git-novice/blob/main//config.yaml"
    click EI "https://github.com/swcarpentry/git-novice/blob/main//README.md"

    %% Styles
    classDef content fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef automation fill:#D1E8FF,stroke:#333,stroke-width:2px;
    classDef static fill:#C8FACC,stroke:#333,stroke-width:2px;
    classDef integration fill:#FCD1D1,stroke:#333,stroke-width:2px;
```
