# github/platform-samples architecture

> Architecture diagram of the GitHub repository github/platform-samples, 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/platform-samples
- Repository: https://github.com/github/platform-samples

## Overview

##### Project type and purpose
- This is a “platform-samples” repository, not a single running system. It’s a curated collection of sample projects demonstrating how to call GitHub’s REST API in multiple languages, run GraphQL queries, write webhook consumers, pre-receive hooks, helper scripts, and SQL reports.
- Its sole purpose is to act as a learning/reference library, organized by use case (API, GraphQL, hooks, scripts, SQL, Microsoft Graph) and by language or sub-type.

##### File structure
- Top-level directories, each independent:
- .github: CI/workflow definitions (CodeQL, PR combining).
- api: REST API samples, subdivided by language (bash, golang, groovy, java, javascript, powershell, python, ruby, scala).
- app: example GitHub App (Ruby).
- graphql: GraphQL query samples, plus a small demo client for Enterprise.
- hooks: incoming-webhook and pre-receive-hook consumers, subdivided by language.
- microsoft-graph-api: sample docs for Azure AD OIDC integration.
- pre-receive-hooks: shell scripts for GitHub Enterprise policy enforcement.
- scripts: various repository-maintenance scripts (bash/PowerShell).
- sql: SQL query scripts for Enterprise Server reporting (audit, metrics, security).
- There is no single “build” or “runtime” artifact; each directory is self-contained.

##### Key insights from README
- The README outlines six major categories: api, graphql, hooks, microsoft-graph-api, pre-receive-hooks, scripts, sql.
- It encourages community contributions, so the architecture must be extensible by dropping new directories under the right category.

