# dpgalliance/publicgoods-candidates architecture

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

## Overview

##### Project Type and Purpose
- This is an open-source data repository and pipeline for managing nominations of Digital Public Goods (DPGs).
- It hosts JSON “content” (nominee metadata, reviews, archived items), transformation scripts, documentation, and CI workflows.
- The output feeds a static site or downstream DPG application that publishes the list of approved and candidate public goods.

##### Key Architectural Components
a. Data Stores (Content Layer)
- /nominees – JSON files for each candidate project
- /digitalpublicgoods – JSON metadata for approved DPGs
- /archive, /excluded-nominees – JSON for historical and excluded items
- /reviews – reviewer feedback JSON
- nominee-schema.json, screening-schema.json – JSON Schema for validation

b. Processing Engine (Transformation Layer)
- /scripts – Node.js scripts (csvToJson.js, migrate-*.js, api.js, etc.) that:
– validate JSON against schemas
– normalize, merge, order fields
– generate or update JSON outputs
- package.json, package-lock.json – define dependencies and scripts

c. CI/CD Pipelines
- .github/workflows/*.yml – GitHub Actions that:
– run tests and validation on pull requests
– execute transformation scripts automatically
– deploy updated content to the public site (e.g., GitHub Pages or external endpoint)

d. Documentation & Policies
- /docs – development guides, overview, bug reporting
- /help-center – content guidelines, license policies, privacy practices
- CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE – process and governance

e. External Services
- digitalpublicgoods.net (static site or web application) – consumes generated JSON data
- bug-reporter.vercel.app – issue intake
- GitHub – source hosting, Actions, Pages

##### Relationships and Data Flows
- Authors commit JSON content to the repo.
- On push or pull request, GitHub Actions validate and run scripts.
- Scripts produce normalized JSON and may push built artifacts.
- CI then publishes the updated dataset to the DPG website or API endpoint.
- End users browse the static site or API to explore DPGs.

##### Architectural Patterns and Principles
- “Content as Code”: treating JSON data and schemas like source code under version control.
- “CI-driven pipeline”: automated validation, transformation, publication.
- Separation of concerns: distinct layers for data (JSON), processing (scripts), and deployment (CI).
- Schema-first design: enforce data quality via JSON Schema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and Events
    Author(["Author"]):::external
    GitHubPush(["GitHub Push / PR"]):::ci

    %% Content Layer
    subgraph "Content Layer"
        Nominees["/nominees JSON Store"]:::data
        DigitalPublicGoods["/digitalpublicgoods JSON Store"]:::data
        Archive["/archive JSON Store"]:::data
        ExcludedNominees["/excluded-nominees JSON Store"]:::data
        Reviews["/reviews JSON Store"]:::data
        Schemas["nominee-schema.json<br/>screening-schema.json"]:::data
    end

    %% Processing Engine
    subgraph "Processing Engine"
        Scripts["Transformation Scripts<br/>(Node.js)"]:::process
        Dependencies["package.json<br/>package-lock.json"]:::process
    end

    %% CI/CD Layer
    subgraph "CI/CD (GitHub Actions)"
        Workflows[".github/workflows<br/>main.yml<br/>auto.yml"]:::ci
    end

    %% Documentation & Policies
    subgraph "Documentation & Policies"
        Docs["/docs"]:::doc
        HelpCenter["/help-center"]:::doc
        Governance["CONTRIBUTING.md<br/>CODE_OF_CONDUCT.md<br/>LICENSE"]:::doc
    end

    %% External Services
    subgraph "External Services"
        DPGWebsite["DigitalPublicGoods.net<br/>(Static Site/API)"]:::external
        BugReporter["bug-reporter.vercel.app"]:::external
    end

    %% Data Flows
    Author -->|commits JSON content| Nominees
    Author -->|commits JSON content| DigitalPublicGoods
    Author -->|commits JSON content| Archive
    Author -->|commits JSON content| ExcludedNominees
    Author -->|commits JSON content| Reviews
    Author -->|updates schemas| Schemas

    GitHubPush -.->|trigger| Workflows
    Workflows -->|invoke scripts| Scripts
    Scripts -->|read JSON & schemas| Nominees
    Scripts -->|read JSON & schemas| DigitalPublicGoods
    Scripts -->|read JSON & schemas| Archive
    Scripts -->|read JSON & schemas| ExcludedNominees
    Scripts -->|read JSON & schemas| Reviews
    Scripts -->|use schemas| Schemas
    Scripts -->|use dependencies| Dependencies
    Scripts -->|produce normalized JSON| Workflows
    Workflows -->|deploy artifacts| DPGWebsite
    Workflows -->|notify issues| BugReporter

    %% Documentation links
    Author --> Docs
    Author --> HelpCenter
    Author --> Governance

    %% Click Events for component mapping
    click Nominees "https://github.com/dpgalliance/publicgoods-candidates/tree/main/nominees/"
    click DigitalPublicGoods "https://github.com/dpgalliance/publicgoods-candidates/tree/main/digitalpublicgoods/"
    click Archive "https://github.com/dpgalliance/publicgoods-candidates/tree/main/archive/"
    click ExcludedNominees "https://github.com/dpgalliance/publicgoods-candidates/tree/main/excluded-nominees/"
    click Reviews "https://github.com/dpgalliance/publicgoods-candidates/tree/main/reviews/"
    click Schemas "https://github.com/dpgalliance/publicgoods-candidates/blob/main/nominee-schema.json"
    click Scripts "https://github.com/dpgalliance/publicgoods-candidates/tree/main/scripts/"
    click Dependencies "https://github.com/dpgalliance/publicgoods-candidates/blob/main/package.json"
    click Workflows "https://github.com/dpgalliance/publicgoods-candidates/blob/main/.github/workflows/main.yml"
    click Docs "https://github.com/dpgalliance/publicgoods-candidates/tree/main/docs/"
    click HelpCenter "https://github.com/dpgalliance/publicgoods-candidates/tree/main/help-center/"
    click Governance "https://github.com/dpgalliance/publicgoods-candidates/blob/main/CONTRIBUTING.md"

    %% Styling
    classDef data fill:#cce5ff,stroke:#004085,color:#004085;
    classDef process fill:#d4edda,stroke:#155724,color:#155724;
    classDef ci fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef doc fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
```
