# btholt/next-course-starter architecture

> Architecture diagram of the GitHub repository btholt/next-course-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/btholt/next-course-starter
- Repository: https://github.com/btholt/next-course-starter

## Overview

##### Project Type and Purpose
- This is a Next.js–based static-site generator tailored for educational courses. It reads Markdown lessons, course metadata (course.json & meta.json), and frontmatter, then uses Next.js’s SSG (getStaticProps / getStaticPaths) to build a fully client-hydrated React site. It also provides build-time utilities (CSV generation, ChatGPT-powered SEO metadata) and a GitHub Actions workflow for deployment to GitHub Pages.

##### High-Level File-Structure Analysis
- “context/”: React Context providers for global state (course info, header data).
- “pages/”: Next.js page files, incl. dynamic routes under pages/lessons/[section]/[slug].js, plus _app.js.
- “lessons/”: Organized Markdown content per section (01-…/A-… .md), with optional meta.json for section overrides.
- “data/” & “csv/” & “summary/”: Build-time scripts for generating CSV metadata and SEO summaries via ChatGPT.
- “public/”: Static assets (images, favicon).
- “styles/”: CSS variables & component styles.
- Config files: next.config.js, course.json, .github/workflows/next.yaml, package.json.

##### Key Insights from README
- Emphasizes: file-system routing, Markdown → React transformation, frontmatter usage, theming via CSS variables, CSV and SEO scripts, and automated GitHub Pages deployment via GitHub Actions.

##### Diagramming the Architecture
- Developer Workstation
- Next.js Build Pipeline
- Markdown Content Store (lessons/, course.json, meta.json)
- Data & Utility Scripts (csv/index.js, summary/)
- React Components & Context Providers
- Static Asset Store (public/images, styles/)
- Generated Output (/.next, CSV file)
- GitHub Actions CI/CD
- GitHub Pages Hosting
- End-User Browser

- Developer → (npm run build) → Next.js Build Pipeline
- Build Pipeline reads → Markdown Content Store & course.json
- Build Pipeline invokes → Data & Utility Scripts → produces CSV + enriched frontmatter
- Build Pipeline compiles → React Components + Context + styles → static HTML/CSS/JS
- Compiled output pushed → GitHub Repo → GitHub Actions → publishes → GitHub Pages Hosting
- End-User Browser → HTTP GET → Hosted Static Files → Hydrates React on client

c. Architectural Patterns & Principles:
- Static Site Generation (SSG) via Next.js
- File-system routing for dynamic lesson pages
- Separation of concerns: content vs. presentation vs. data-processing scripts
- Context API for global state (course metadata)
- Build-time extensibility (CSV / SEO augmenters)

d. Technologies & Frameworks to annotate:
- Next.js (SSG, dynamic routes)
- React (Components, Context API)
- .js (code syntax highlighting theme)
- Node.js scripts for CSV & ChatGPT SEO (OpenAI API)
- GitHub Actions (.github/workflows/next.yaml)
- GitHub Pages (static hosting)
- CSS variables & custom styles

