# near/near-discovery architecture

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

- Interactive diagram: https://gitdiagram.com/near/near-discovery
- Repository: https://github.com/near/near-discovery

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (React) called “NEAR Discovery (BOS)”.
- It provides a UI for exploring and interacting with NEAR blockchain tools, components, and communities, with serverless API endpoints for newsletter subscription, search, etc.

##### Main components
a. Client (Browser/SPA)
- Next.js pages and React components under src/pages and src/components
- Layouts, UI widgets, forms, wallet selector, VM embed, research wizard, etc.
- Custom hooks & client-side stores (Zustand) for state management
b. Next.js Server (Node.js runtime)
- Server-side rendering for public pages (_app.tsx, _document.tsx)
- API Routes under src/pages/api (newsletter, search)
- Middleware (src/middleware.ts) for routing/auth guards
c. External Services
- NEAR blockchain network (via BOS Loader, web3modal)
- VM Gateway (local or linked VM for component development)
- 3rd-party APIs: Algolia (search), CatalogSearchApi, Zendesk, PostHog/Google Analytics, Newsletter service
- CDN for public assets (fonts, images, pwa.js, manifest.json)
d. Build & Deployment
- Package manager: pnpm, config: next.config.js, tsconfig.json, environment (.env)
- CI/CD pipelines defined in .github/workflows (tests, release, promote, devrel)

##### Relationships and data flows
- Client ↔ Next.js Server:
- Browser requests pages → SSR/SSG or client-side hydration
- Client code calls API routes (newsletter, search) via HTTP
- Next.js Server ↔ External Services:
- API handlers communicate with Algolia, catalog search, newsletter backend
- Server and client both call NEAR blockchain through BOS Loader and VM Gateway
- Client ↔ External services (direct integrations):
- In-browser wallet interactions (web3modal) → NEAR network
- Analytics scripts → PostHog/Google Analytics
- CI/CD ↔ Repository:
- GitHub Actions triggers on push/PR to build, test, deploy

##### Architectural patterns & principles
- MVC-style:
- Views = React pages & components
- Controllers = API route handlers
- Models = data schemas or direct calls to external APIs (no internal DB)
- Modular component design:
- Reusable UI primitives in src/components and src/components/tools
- Hooks encapsulate side effects, data fetching, event tracking
- Serverless architecture:
- API Routes as serverless functions
- No self-hosted database
- Environment-driven configuration:
- .env for NEXT_PUBLIC_NETWORK_ID to switch blockchain network

