# github/explore architecture

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

- Interactive diagram: https://gitdiagram.com/github/explore
- Repository: https://github.com/github/explore

## Overview

##### Project type and purpose
- This is a content-driven static site (a “Jamstack” site) that powers GitHub’s community-curated Topics and Collections pages.
- It uses Markdown files under `topics/` and `collections/` plus Jekyll/Liquid templates to generate a static website.

##### File structure
- Top-level content:
- `topics/` (folder full of `<topic>/index.md`)
- `collections/` (folder full of `<collection>/index.md`)
- Site engine/configuration:
- `_config.yml` – Jekyll configuration
- `feed.json.liquid` – Liquid template for feeds
- `Rakefile` – build tasks
- Tooling/development:
- `Gemfile`/`Gemfile.lock` – Ruby dependencies (Jekyll, plugins, rubocop)
- `.github/workflows/` – CI workflows (jekyll_build, lint, test, etc.)
- `test/` – Ruby‐based lint/format checks
- Deployment:
- `CNAME` – custom domain for GitHub Pages
- GitHub Pages picks up the `main` (or `gh-pages`) branch

##### README for additional insights
- Describes that tests/lint run via GitHub Actions and locally with `bundle exec rubocop`.
- Mentions that content is under CC-BY-4.0 and contributions follow CONTRIBUTING.md.

A. Developer Environment
- Code editor + local Ruby/Bundler
- Markdown content + Jekyll templates
- `bundle exec jekyll serve` for local preview
B. GitHub Repository (central source)
- Stores all Markdown, config, templates, CI definitions
C. Continuous Integration (GitHub Actions)
1. Lint & tests (`lint.yml`, `test.yml`)
2. Build (`jekyll_build.yml`) – runs Jekyll to generate HTML
D. Artifact Deployment
- Upon successful build, GitHub Pages deploys `_site/` to the public endpoint
E. Hosting (GitHub Pages/CDN)
- Static HTML/CSS/JS served via GitHub’s CDN under the custom domain in `CNAME`

##### Architectural patterns & design principles
- Jamstack static site pattern:
- Content as data (Markdown)
- Build time rendering (Jekyll)
- CDN deployment (GitHub Pages)
- Clear separation of concerns:
- Content (topics/collections)
- Presentation (templates, `_config.yml`)
- Build pipeline (Rake tasks, GitHub Actions)
- Enforcement (Rubocop, tests)
- Extensibility point: add new `topics/<name>/index.md` or collections, and push changes

##### Technologies, frameworks, libraries
- Ruby & Bundler (dependency management)
- Jekyll (static site generator) + Liquid templates
- GitHub Actions (CI/CD workflows)
- Rubocop + custom tests (linting/formatting)
- GitHub Pages (hosting)

