# github/dev architecture

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

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

## Overview

##### Project type & purpose (from README + file tree)
**Type:** Product/experience description (no source code in this repo snapshot; only `README.md`).
**Purpose:** **github.dev** is a **browser-only, lightweight VS Code editing environment** for GitHub repos and PRs. Users can:
- Browse repositories and files
- Edit multiple files with VS Code-like UX
- Commit changes back to GitHub
Entry points:
- Press `.` on a repo/PR page
- Replace `github.com` with `github.dev` in the URL

##### User + Browser
- **User**
- **Browser (github.dev web app runtime)**

##### github.dev Web Application (runs entirely in browser)
Model it as a container with subcomponents:
- **UI Shell / Workbench** (VS Code-like layout: explorer, editor, SCM view)
- **Editor Engine** (VS Code Web / Monaco-like editor core)
- **Language Features** (syntax highlighting, IntelliSense-like capabilities)
- Often implemented via **Language Servers** (web/remote) or **in-browser providers**
- **Source Control Integration**
- Diff/patch generation
- Staging model
- Commit message UI
- **Filesystem Abstraction**
- Virtual FS representing repo contents
- Caching layer (IndexedDB / in-memory)
- **Auth / Session**
- OAuth / GitHub session cookie / token management
- **Networking Layer**
- Calls to GitHub APIs (REST/GraphQL)
- **Telemetry/Logging** (optional but common in such products)
- **Service Worker / Offline Cache** (optional but common for web IDE performance)

##### GitHub Platform (external services)
- **GitHub Web (github.com)**: the originating navigation context; redirects into github.dev
- **GitHub Authentication**: OAuth / SSO / session
- **GitHub API**
- **GitHub REST API** (contents, commits, trees, refs, PR endpoints)
- **GitHub GraphQL API** (repo/PR metadata, file trees, etc.)
- **Git Data/Storage**
- Repos, branches, commits, PR refs
- **(Optional) Artifact/CDN hosting**
- Static assets for github.dev served via CDN

##### On commit
- Create new blob/tree/commit through API, or use “create/update file” endpoints
- Update ref (branch) through API

##### Flow 4: PR context (if starting from PR)
- Fetch PR refs/patch context
- Possibly write commits to a branch/fork depending on permissions

- “HTTPS: REST/GraphQL”
- “OAuth redirect”
- “Static asset fetch”

##### Architectural patterns/design principles to highlight
Even conceptually, github.dev implies these patterns:

- **Client-heavy SPA architecture**: most UX and editing runs in-browser.
- **API-driven backend**: GitHub APIs are the system of record for repo data.
- **Virtualized filesystem**: repo content represented locally, synced via API calls.
- **Separation of concerns inside the client**:
- UI workbench vs editor engine vs SCM vs network/auth/caching.
- **Performance/caching**: local caching of file contents + lazy loading file trees.
- **Security constraints**: least-privilege auth, permission checks enforced by GitHub.

