# dpgalliance/publicgoods-submission architecture

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

## Overview

##### Project Type and Purpose
- This is a Next.js–based web application (“webapp”) that renders and serves a dynamic, JSON-schema–driven submission form.
- Its goal is to collect nomination data for the Digital Public Goods Registry via a custom form UI (using Data Driven Forms), hosted and server-rendered on Vercel.

##### File-Structure Analysis
- Top level:
- .gitmodules – indicates use of one or more submodules (e.g., shared schema repo)
- README.md, LICENSE, CODE_OF_CONDUCT.md, BUGS.md – project docs and governance
- webapp/ – Next.js application containing pages/, components/, API routes, public/ assets, and likely a schemas/ folder
- pages/ – React pages (including form page and API routes under pages/api/)
- components/ – form fields, layout, wrappers
- schemas/ – schema.js JSON definitions for Data Driven Forms
- next.config.js, package.json, tsconfig.json – build and deployment configs

##### README Insights
- Core stack: Next.js (SSR/SSG + API routes) and Data Driven Forms (for runtime form rendering)
- Deployment: Vercel (leverages serverless functions for API endpoints and global CDN for static assets)
- Schema-driven: The entire form is driven by a JSON schema (no hard-coded form fields)

##### Main Components
a. Client Tier
- Browser / User Agent
- Static assets served (JS bundles, CSS, images) via Vercel CDN
b. Presentation & Application Tier
- Next.js Frontend (React)
- Server-side rendering (SSR) or static-site generation (SSG) for initial form page
- Client-side hydration for interactive form wizard
- Data Driven Forms Renderer
- Consumes JSON schema (schemas/schema.js)
- Renders form fields dynamically
- Next.js API Routes (serverless functions)
- Endpoint to receive form submissions (POST /api/submit)
c. Data & Integration Tier
- JSON Schema Store (in-repo or submodule)
- External Registry Service or Database (where nominations are persisted)
- May call a third-party API or write to a storage layer (not shown in repo, but include a placeholder)
d. Infrastructure & DevOps
- Vercel Platform
- Global CDN for static assets
- Serverless function hosting for API routes
- Git + Git Submodule (for shared schema)

##### Relationships & Data Flows
1. User ➔ Browser requests “/submission”
2. Browser ➔ Vercel CDN edge ➔ Next.js serverless (SSR) or static asset
3. Next.js ➔ Loads JSON schema (local file or submodule)
4. Browser renders dynamic form via Data Driven Forms
5. User fills form & submits ➔ POST to /api/submit (Next.js API route)
6. API route processes payload ➔ Forwards to external registry API or persistence layer
7. API returns success/failure ➔ Browser displays confirmation

##### Architectural Patterns & Design Principles
- Hybrid SSR/SSG: balances SEO and dynamic capabilities
- Schema-driven UI: single source of truth for form definition
- Serverless functions: on-demand backend without dedicated servers
- Monorepo/submodule for schema reuse

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        UserAgent["Browser / User Agent"]:::client
        SubmissionPage["Submission Form Page<br>(SSR/SSG)"]:::frontend
        StaticAssets["Static Assets<br>(JS, CSS, images)"]:::assets
    end

    %% Presentation & Application Tier
    subgraph "Presentation & Application Tier"
        direction TB
        NextJS["Next.js Frontend<br>(SSR/SSG & CSR)"]:::frontend
        FormRenderer["Data Driven Forms Renderer"]:::component
        APIRoute["pages/api/submit handler"]:::api
    end

    %% Data & Integration Tier
    subgraph "Data & Integration Tier"
        direction TB
        SchemaStore["JSON Schema Store"]:::data
        ExternalRegistry["External Registry Service / DB"]:::cloud
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        direction TB
        Vercel["Vercel Platform"]:::cloud
        GitModules["Git Submodule<br>(shared schema)"]:::data
        NextConfig["next.config.js"]:::config
        PackageJSON["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
        Docs["Project Docs & Governance"]:::docs
    end

    %% Connections
    UserAgent -->|"GET /submission"| Vercel
    Vercel -->|"edge cache"| StaticAssets
    Vercel -->|"SSR/SSG request"| NextJS
    NextJS -->|"loads JSON schema"| SchemaStore
    NextJS -->|"renders page"| SubmissionPage
    SubmissionPage -->|"client hydration"| FormRenderer
    FormRenderer -->|"renders dynamic form"| UserAgent
    UserAgent -->|"POST JSON payload"| APIRoute
    APIRoute -->|"forwards nomination data"| ExternalRegistry
    ExternalRegistry -->|"response"| APIRoute
    APIRoute -->|"success/failure"| UserAgent

    Vercel --> NextJS
    Vercel --> APIRoute
    GitModules --- SchemaStore

    %% Click Events
    click NextJS "https://github.com/dpgalliance/publicgoods-submission/tree/main/webapp/pages"
    click SubmissionPage "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/pages/submission.js"
    click FormRenderer "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/components/FormRenderer.jsx"
    click SchemaStore "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/schemas/schema.js"
    click APIRoute "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/pages/api/submit.js"
    click StaticAssets "https://github.com/dpgalliance/publicgoods-submission/tree/main/webapp/public"
    click NextConfig "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/next.config.js"
    click PackageJSON "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/package.json"
    click TSConfig "https://github.com/dpgalliance/publicgoods-submission/blob/main/webapp/tsconfig.json"
    click GitModules "https://github.com/dpgalliance/publicgoods-submission/blob/main/.gitmodules"
    click Docs "https://github.com/dpgalliance/publicgoods-submission/blob/main/README.md"

    %% Styles
    classDef client fill:#a2d2ff,stroke:#0165a5,color:#000
    classDef frontend fill:#ffcad4,stroke:#ff0054,color:#000
    classDef component fill:#bde0fe,stroke:#0077b6,color:#000
    classDef api fill:#caf0f8,stroke:#0096c7,color:#000
    classDef data fill:#ffe5b4,stroke:#ff9900,color:#000
    classDef cloud fill:#e0e0e0,stroke:#717171,color:#000
    classDef assets fill:#d8f3dc,stroke:#2d6a4f,color:#000
    classDef config fill:#f0efeb,stroke:#a8a8a8,color:#000
    classDef docs fill:#f7d6bf,stroke:#d35400,color:#000
```