- Related components in containers (e.g., “Next.js App”, “src/components”)
- Call out architectural patterns (modular UI, serverless functions) in side notes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        ReactPages["React Pages\n(src/pages/*.tsx)"]:::client
        Components["React Components\n(src/components)"]:::client
        Hooks["Custom Hooks\n(src/hooks)"]:::client
        Stores["Zustand Stores\n(src/stores)"]:::client
    end

    %% Server Layer
    subgraph "Server/Edge Layer"
        direction TB
        SSRApp["SSR/SSG Entry Points\n(_app.tsx, _document.tsx)"]:::server
        Middleware["Middleware\n(src/middleware.ts)"]:::server
        subgraph "API Routes"
            NewsletterAPI["Newsletter API\n(src/pages/api/newsletter/index.ts)"]:::server
            SearchAPI["Search API\n(src/pages/api/search.ts)"]:::server
        end
    end

    %% External Services Layer
    subgraph "External Services Layer"
        direction TB
        NEAR["NEAR Blockchain Network"]:::external
        BOSLoader["BOS Loader Integration"]:::external
        VMGateway["VM Gateway"]:::external
        subgraph "3rd-Party APIs"
            Algolia["Algolia Search API"]:::external
            CatalogSearch["Catalog Search API"]:::external
            Zendesk["Zendesk API"]:::external
            AnalyticsPH["PostHog Analytics"]:::external
            AnalyticsGA["Google Analytics"]:::external
            NewsletterService["Newsletter Service"]:::external
            CDN["CDN (public assets)"]:::external
        end
    end

    %% CI/CD Layer
    subgraph "CI/CD & Config"
        direction TB
        GitHubActions["GitHub Actions\n(.github/workflows)"]:::ci
        EnvConfig["Config Files\n(next.config.js,\ntsconfig.json,\n.env.example)"]:::ci
        Package["Package Manager\n(package.json, pnpm-lock.yaml)"]:::ci
    end

    %% Connections
    ReactPages -->|"Hydration/SSR"| SSRApp
    Components --> SSRApp
    ReactPages -->|"Calls"/newsletter & search| NewsletterAPI
    ReactPages -->|"Calls"/newsletter & search| SearchAPI
    SSRApp -->|Renders Pages| ReactPages
    Middleware -->|"Guards Routing"| SSRApp
    NewsletterAPI -->|"POST /api/newsletter"| NewsletterService
    SearchAPI -->|"GET /api/search"| Algolia
    NewsletterAPI -->|"GET Catalog Data"| CatalogSearch
    SSRApp -->|"Uses BOS Loader Hook"| BOSLoader
    Components -->|"Embeds VM"| VMGateway
    Components -->|"Uses Wallet Selector"| NEAR
    Hooks -->|"useBosLoaderInitializer"| BOSLoader
    Hooks -->|"useAnalytics"| AnalyticsPH & AnalyticsGA
    Stores -->|"bos-loader store"| BOSLoader
    Stores -->|"vm store"| VMGateway
    SSRApp -->|"Middleware"| Middleware

    ReactPages -->|"Direct Wallet Interaction"| NEAR
    ReactPages -->|"Analytics Scripts"| AnalyticsPH & AnalyticsGA

    GitHubActions -->|"Triggers on Push/PR"| Package
    GitHubActions -->|"Runs Build/Deploy"| SSRApp
    GitHubActions -->|"Runs Tests"| ReactPages & Components

    EnvConfig -->|"Configures Network"| NEAR

    CDN -->|"Serves Assets"| ReactPages

    %% Click Events
    click ReactPages "https://github.com/near/near-discovery/tree/develop/src/pages"
    click Components "https://github.com/near/near-discovery/tree/develop/src/components"
    click Hooks "https://github.com/near/near-discovery/tree/develop/src/hooks"
    click Stores "https://github.com/near/near-discovery/tree/develop/src/stores"
    click SSRApp "https://github.com/near/near-discovery/blob/develop/src/pages/_app.tsx"
    click Middleware "https://github.com/near/near-discovery/blob/develop/src/middleware.ts"
    click NewsletterAPI "https://github.com/near/near-discovery/blob/develop/src/pages/api/newsletter/index.ts"
    click SearchAPI "https://github.com/near/near-discovery/blob/develop/src/pages/api/search.ts"
    click BOSLoader "https://github.com/near/near-discovery/blob/develop/src/components/BosLoaderBanner.tsx"
    click Hooks "https://github.com/near/near-discovery/blob/develop/src/hooks/useBosLoaderInitializer.ts"
    click Stores "https://github.com/near/near-discovery/blob/develop/src/stores/bos-loader.ts"
    click VMGateway "https://github.com/near/near-discovery/blob/develop/src/components/vm/VM.tsx"
    click Stores "https://github.com/near/near-discovery/blob/develop/src/stores/vm.ts"
    click Components "https://github.com/near/near-discovery/blob/develop/src/components/wallet-selector/WalletSelector.ts"
    click Components "https://github.com/near/near-discovery/blob/develop/src/components/wallet-selector/web3modal.js"
    click Algolia "https://github.com/near/near-discovery/blob/develop/src/utils/algoliaSearchApi.ts"
    click CatalogSearch "https://github.com/near/near-discovery/blob/develop/src/utils/catalogSearchApi.ts"
    click Zendesk "https://github.com/near/near-discovery/blob/develop/src/utils/zendesk.ts"
    click AnalyticsPH "https://github.com/near/near-discovery/blob/develop/src/utils/analytics-posthog.tsx"
    click AnalyticsGA "https://github.com/near/near-discovery/blob/develop/src/utils/analytics.ts"
    click EnvConfig "https://github.com/near/near-discovery/blob/develop/next.config.js"
    click EnvConfig "https://github.com/near/near-discovery/blob/develop/tsconfig.json"
    click EnvConfig "https://github.com/near/near-discovery/blob/develop/.env.example"
    click Package "https://github.com/near/near-discovery/blob/develop/package.json"
    click CDN "https://github.com/near/near-discovery/blob/develop/public/manifest.json"
    click GitHubActions "https://github.com/near/near-discovery/blob/develop/.github/workflows/continuous-integration-workflow.yml"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef server fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef external fill:#FFF4D6,stroke:#FF8C00,color:#FF8C00;
    classDef ci fill:#E0E0E0,stroke:#666666,color:#333333;
```