##### How to represent this
- a. Main components (modules):
- CI/CD: .github workflows
- API samples (bash, golang, groovy, java, js, ps, py, ruby, scala)
- GitHub App example (app/ruby/app-issue-creator)
- GraphQL samples & demo UI
- Webhook consumers (hooks/python, hooks/ruby, hooks/jenkins)
- Pre-receive hooks (shell scripts)
- Maintenance scripts (scripts/*)
- SQL reports (sql/audit, sql/metrics, sql/security)
- Microsoft Graph API docs
External systems:
- GitHub REST API
- GitHub GraphQL API
- GitHub Webhooks endpoint
- GitHub Enterprise server (pre-receive hooks & SQL against its DB)
- Azure AD (Microsoft Graph samples)

- b. Relationships and interactions:
- CI/CD workflows → run static analysis, tests across samples
- REST samples → HTTP calls → GitHub REST API
- GraphQL samples → HTTP calls → GitHub GraphQL API → optional demo UI
- Webhook consumers ← GitHub Events → HTTP POST → user’s webhook URL
- Pre-receive hooks → invoked by GitHub Enterprise server on git push
- Scripts → CLI utilities run locally against target repos/hosts
- SQL reports → executed against Enterprise Server database

- c. Architectural patterns and design principles:
- Modular folder-per-language or per-guideline
- Self-contained example: each subfolder has its own dependencies and README
- CI as a thin “enforcer” layer, independent of samples
- Clear separation by use-case (API vs. GraphQL vs. Hooks vs. SQL vs. Scripts)

- d. Key technologies and frameworks:
- Shell/Bash, PowerShell
- Go, Java, JavaScript (Node.js), Python, Ruby, Groovy, Scala
- Sinatra (Ruby HTTP servers), Flask (Python), Express or bare Node CLI
- GitHub’s REST API, GraphQL API
- Jenkins for hook pipelines
- SQLite/MySQL/Postgres for SQL report execution (depending on Enterprise DB)
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI Workflows
    subgraph ".github/workflows"
        CI_CodeQL["codeql.yml"]:::ci
        CI_Combine["combine-prs.yml"]:::ci
    end

    %% API Samples
    subgraph "API Samples"
        API_Bash["bash"]:::sample
        API_Go["golang"]:::sample
        API_Groovy["groovy"]:::sample
        API_Java["java"]:::sample
        API_JS["javascript"]:::sample
        API_PS["powershell"]:::sample
        API_Py["python"]:::sample
        API_Rb["ruby"]:::sample
        API_Scala["scala"]:::sample
    end

    %% GitHub App Example
    subgraph "GitHub App Example"
        App_Ruby["app-issue-creator (Ruby)"]:::sample
    end

    %% GraphQL Samples
    subgraph "GraphQL Samples"
        GraphQL["graphql"]:::sample
    end

    %% Webhook Consumers
    subgraph "Webhook Consumers"
        Hooks_Jenkins["jenkins"]:::sample
        Hooks_Python["python"]:::sample
        Hooks_Ruby["ruby"]:::sample
    end

    %% Pre-receive Hooks
    subgraph "Pre-receive Hooks"
        PR_Hooks["shell scripts"]:::sample
    end

    %% Maintenance Scripts
    subgraph "Maintenance Scripts"
        Scripts["scripts"]:::sample
    end

    %% SQL Reports
    subgraph "SQL Reports"
        SQL_Audit["audit"]:::sample
        SQL_Metrics["metrics"]:::sample
        SQL_Security["security"]:::sample
    end

    %% Microsoft Graph Docs
    subgraph "Microsoft Graph Docs"
        MSGraph["microsoft-graph-api"]:::doc
    end

    %% External Services
    GitHubREST["GitHub REST API"]:::external
    GitHubGraphQL["GitHub GraphQL API"]:::external
    GitHubWebhooks["GitHub Webhooks"]:::external
    GHEnterprise["GitHub Enterprise Server"]:::external
    EnterpriseDB["Enterprise DB"]:::external
    AzureAD["Microsoft Graph API / Azure AD"]:::external

    %% CI to Samples
    CI_CodeQL -->|lint/test/build| API_Bash
    CI_CodeQL -->|lint/test/build| API_Go
    CI_CodeQL -->|lint/test/build| API_Groovy
    CI_CodeQL -->|lint/test/build| API_Java
    CI_CodeQL -->|lint/test/build| API_JS
    CI_CodeQL -->|lint/test/build| API_PS
    CI_CodeQL -->|lint/test/build| API_Py
    CI_CodeQL -->|lint/test/build| API_Rb
    CI_CodeQL -->|lint/test/build| API_Scala
    CI_CodeQL -->|lint/test/build| App_Ruby
    CI_CodeQL -->|lint/test/build| GraphQL
    CI_CodeQL -->|lint/test/build| Hooks_Jenkins
    CI_CodeQL -->|lint/test/build| Hooks_Python
    CI_CodeQL -->|lint/test/build| Hooks_Ruby
    CI_CodeQL -->|lint/test/build| PR_Hooks
    CI_CodeQL -->|lint/test/build| Scripts
    CI_CodeQL -->|lint/test/build| SQL_Audit
    CI_CodeQL -->|lint/test/build| SQL_Metrics
    CI_CodeQL -->|lint/test/build| SQL_Security
    CI_CodeQL -->|lint/test/build| MSGraph

    CI_Combine -->|combine PRs| API_Bash
    CI_Combine -->|combine PRs| API_Go
    CI_Combine -->|combine PRs| API_Groovy
    CI_Combine -->|combine PRs| API_Java
    CI_Combine -->|combine PRs| API_JS
    CI_Combine -->|combine PRs| API_PS
    CI_Combine -->|combine PRs| API_Py
    CI_Combine -->|combine PRs| API_Rb
    CI_Combine -->|combine PRs| API_Scala
    CI_Combine -->|combine PRs| App_Ruby
    CI_Combine -->|combine PRs| GraphQL
    CI_Combine -->|combine PRs| Hooks_Jenkins
    CI_Combine -->|combine PRs| Hooks_Python
    CI_Combine -->|combine PRs| Hooks_Ruby
    CI_Combine -->|combine PRs| PR_Hooks
    CI_Combine -->|combine PRs| Scripts
    CI_Combine -->|combine PRs| SQL_Audit
    CI_Combine -->|combine PRs| SQL_Metrics
    CI_Combine -->|combine PRs| SQL_Security
    CI_Combine -->|combine PRs| MSGraph

    %% Sample interactions
    API_Bash -->|HTTP| GitHubREST
    API_Go -->|HTTP| GitHubREST
    API_Groovy -->|HTTP| GitHubREST
    API_Java -->|HTTP| GitHubREST
    API_JS -->|HTTP| GitHubREST
    API_PS -->|HTTP| GitHubREST
    API_Py -->|HTTP| GitHubREST
    API_Rb -->|HTTP| GitHubREST
    API_Scala -->|HTTP| GitHubREST
    App_Ruby -->|HTTP| GitHubREST
    GraphQL -->|HTTP| GitHubGraphQL
    GraphQL -->|UI Demo| GraphQL
    Hooks_Jenkins -->|POST| GitHubWebhooks
    Hooks_Python -->|POST| GitHubWebhooks
    Hooks_Ruby -->|POST| GitHubWebhooks
    PR_Hooks -->|invoke| GHEnterprise
    SQL_Audit -->|SQL| EnterpriseDB
    SQL_Metrics -->|SQL| EnterpriseDB
    SQL_Security -->|SQL| EnterpriseDB
    Scripts -->|CLI| GHEnterprise
    MSGraph -->|HTTP| AzureAD

    %% Click Events
    click CI_CodeQL "https://github.com/github/platform-samples/blob/master/.github/workflows/codeql.yml"
    click CI_Combine "https://github.com/github/platform-samples/blob/master/.github/workflows/combine-prs.yml"
    click API_Bash "https://github.com/github/platform-samples/tree/master/api/bash/"
    click API_Go "https://github.com/github/platform-samples/blob/master/api/golang/basics-of-authentication/server.go"
    click API_Groovy "https://github.com/github/platform-samples/tree/master/api/groovy/"
    click API_Java "https://github.com/github/platform-samples/blob/master/api/java/deployment/src/main/java/com/github/DeployServer.java"
    click API_JS "https://github.com/github/platform-samples/blob/master/api/javascript/es2015-nodejs/libs/GitHubClient.js"
    click API_PS "https://github.com/github/platform-samples/blob/master/api/powershell/invite_members_to_org.ps1"
    click API_Py "https://github.com/github/platform-samples/blob/master/api/python/building-a-ci-server/server.py"
    click API_Rb "https://github.com/github/platform-samples/blob/master/api/ruby/basics-of-authentication/server.rb"
    click API_Scala "https://github.com/github/platform-samples/blob/master/api/scala.with.sbt/octocat-samples/src/main/scala/github/Client.scala"
    click App_Ruby "https://github.com/github/platform-samples/blob/master/app/ruby/app-issue-creator/server.rb"
    click GraphQL "https://github.com/github/platform-samples/tree/master/graphql/bin/run-query"
    click Hooks_Jenkins "https://github.com/github/platform-samples/tree/master/hooks/jenkins/jira-issue-validator/Jenkinsfile"
    click Hooks_Python "https://github.com/github/platform-samples/blob/master/hooks/python/flask-github-webhooks/webhooks.py"
    click Hooks_Ruby "https://github.com/github/platform-samples/blob/master/hooks/ruby/delete-repository-event/app.rb"
    click PR_Hooks "https://github.com/github/platform-samples/blob/master/pre-receive-hooks/always_reject.sh"
    click Scripts "https://github.com/github/platform-samples/tree/master/scripts/"
    click SQL_Audit "https://github.com/github/platform-samples/tree/master/sql/audit/"
    click SQL_Metrics "https://github.com/github/platform-samples/tree/master/sql/metrics/"
    click SQL_Security "https://github.com/github/platform-samples/tree/master/sql/security/"
    click MSGraph "https://github.com/github/platform-samples/blob/master/microsoft-graph-api/EMU-OIDC-tokenlifetime-policy.md"

    %% Styles
    classDef ci fill:#ddd,stroke:#666,stroke-width:1px;
    classDef sample fill:#bbf,stroke:#333,stroke-width:1px;
    classDef external fill:#dfd,stroke:#090,stroke-width:1px;
    classDef doc fill:#fff,stroke:#999,stroke-dasharray:5 5,stroke-width:1px;
```