##### Be Detailed but Not Overcomplicated
- Layer 1: Developer → Build Pipeline
- Layer 2: Source Content & Scripts → SSG Engine → Static Output
- Layer 3: CI/CD → Hosting
- Layer 4: End-User Interaction

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Developer
    Developer["Developer Workstation"]:::build

    %% Layer 2: Build-Time
    subgraph "Next.js Build Pipeline" 
        direction TB
        Config["next.config.js"]:::build
        App["pages/_app.js"]:::build
        IndexPage["pages/index.js"]:::build
        LessonPage["pages/lessons/[section]/[slug].js"]:::build
    end

    subgraph "Markdown Content Store"
        direction TB
        Lessons01["A-intro.md"]:::build
        Lessons02A["A-first-lesson.md"]:::build
        Lessons02B["B-second-lesson.md"]:::build
        Meta02["meta.json (section 02)"]:::build
        Lessons03A["A-css.md"]:::build
        Lessons03B["B-javascript.md"]:::build
        Lessons03C["C-npm.md"]:::build
        Meta03["meta.json (section 03)"]:::build
        CourseMeta["course.json"]:::build
    end

    subgraph "Data & Utility Scripts"
        direction TB
        CSVGen["csv/index.js"]:::build
        SEOSum["summary/index.js"]:::build
        Prompt["summary/getPrompt.js"]:::build
    end

    subgraph "React Components & Context"
        direction TB
        HeaderComp["components/header.js"]:::runtime
        FooterComp["components/footer.js"]:::runtime
        LayoutComp["components/layout.js"]:::runtime
        IconsComp["components/themeicons.js"]:::runtime
        BlueskyComp["components/bluesky.js"]:::runtime
        CornerComp["components/corner.js"]:::runtime
        GitHubComp["components/github.js"]:::runtime
        TwitterComp["components/twitter.js"]:::runtime
        LinkedInComp["components/linkedin.js"]:::runtime
        CourseCtx["context/courseInfoContext.js"]:::runtime
        HeaderCtx["context/headerContext.js"]:::runtime
    end

    subgraph "Build-Time Data Helpers"
        direction TB
        CourseHelper["data/course.js"]:::build
        LessonHelper["data/lesson.js"]:::build
        CopyCode["data/copyCode.js"]:::build
    end

    Developer -->|"npm run build"| Config
    Config -->|reads| Lessons01
    Config -->|reads| Lessons02A
    Config -->|reads| Lessons02B
    Config -->|reads| Meta02
    Config -->|reads| Lessons03A
    Config -->|reads| Lessons03B
    Config -->|reads| Lessons03C
    Config -->|reads| Meta03
    Config -->|reads| CourseMeta
    Config -->|invokes| CSVGen
    Config -->|invokes| SEOSum
    SEOSum -->|uses| Prompt
    Config -->|uses| CourseHelper
    Config -->|uses| LessonHelper
    Config -->|uses| CopyCode
    Config -->|compiles| HeaderComp
    Config -->|compiles| FooterComp
    Config -->|compiles| LayoutComp
    Config -->|compiles| IconsComp
    Config -->|compiles| BlueskyComp
    Config -->|compiles| CornerComp
    Config -->|compiles| GitHubComp
    Config -->|compiles| TwitterComp
    Config -->|compiles| LinkedInComp
    Config -->|wires| CourseCtx
    Config -->|wires| HeaderCtx

    subgraph "SSG Engine"
        direction TB
        StaticHTML["Static HTML/CSS/JS"]:::build
        CSVOutput["Generated CSV"]:::build
    end

    Config -->|generates| StaticHTML
    CSVGen -->|outputs| CSVOutput

    %% Layer 3: CI/CD
    subgraph "CI/CD"
        direction TB
        GitHubActions[".github/workflows/next.yaml"]:::external
    end

    StaticHTML -->|push to repo| GitHubActions
    CSVOutput -->|push to repo| GitHubActions
    GitHubActions -->|deploy| GitHubPages

    %% Layer 4: Hosting & Run-Time
    subgraph "GitHub Pages Hosting"
        direction TB
        Pages["GitHub Pages"]:::external
    end

    subgraph "End-User Browser"
        direction TB
        Browser["Web Browser"]:::runtime
    end

    Pages -->|serves| Browser
    Browser -->|hydrates React| StaticHTML

    %% Click Events
    click Config "https://github.com/btholt/next-course-starter/blob/main/next.config.js"
    click App "https://github.com/btholt/next-course-starter/blob/main/pages/_app.js"
    click IndexPage "https://github.com/btholt/next-course-starter/blob/main/pages/index.js"
    click LessonPage "https://github.com/btholt/next-course-starter/blob/main/pages/lessons/[section]/[slug].js"
    click Lessons01 "https://github.com/btholt/next-course-starter/blob/main/lessons/01-the-first-section/A-intro.md"
    click Lessons02A "https://github.com/btholt/next-course-starter/blob/main/lessons/02-a-second-section/A-first-lesson.md"
    click Lessons02B "https://github.com/btholt/next-course-starter/blob/main/lessons/02-a-second-section/B-second-lesson.md"
    click Meta02 "https://github.com/btholt/next-course-starter/blob/main/lessons/02-a-second-section/meta.json"
    click Lessons03A "https://github.com/btholt/next-course-starter/blob/main/lessons/03-thoughts-on-js-and-css/A-css.md"
    click Lessons03B "https://github.com/btholt/next-course-starter/blob/main/lessons/03-thoughts-on-js-and-css/B-javascript.md"
    click Lessons03C "https://github.com/btholt/next-course-starter/blob/main/lessons/03-thoughts-on-js-and-css/C-npm.md"
    click Meta03 "https://github.com/btholt/next-course-starter/blob/main/lessons/03-thoughts-on-js-and-css/meta.json"
    click CourseMeta "https://github.com/btholt/next-course-starter/blob/main/course.json"
    click CSVGen "https://github.com/btholt/next-course-starter/blob/main/csv/index.js"
    click SEOSum "https://github.com/btholt/next-course-starter/blob/main/summary/index.js"
    click Prompt "https://github.com/btholt/next-course-starter/blob/main/summary/getPrompt.js"
    click HeaderComp "https://github.com/btholt/next-course-starter/blob/main/components/header.js"
    click FooterComp "https://github.com/btholt/next-course-starter/blob/main/components/footer.js"
    click LayoutComp "https://github.com/btholt/next-course-starter/blob/main/components/layout.js"
    click IconsComp "https://github.com/btholt/next-course-starter/blob/main/components/themeicons.js"
    click BlueskyComp "https://github.com/btholt/next-course-starter/blob/main/components/bluesky.js"
    click CornerComp "https://github.com/btholt/next-course-starter/blob/main/components/corner.js"
    click GitHubComp "https://github.com/btholt/next-course-starter/blob/main/components/github.js"
    click TwitterComp "https://github.com/btholt/next-course-starter/blob/main/components/twitter.js"
    click LinkedInComp "https://github.com/btholt/next-course-starter/blob/main/components/linkedin.js"
    click CourseCtx "https://github.com/btholt/next-course-starter/blob/main/context/courseInfoContext.js"
    click HeaderCtx "https://github.com/btholt/next-course-starter/blob/main/context/headerContext.js"
    click CourseHelper "https://github.com/btholt/next-course-starter/blob/main/data/course.js"
    click LessonHelper "https://github.com/btholt/next-course-starter/blob/main/data/lesson.js"
    click CopyCode "https://github.com/btholt/next-course-starter/blob/main/data/copyCode.js"
    click GitHubActions "https://github.com/btholt/next-course-starter/blob/main/.github/workflows/next.yaml"

    %% Styles
    classDef build fill:#D0E8FF,stroke:#004080,color:#000
    classDef runtime fill:#E0F8E0,stroke:#006400,color:#000
    classDef external fill:#FFE8B0,stroke:#804000,color:#000
```