##### What you *cannot* claim from this repo snapshot (but can represent as assumptions)
- “Cache (e.g., IndexedDB)”
- “GitHub APIs (REST/GraphQL)”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors & entry points
    U["User"]:::actor
    GHWEB["GitHub Web (github.com)\nRepo/PR page"]:::external
    B["Browser\n(github.dev runtime)"]:::client

    U -->|"press '.' or edit URL"| GHWEB
    U -->|"navigates to github.dev"| B
    GHWEB -->|"redirect/navigation to github.dev"| B

    %% Delivery / edge
    CDN["Static Assets / CDN / Edge\n(HTML/JS/CSS for github.dev)"]:::delivery
    B -->|"1) static asset fetch"| CDN

    %% github.dev SPA (client-heavy)
    subgraph "github.dev Web App (SPA, runs entirely in browser)"
        SPA["App Bootstrap / Router"]:::client

        UI["UI Shell / Workbench\nExplorer • Editor • SCM"]:::client
        EDIT["Editor Engine\n(VS Code Web / Monaco-like)"]:::client

        subgraph "Editor Runtime Internals"
            LANG["Language Features\n(syntax • IntelliSense-like)\n(via providers / language servers)"]:::client
            WORKERS["Web Workers\n(parsing/indexing)"]:::client
        end

        SCM["Source Control Integration\nstaging • diff/patch • commit UI"]:::client
        NET["Networking Layer\n(HTTPS client)"]:::client
        AUTH["Auth / Session\n(OAuth / cookies / tokens)"]:::client
        SW["Service Worker / Offline Cache\n(optional)"]:::client
        TEL["Telemetry / Logging\n(optional)"]:::client

        VFS["Virtual File System\n(repo workspace view)"]:::client
        CACHE[("Local Cache\n(e.g., IndexedDB / memory)")]:::storage

        SPA --> UI
        SPA --> EDIT
        EDIT --> LANG
        LANG --> WORKERS

        UI -->|"open file / navigate tree"| VFS
        VFS <--> CACHE

        UI -->|"SCM view actions"| SCM
        SCM -->|"reads/writes workspace"| VFS

        SPA --> AUTH
        SPA --> NET
        SW -.->|"cache assets/requests"| CACHE
        TEL -.->|"async events"| NET
    end

    B -->|"runs"| SPA

    %% GitHub platform (system of record)
    subgraph "GitHub Platform (external dependencies)"
        GHAUTH["GitHub Authentication\nOAuth / SSO / Session"]:::external
        REST["GitHub REST API\n(contents • commits • trees • refs • PR endpoints)"]:::external
        GQL["GitHub GraphQL API\n(repo/PR metadata • file trees)"]:::external
        LIMIT["Rate limiting & abuse protection\n(constraints)"]:::external
        PERM["Permissions model\n(access checks enforced by GitHub)"]:::external

        REPO[("Git Data/Storage\nRepos • blobs • trees • commits • refs")]:::storage
        PRMETA[("PR metadata / refs\n(head/base • patches)")]:::storage

        REST --> REPO
        GQL --> PRMETA
        REST --> PRMETA
        PERM --> REST
        PERM --> GQL
        LIMIT --> REST
        LIMIT --> GQL
    end

    %% Key flows (numbered)
    AUTH -->|"2) OAuth redirect / token exchange"| GHAUTH
    NET -->|"2) HTTPS: REST/GraphQL requests"| REST
    NET -->|"2) HTTPS: REST/GraphQL requests"| GQL

    %% Browse & open files
    VFS -->|"3) request file/tree via NET"| NET
    REST -->|"file contents / trees"| NET
    GQL -->|"repo/PR metadata / tree info"| NET
    NET -->|"populate workspace view"| VFS

    %% Edit / diff / commit
    UI -->|"edit buffer"| EDIT
    EDIT -->|"document changes"| SCM
    SCM -->|"local diff computed"| UI
    SCM -->|"4) write commits/refs (API-driven)"| NET
    NET -->|"create blobs/trees/commits/refs"| REST
    NET -->|"refresh state"| GQL

    %% PR context (optional)
    UI -.->|"if PR context"| NET
    NET -.->|"fetch PR refs/patch context"| REST
    NET -.->|"fetch PR metadata"| GQL

    %% Notes / principles
    NOTE1["Pattern: Client-heavy SPA\nGitHub APIs are the backend/system-of-record"]:::note
    NOTE2["Virtualized FS + caching\nlazy-load trees + cache contents"]:::note
    NOTE3["Security: least-privilege auth\npermissions enforced by GitHub"]:::note

    SPA -.-> NOTE1
    VFS -.-> NOTE2
    AUTH -.-> NOTE3
    PERM -.-> NOTE3

    %% Click events (from component mapping)
    click SPA "https://github.com/github/dev/blob/main/README.md"
    click NOTE1 "https://github.com/github/dev/blob/main/README.md"

    %% Styles
    classDef actor fill:#f7f7f7,stroke:#444,stroke-width:1px,color:#111
    classDef client fill:#cfe8ff,stroke:#1b4f8a,stroke-width:1px,color:#0b1b2b
    classDef external fill:#d7f5d7,stroke:#1f7a3b,stroke-width:1px,color:#0b2b14
    classDef delivery fill:#e6e6e6,stroke:#666,stroke-width:1px,color:#111
    classDef storage fill:#fff2cc,stroke:#a67c00,stroke-width:1px,color:#2b1f00
    classDef note fill:#fff6bf,stroke:#b59a00,stroke-width:1px,color:#2b2500
```
