# gainforest/green_globe_2 architecture

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

- Interactive diagram: https://gitdiagram.com/gainforest/green_globe_2
- Repository: https://github.com/gainforest/green_globe_2

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client / Presentation Layer
    subgraph "Client / Presentation Layer"
        direction TB
        Browser["Browser / Client"]:::frontend
        MapComp["Map Component<br/>(Map/index.tsx)"]:::frontend
        LayersOverlay["Layers Overlay<br/>(LayersOverlay/index.tsx)"]:::frontend
        HoveredTree["Hovered Tree Overlay<br/>(HoveredTreeOverlay/index.tsx)"]:::frontend
        GenericOverlay["Generic Overlay<br/>(Overlay/index.tsx)"]:::frontend
        ProjectOverlay["Project Overlay<br/>(ProjectOverlay/index.tsx)"]:::frontend
        SearchOverlay["Search Overlay<br/>(SearchOverlay/index.tsx)"]:::frontend
        Sidebar["Sidebar<br/>(Sidebar.tsx)"]:::frontend
        AuthBoundary["Auth Boundary<br/>(ClientAuthBoundary.tsx)"]:::frontend
    end

    %% Next.js Server
    subgraph "Next.js Server"
        direction TB
        subgraph "App Router (TSX)"
            direction TB
            RootLayout["Root Layout<br/>(layout.tsx)"]:::backend
            MapLayout["Map Routes Layout<br/>(map-routes/layout.tsx)"]:::backend
            NonMapLayout["Non-Map Routes Layout<br/>(non-map-routes/layout.tsx)"]:::backend
            MapPage["Project Map Page<br/>([projectId]/page.tsx)"]:::backend
            ShapefilePage["Shapefile Import Page<br/>(geo/view/page.tsx)"]:::backend
            MyProjects["My Projects Page<br/>(my-projects/page.tsx)"]:::backend
        end
        subgraph "API Routes (Serverless)"
            direction TB
            AuthRoute["NextAuth Route<br/>([...nextauth]/route.ts)"]:::backend
            AuthOptions["NextAuth Options<br/>(options.ts)"]:::backend
            UsersCRUD["Users CRUD<br/>(users/route.ts & [id]/route.ts)"]:::backend
            ProjectsCRUD["Projects CRUD<br/>(projects/route.ts & action.ts)"]:::backend
            BigQueryAPI["BigQuery API<br/>(bigquery.ts)"]:::backend
            PlanetTilesAPI["Planet Tiles Proxy<br/>(planet-tiles/route.ts)"]:::backend
        end
    end

    %% Data and External Services
    subgraph "External Services & Data Stores"
        direction TB
        BigQueryDB["BigQuery (SQL)"]:::external
        PlanetService["Planet Tiles API"]:::external
        Mapbox["Mapbox GL JS"]:::external
        SessionStore["Session Store<br/>(NextAuth Adapter)"]:::external
        WalletProvider["WalletConnect / SIWE"]:::external
    end

    %% Shared Utilities
    subgraph "Shared Utilities & Config"
        direction TB
        Config["Config<br/>(src/config)"]:::util
        Web3Ctx["Web3 Context<br/>(wagmi.tsx)"]:::util
        UIComponents["Shared UI Components<br/>(src/components/ui)"]:::util
        Utils["Utility Libraries<br/>(lib & utils)"]:::util
        Styles["Global Styles & Manifest"]:::util
    end

    %% Client to Server
    Browser -->|"SSR/CSR"| RootLayout
    Browser -->|"API Requests"| AuthRoute
    Browser --> MapPage
    Browser --> ShapefilePage
    Browser --> MyProjects
    Browser --> MapComp

    %% Component Relations
    MapComp --> LayersOverlay
    MapComp --> HoveredTree
    MapComp --> GenericOverlay
    MapComp --> ProjectOverlay
    MapComp --> SearchOverlay
    AuthBoundary --> MyProjects
    AuthBoundary --> ProjectsCRUD

    %% Server API to External/Data
    AuthRoute --> SessionStore
    UsersCRUD --> SessionStore
    ProjectsCRUD --> BigQueryDB
    BigQueryAPI --> BigQueryDB
    PlanetTilesAPI --> PlanetService

    %% Client hooks & rendering
    LayersOverlay -->|"fetch project data"| ProjectsCRUD
    ProjectOverlay --> ProjectsCRUD
    SearchOverlay --> UsersCRUD
    ShapefilePage --> PlanetTilesAPI
    MapComp --> Mapbox

    %% Shared utilities usage
    RootLayout --> Config
    AuthBoundary --> Web3Ctx
    MapComp --> UIComponents
    LayersOverlay --> Utils
    ProjectOverlay --> Utils
    ShapefilePage --> Utils
    MapLayout --> Styles
    NonMapLayout --> Styles

    %% Click Events
    click MapComp "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/Map/index.tsx"
    click LayersOverlay "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/LayersOverlay/index.tsx"
    click HoveredTree "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/HoveredTreeOverlay/index.tsx"
    click GenericOverlay "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/Overlay/index.tsx"
    click ProjectOverlay "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/ProjectOverlay/index.tsx"
    click SearchOverlay "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/_components/SearchOverlay/index.tsx"
    click Sidebar "https://github.com/gainforest/green_globe_2/blob/main/src/app/(non-map-routes)/_components/Sidebar.tsx"
    click AuthBoundary "https://github.com/gainforest/green_globe_2/blob/main/src/app/(non-map-routes)/_components/ClientAuthBoundary.tsx"
    click RootLayout "https://github.com/gainforest/green_globe_2/blob/main/src/app/layout.tsx"
    click MapLayout "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/layout.tsx"
    click NonMapLayout "https://github.com/gainforest/green_globe_2/blob/main/src/app/(non-map-routes)/layout.tsx"
    click MapPage "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(main)/[projectId]/page.tsx"
    click ShapefilePage "https://github.com/gainforest/green_globe_2/blob/main/src/app/(map-routes)/(shapefile-related)/geo/view/page.tsx"
    click MyProjects "https://github.com/gainforest/green_globe_2/blob/main/src/app/(non-map-routes)/my-projects/page.tsx"
    click AuthRoute "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click AuthOptions "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/auth/options.ts"
    click UsersCRUD "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/users/route.ts"
    click ProjectsCRUD "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/projects/route.ts"
    click BigQueryAPI "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/bigquery.ts"
    click PlanetTilesAPI "https://github.com/gainforest/green_globe_2/blob/main/src/app/api/planet-tiles/route.ts"
    click Config "https://github.com/gainforest/green_globe_2/blob/main/src/config/map.ts"
    click Web3Ctx "https://github.com/gainforest/green_globe_2/blob/main/src/app/_contexts/wagmi.tsx"
    click UIComponents "https://github.com/gainforest/green_globe_2/blob/main/src/components/ui/button.tsx"
    click Utils "https://github.com/gainforest/green_globe_2/blob/main/src/lib/utils.ts"
    click Styles "https://github.com/gainforest/green_globe_2/blob/main/src/app/globals.css"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef util fill:#F0F0F0,stroke:#808080,color:#808080;
```
