# dpgalliance/publicgoods-form-opens-pr architecture

> Architecture diagram of the GitHub repository dpgalliance/publicgoods-form-opens-pr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dpgalliance/publicgoods-form-opens-pr
- Repository: https://github.com/dpgalliance/publicgoods-form-opens-pr

## Overview

##### Project type and purpose
- This is an event-driven integration tool (not a full-stack app) that connects a Google Form → Google Sheets → Google Apps Script pipeline to the GitHub REST API, automatically creating pull requests with JSON files built from form responses.

##### File structure
- Top-level files:
- code.gs → Google Apps Script entry point, installed as a spreadsheet trigger (“On form submit”)
- index.js → local Node.js version used for development/testing
- package.json / package-lock.json → NPM dependencies for index.js
- README.md, LICENSE, .gitignore
- No separate frontend or backend folders; the “front end” is hosted by Google Forms/Sheets, the “backend” is a serverless Apps Script function.

##### README insights
- Google Forms → spreadsheet responses
- Script Editor trigger runs function getHead()
- Four GitHub API steps: fetch master ref, create branch, commit JSON file, open PR
- Local dev mirrors Apps Script logic in index.js

##### Main components
a. User browser / Google Form (UI)
b. Google Sheets (response store)
c. Google Apps Script runtime (triggered function)
d. GitHub REST API (external service)
e. GitHub repository (DPGAlliance/publicgoods-candidates)
f. (Optional) Local Node.js environment for development/testing

##### Architectural patterns
- Event-driven pipeline (trigger → function chain)
- Serverless runtime (Apps Script)
- Callback/Promise cascade implementing API steps
- Local development shim (index.js) for easier debugging

##### Technologies and libraries
- Google Forms & Sheets (UI + data store)
- Google Apps Script (JavaScript on Google Cloud)
- Node.js (local dev)
- Axios/fetch or built-in UrlFetchApp for HTTP
- GitHub REST API v3

## Diagram (Mermaid)

```mermaid
graph TB
    %% Components
    Form["User Browser / Google Form"]:::cloud
    Sheets["Google Sheets (Response Store)"]:::db
    subgraph "Serverless Apps Script" 
        Apps["Apps Script Runtime\n(getHead, createBranch, commitFile, openPR)"]:::function
    end
    GitAPI["GitHub REST API"]:::external
    Repo["GitHub Repo\nDPGAlliance/publicgoods-candidates"]:::external
    Local["Local Node.js Env (Optional)"]:::optional

    %% Data Flow
    Form -->|Submits Form Data| Sheets
    Sheets -->|Trigger: onFormSubmit| Apps
    Apps -->|1: fetch master ref| GitAPI
    GitAPI -->|ref data| Apps
    Apps -->|2: create branch| GitAPI
    GitAPI -->|branch info| Apps
    Apps -->|3: commit JSON file| GitAPI
    GitAPI -->|commit sha| Apps
    Apps -->|4: open pull request| GitAPI
    GitAPI -->|PR created| Repo
    Local -.->|mirrors logic for dev/testing| Apps

    %% Click Events
    click Apps "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/code.gs"
    click Local "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/index.js"
    click package "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/package.json"
    click packlock "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/package-lock.json"
    click readme "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/README.md"
    click license "https://github.com/dpgalliance/publicgoods-form-opens-pr/tree/main/LICENSE"
    click gitignore "https://github.com/dpgalliance/publicgoods-form-opens-pr/blob/main/.gitignore"

    %% Legend
    subgraph "Legend"
        LC["Cloud Component"]:::cloud
        DB["Data Store"]:::db
        FN["Serverless Function"]:::function
        EX["External Service/Repo"]:::external
        OP["Optional / Dev"]:::optional
    end

    %% Styles
    classDef cloud fill:#bbdefb,stroke:#1e88e5,stroke-width:2px
    classDef db fill:#b3e5fc,stroke:#0288d1,stroke-width:2px
    classDef function fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
    classDef external fill:#e0e0e0,stroke:#757575,stroke-width:2px
    classDef optional fill:#ffffff,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 5 5
    class Form,LC cloud
    class Sheets,DB db
    class Apps,FN function
    class GitAPI,Repo,EX external
    class Local,OP optional
```
