# dpgalliance/publicgoods-validate architecture

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

## Overview

##### Project type and purpose
- From the README and file tree, this is a single‐page “webapp” crowdsourcing form for validating open‐source projects against the Digital Public Goods Standard.
- The root repo simply holds a Git submodule called “webapp,” so all application code lives there. There is no separate “backend” in this repo—this is essentially a front‐end‐first project, likely calling out to external services or serverless endpoints for storage and business logic.

##### File structure
- Top level:
– .gitmodules → declares “webapp” as a Git submodule
– README.md, LICENSE, CODE_OF_CONDUCT.md → project metadata
– webapp/ → entire application code
- Look for any Netlify/Vercel, GitHub Actions, or Docker config to understand how it’s built and deployed.

##### README for additional insights
- Live app URL (https://validate.digitalpublicgoods.net) hints at a static‐hosting or serverless deployment (Netlify, Vercel, Cloudflare Pages).
- No explicit “backend” instructions here—means the front end likely calls third‐party or remotely hosted endpoints.

a. Main components
1. Developer environment & code repo (Git + webapp submodule)
2. CI/CD pipeline (GitHub Actions, Netlify/Vercel build step)
3. Static hosting / CDN (serving the SPA)
4. Browser (SPA running React/Vue/Angular)
5. External APIs / serverless functions (receiving form submissions, validating against Digital Public Goods Standard API, storing results)
6. Data store (e.g., managed database or GitHub Issues / Airtable / Firestore)
7. Third‐party integrations (e.g., authentication via GitHub OAuth, email/webhooks)

b. Relationships & interactions
– Developer pushes to GitHub → CI/CD builds webapp → deploys to CDN
– End user opens URL → CDN serves SPA → user fills form → SPA calls API endpoint (serverless or external)
– API endpoint fetches Standard definitions, applies business rules, writes review data to store → optionally triggers notifications
– Admin / dashboard client can query the data store or GitHub repo for results

c. Architectural patterns & principles
– SPA + serverless “microservices” for business logic
– Git submodule to isolate “webapp” code in its own repo
– Static hosting + CDN for global performance
– External managed services to reduce operational overhead

d. Key technologies & frameworks (tailor after you inspect webapp/)
– Frontend: React (create-react-app) or Vue CLI
– Deployment: Netlify/Vercel or GitHub Pages
– CI: GitHub Actions (build, test, deploy)
– Serverless: Netlify Functions / AWS Lambda / Vercel Serverless Functions
– Data: Firebase/Firestore, Airtable, or a SQL/NoSQL database
– Auth & integrations: GitHub OAuth APIs, email service, webhooks

## Diagram (Mermaid)

```mermaid
graph TB
  %% Root Repository
  subgraph "Root Repository"
    GitModules[".gitmodules"]:::repo
    GitModules --> WebappSubmodule["webapp submodule"]:::repo
  end

  %% Webapp Repository
  subgraph "Webapp Repository"
    PackageJSON["package.json"]:::repo
    PublicAssets["public/ (static assets & HTML)"]:::frontend
    SrcCode["src/ (SPA source code)"]:::frontend
    Functions["functions/ (serverless/API functions)"]:::api
    EnvConfig[".env"]:::repo
    Scripts["scripts/"]:::repo
    CIWorkflows[".github/workflows/ (CI/CD pipelines)"]:::repo
    HostingConfig["netlify.toml / vercel.json"]:::repo

    WebappSubmodule --> PackageJSON
    WebappSubmodule --> PublicAssets
    WebappSubmodule --> SrcCode
    WebappSubmodule --> Functions
    WebappSubmodule --> EnvConfig
    WebappSubmodule --> Scripts
    WebappSubmodule --> CIWorkflows
    WebappSubmodule --> HostingConfig
  end

  %% CI/CD Pipeline
  subgraph "CI/CD Pipeline"
    GitHubActions["GitHub Actions"]:::external
    NetlifyDeploy["Netlify/Vercel Build & Deploy"]:::external
  end

  %% Cloud Infrastructure
  subgraph "Cloud Infrastructure"
    CDN["CDN (Netlify/Vercel)"]:::external
    Browser["Browser (SPA)"]:::frontend
    ReviewAPI["Review Submission Function"]:::api
    Database["Database (Firestore/Airtable)"]:::data
    AuthService["GitHub OAuth"]:::external
    NotificationSvc["Email/Webhooks"]:::external
  end

  %% Relationships
  PackageJSON & SrcCode & PublicAssets -->|"source code"| GitHubActions
  CIWorkflows -->|triggers| GitHubActions
  GitHubActions -->|build & deploy| NetlifyDeploy
  HostingConfig -->|configures| NetlifyDeploy
  NetlifyDeploy -->|deploys SPA| CDN

  Browser -->|fetch SPA| CDN
  Browser -->|submit form| ReviewAPI
  ReviewAPI -->|uses code from| Functions
  ReviewAPI -->|read/write data| Database
  ReviewAPI -->|authenticate users| AuthService
  ReviewAPI -->|send notifications| NotificationSvc

  %% Click Events
  click GitModules "https://github.com/dpgalliance/publicgoods-validate/blob/main//.gitmodules"
  click PackageJSON "https://github.com/dpgalliance/publicgoods-validate/blob/main//webapp/package.json"
  click PublicAssets "https://github.com/dpgalliance/publicgoods-validate/tree/main//webapp/public/"
  click SrcCode "https://github.com/dpgalliance/publicgoods-validate/tree/main//webapp/src/"
  click Functions "https://github.com/dpgalliance/publicgoods-validate/tree/main//webapp/functions/"
  click EnvConfig "https://github.com/dpgalliance/publicgoods-validate/blob/main//webapp/.env"
  click Scripts "https://github.com/dpgalliance/publicgoods-validate/tree/main//webapp/scripts/"
  click CIWorkflows "https://github.com/dpgalliance/publicgoods-validate/tree/main//webapp/.github/workflows/"
  click HostingConfig "https://github.com/dpgalliance/publicgoods-validate/blob/main//webapp/netlify.toml"
  click HostingConfig "https://github.com/dpgalliance/publicgoods-validate/blob/main//webapp/vercel.json"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
  classDef api fill:#fff3cd,stroke:#ffcc00,color:#000;
  classDef data fill:#d4edda,stroke:#28a745,color:#000;
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
  classDef repo fill:#f8d7da,stroke:#dc3545,color:#000;
```