##### Be very detailed
- Workflows under `.github/workflows` as separate CI steps.
- Dependency on `Gemfile` and external plugins.
- That `CNAME` config maps to a custom domain.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        DevTools["Code Editor\n+ Ruby/Bundler"]:::dev
        DevPreview["Local Preview\nbundle exec jekyll serve"]:::dev
    end

    %% GitHub Repository
    subgraph "GitHub Repository (Source)" 
        direction TB
        Repo["Git Repository"]:::repo
        Topics["Content - Topics"]:::repo
        Collections["Content - Collections"]:::repo
        ConfigYML["_config.yml"]:::repo
        FeedTemplate["feed.json.liquid"]:::repo
        RakefileNode["Rakefile"]:::repo
        GemfileNode["Gemfile"]:::repo
        GemfileLock["Gemfile.lock"]:::repo
        RubyVersion[".ruby-version"]:::repo
        RuboCopConfig[".rubocop.yml"]:::repo
        Templates["_explore_collections/"]:::repo
        ContribGuide["CONTRIBUTING.md"]:::repo
        CodeConduct["CODE_OF_CONDUCT.md"]:::repo
        Readme["README.md"]:::repo
        License["LICENSE.txt"]:::repo
        CNAMEFile["CNAME"]:::repo
        GitIgnore[".gitignore"]:::repo
        PRTemplate[".github/PULL_REQUEST_TEMPLATE.md"]:::repo
        CodeOwners["CODEOWNERS"]:::repo
    end

    %% CI Pipeline
    subgraph "Continuous Integration (GitHub Actions)" 
        direction TB
        LintCI["Lint Workflow"]:::ci
        TestCI["Test Workflow"]:::ci
        CollectionsRenamesCI["Collections Renames Checker"]:::ci
        ConflictCI["Conflict Detection"]:::ci
        StaleCI["Stale Issue Manager"]:::ci
        TopicBotCI["Topic Commenter Bot"]:::ci
        BuildCI["Jekyll Build Workflow"]:::ci
    end

    %% Build Engine
    subgraph "Build Engine (Jekyll)" 
        direction TB
        Jekyll["Jekyll Build Server\n(Ruby, Liquid)"]:::build
        Artifacts["_site/ (Static Assets)"]:::build
    end

    %% Hosting
    subgraph "Hosting & Delivery" 
        direction TB
        Pages["GitHub Pages/CDN"]:::host
        EndUsers["Users\n(HTTP GET)"]:::host
    end

    %% Connections
    DevTools --> DevPreview
    DevPreview -->|push PR| Repo
    Repo -->|triggers workflows| LintCI
    Repo -->|triggers workflows| TestCI
    Repo -->|triggers workflows| CollectionsRenamesCI
    Repo -->|triggers workflows| ConflictCI
    Repo -->|triggers workflows| StaleCI
    Repo -->|triggers workflows| TopicBotCI
    Repo -->|triggers workflows| BuildCI

    LintCI -->|"runs RuboCop"| Repo
    TestCI -->|"runs tests"| Repo
    BuildCI -->|"runs Jekyll"| Jekyll

    Jekyll -->|"generates HTML"| Artifacts
    Artifacts -->|deploy| Pages
    Pages -->|serves static site| EndUsers

    %% Click Events
    click Topics "https://github.com/github/explore/tree/main/topics/"
    click Collections "https://github.com/github/explore/tree/main/collections/"
    click ConfigYML "https://github.com/github/explore/blob/main/_config.yml"
    click FeedTemplate "https://github.com/github/explore/blob/main/feed.json.liquid"
    click RakefileNode "https://github.com/github/explore/tree/main/Rakefile"
    click GemfileNode "https://github.com/github/explore/tree/main/Gemfile"
    click GemfileLock "https://github.com/github/explore/blob/main/Gemfile.lock"
    click RubyVersion "https://github.com/github/explore/blob/main/.ruby-version"
    click RuboCopConfig "https://github.com/github/explore/blob/main/.rubocop.yml"
    click Templates "https://github.com/github/explore/tree/main/_explore_collections/"
    click BuildCI "https://github.com/github/explore/blob/main/.github/workflows/jekyll_build.yml"
    click LintCI "https://github.com/github/explore/blob/main/.github/workflows/lint.yml"
    click TestCI "https://github.com/github/explore/blob/main/.github/workflows/test.yml"
    click CollectionsRenamesCI "https://github.com/github/explore/blob/main/.github/workflows/collections-renames.yml"
    click ConflictCI "https://github.com/github/explore/blob/main/.github/workflows/conflict.yml"
    click StaleCI "https://github.com/github/explore/blob/main/.github/workflows/stale.yml"
    click TopicBotCI "https://github.com/github/explore/blob/main/.github/workflows/topic-commenter.yml"
    click test/collections_test.rb "https://github.com/github/explore/blob/main/test/collections_test.rb"
    click test/collections_test_helper.rb "https://github.com/github/explore/blob/main/test/collections_test_helper.rb"
    click test/topics_test.rb "https://github.com/github/explore/blob/main/test/topics_test.rb"
    click test/topics_test_helper.rb "https://github.com/github/explore/blob/main/test/topics_test_helper.rb"
    click test/test_helper.rb "https://github.com/github/explore/blob/main/test/test_helper.rb"
    click ContribGuide "https://github.com/github/explore/blob/main/CONTRIBUTING.md"
    click CodeConduct "https://github.com/github/explore/blob/main/CODE_OF_CONDUCT.md"
    click Readme "https://github.com/github/explore/blob/main/README.md"
    click License "https://github.com/github/explore/blob/main/LICENSE.txt"
    click CNAMEFile "https://github.com/github/explore/tree/main/CNAME"
    click GitIgnore "https://github.com/github/explore/blob/main/.gitignore"
    click PRTemplate "https://github.com/github/explore/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    click CodeOwners "https://github.com/github/explore/tree/main/CODEOWNERS"

    %% Styles
    classDef dev fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef repo fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1;
    classDef ci fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef build fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef host fill:#F3E5F5,stroke:#4A148C,color:#4A148C;
```
