# ethereum/esp-website architecture

> Architecture diagram of the GitHub repository ethereum/esp-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethereum/esp-website
- Repository: https://github.com/ethereum/esp-website

## Overview

##### Project type and purpose
- This is a Next.js–based full-stack website for the Ethereum Ecosystem Support Program (ESP). It serves public marketing pages (SSG/SSR), handles a variety of grant application forms, and integrates with external systems (Salesforce API, Google Sheets, hCaptcha).

##### File structure
- Top-level directories:
- public – static assets (fonts, images, docs)
- src/pages – React pages + Next.js API routes under pages/api
- src/components – reusable UI and form components organized into UI, forms, layouts
- src/middlewares – server-side middleware for parsing multipart/form-data, sanitizing, captcha validation
- src/hooks, src/utils, src/theme – custom hooks, utilities, Chakra UI theme customizations
- Config files: next.config.js, netlify.toml (deployment), tsconfig.json, ESLint/Prettier
- Build script and dependencies in package.json

##### README for additional insights
- Confirms Next.js + TypeScript + Chakra UI + react-hook-form + Framer Motion
- Describes Salesforce integration via JSforce in API routes
- Describes Google Sheets → CSV → JSON parsing at build time for static “Latest Grantees” page
- Mentions hCaptcha testing keys, environment variable config

##### Main components & interactions (to show
a. Frontend (Browser + Next.js)
- Static assets (public) served by CDN/Netlify
- React pages (src/pages/*.tsx) using Chakra UI components and layouts
- Client-side form handling via react-hook-form, Framer Motion animations
b. API Layer (Serverless functions on Netlify)
- Next.js API routes in src/pages/api/*.ts
- Each route imports middlewares (multipartyParse, sanitizeFields, verifyCaptcha)
- Business logic for each form – builds formData, calls JSforce to insert/update Salesforce Lead/Objects
c. External Services
- Salesforce REST API (via JSforce) – storing form submissions
- hCaptcha – captcha verification in middleware
- Google Sheets (public CSV) – fetched at build time via getStaticProps to render static pages
- Netlify – CI/CD, hosting, function runtime
d. Build & Data-fetching
- Static generation (`getStaticProps`) for content pages including Latest Grantees
- Server-side rendering (SSR) for dynamic pages or incremental builds

##### Architectural patterns & design principles
- Layered architecture: Presentation (components & pages) → Business logic (API handlers + middlewares) → Data services (Salesforce, Google Sheets)
- Separation of concerns:
- UI vs. Layout vs. Forms vs. Data-fetching
- Middlewares handle cross-cutting concerns (parsing, sanitization, captcha)
- Next.js conventions:
- File-based routing for pages and API routes
- SSG/SSR mix for performance & SEO

##### Elements
- Legible labels (component name + core technology)
- Annotations for build-time vs. runtime processes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser & Next.js)" 
        direction TB
        Browser["Browser"]:::external
        StaticAssets["Static Assets<br/>(public)"]:::frontend
        NextPages["Next.js Pages<br/>(TSX, Chakra UI, SSG/SSR)"]:::frontend
        UIComponents["UI Components<br/>(Chakra UI, Framer Motion)"]:::frontend
        FormComponents["Form Components<br/>(react-hook-form)"]:::frontend
        LayoutComponents["Layout Components"]:::frontend
        CustomHooks["Custom Hooks"]:::frontend
        Theme["Theme Customizations"]:::frontend
        Utils["Utility Functions"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Serverless Functions)" 
        direction TB
        APIRoutes["Next.js API Routes<br/>(Node, JSforce)"]:::backend
        MMParse["Middleware: multipartyParse"]:::backend
        MMSanitize["Middleware: sanitizeFields"]:::backend
        MMCaptcha["Middleware: verifyCaptcha"]:::backend
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        Salesforce["Salesforce REST API"]:::external
        hCaptcha["hCaptcha API"]:::external
        GoogleSheets["Google Sheets CSV"]:::external
        Netlify["Netlify CI/CD & Hosting"]:::external
    end

    %% Build Process
    subgraph "Build & Data-fetching"
        direction TB
        NetlifyBuild["Netlify Build"]:::external
        GSFetch["Fetch CSV via getStaticProps"]:::frontend
    end

    %% Connections
    Browser -->|"requests pages"| NextPages
    Browser -->|"fetches assets"| StaticAssets
    NextPages -->|"uses"| UIComponents
    NextPages -->|"uses"| FormComponents
    NextPages -->|"wraps with"| LayoutComponents
    NextPages -->|"calls hooks"| CustomHooks
    NextPages -->|"applies theme"| Theme
    NextPages -->|"calls utils"| Utils

    NextPages -->|"API calls"| APIRoutes
    APIRoutes -->|"uses"| MMParse
    APIRoutes -->|"uses"| MMSanitize
    APIRoutes -->|"uses"| MMCaptcha
    MMCaptcha -->|"verifies captcha"| hCaptcha
    APIRoutes -->|"JSforce calls"| Salesforce

    NetlifyBuild -->|"build-time"| GSFetch
    GSFetch -->|"reads CSV"| GoogleSheets
    GSFetch -->|"generates static pages"| NextPages

    NetlifyBuild -->|"deploy functions"| APIRoutes
    NetlifyBuild -->|"deploy static assets"| StaticAssets

    %% Click Events
    click StaticAssets "https://github.com/ethereum/esp-website/tree/master/public/"
    click NextPages "https://github.com/ethereum/esp-website/blob/master/src/pages/**/*.tsx"
    click UIComponents "https://github.com/ethereum/esp-website/tree/master/src/components/UI/"
    click FormComponents "https://github.com/ethereum/esp-website/tree/master/src/components/forms/"
    click LayoutComponents "https://github.com/ethereum/esp-website/tree/master/src/components/layout/"
    click CustomHooks "https://github.com/ethereum/esp-website/tree/master/src/hooks/"
    click Theme "https://github.com/ethereum/esp-website/tree/master/src/theme/"
    click Utils "https://github.com/ethereum/esp-website/tree/master/src/utils/"
    click APIRoutes "https://github.com/ethereum/esp-website/blob/master/src/pages/api/*.ts"
    click MMParse "https://github.com/ethereum/esp-website/blob/master/src/middlewares/multipartyParse.ts"
    click MMSanitize "https://github.com/ethereum/esp-website/blob/master/src/middlewares/sanitizeFields.ts"
    click MMCaptcha "https://github.com/ethereum/esp-website/blob/master/src/middlewares/verifyCaptcha.ts"
    click Salesforce "https://github.com/ethereum/esp-website/blob/master/src/pages/api/project-grants.ts"
    click GSFetch "https://github.com/ethereum/esp-website/tree/master/src/utils/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#027BFF,color:#000
    classDef backend fill:#DFF5D0,stroke:#2E7D32,color:#000
    classDef external fill:#FFE5B4,stroke:#FF8C00,color:#000
```
