How near/near-discovery works
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