How gainforest/green_globe_2 works
Project Type & Purpose
• This is a full-stack Next.js (App Router) web application specialized in interactive geospatial mapping and project overviews.
• On the front end it renders map views (with dynamic layers, satellite imagery, shapefile drawing) and project-specific overlays (biodiversity data, community donations, etc.).
• On the back end it exposes Next.js API routes to manage authentication (NextAuth), projects, users, and tiling data, and connects to external services (BigQuery, Planet Satellite Tiles, Mapbox, WalletConnect / SIWE).
File Structure & Architectural Patterns
• src/app holds the Next.js app router with two main route groups:
• (map-routes) – all pages/components related to map display, overlays, shapefile import, drawing.
• (non-map-routes) – authentication boundary, “My Projects”, main layout, sidebar.
• API layer under src/app/api implements serverless endpoints for auth (/auth), BigQuery queries (/bigquery.ts), tile routing (/planet-tiles), project & user CRUD.
• Shared UI components in src/components/ui and domain widgets in components/ are reused across pages.
• Global state management lives in component-level stores (e.g. LayersOverlay/store, ProjectOverlay/store) and feature hooks (src/hooks, _features/navigation).
• Configuration and utility functions are factored into src/config, src/lib, and src/utils.
Key External Services & Technologies
• Next.js App Router (React + SSR/ISR)
• NextAuth for authentication & session management
• BigQuery as the primary data store for project/tree observations
• Planet Tiles API for satellite imagery
• Mapbox GL (via custom map hooks) for vector/raster map rendering
• WalletConnect/SIWE for Web3 wallet authentication
• Vercel (or similar) hosting for serverless functions and CDN
• Presentation Layer:
• Browser/Client
• React Components (Map, Overlays, Sidebar, AuthBoundary)
• Next.js Server:
• App Router (page.tsx + layout.tsx)
• API Routes (Auth, Users, Projects, BigQuery, Planet-tiles)
• State & Business Logic:
• Client-side stores & hooks (LayersOverlay/store, navigation hooks)
• Server-side logic in API handlers
• Data Layer & External Services:
• BigQuery (project data)
• Planet Tiles Service
• Mapbox Tiles / Styles
• NextAuth Adapter (session store, optional database)
• WalletConnect / SIWE provider
• Client sends HTTP(S) requests to Next.js pages (SSR/CSR) and API endpoints.
• API routes fetch or mutate data in BigQuery or call external tile services.
• Next.js server returns JSON or rendered HTML.
• Client renders map via Mapbox, switching sources based on state (handled by dynamic-layer hooks).
• Authentication flow: Client → NextAuth API → Session store → Client.
c. Architectural Patterns & Principles:
• Separation of Concerns: clear split between presentation, state management, API handlers, and data storage.
• Serverless Functions: each API route is an isolated Lambda-style function.
• Modular Folder Convention: grouping by feature (map-routes vs non-map) and by component type.
• Shared Utility Layers: config, lib, hooks to avoid duplication.
Diagramming Conventions
• Blue for Client/Presentation
• Green for Server/API
• Orange for External Services/Datastores
• Gray for Shared Utilities