# georetina/chat2geo architecture

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

- Interactive diagram: https://gitdiagram.com/georetina/chat2geo
- Repository: https://github.com/georetina/chat2geo

## Overview

##### Main Components
- Frontend: The UI is built in Next.js using React components. The “app” directory is organized into sections such as (auth), (broadcast), and (main). Each section contains layouts, pages, and API routes. Additionally, there is a “components” folder and specific feature folders (e.g., features/chat, features/maps, features/knowledge-base, features/user-profile, and so on).
- Backend/API: Many API endpoints are defined within the “app” subdirectories. These API routes handle authentication, geospatial analyses (e.g., chat, gee, google-maps-related endpoints), data fetching, and integration with external services.
- Geospatial Processing: The integration with Google Earth Engine (GEE) for remote-sensing analyses is a primary backend capability. There are also helper functions in “lib/geospatial” that perform various analyses (urban heat island, land cover mapping, pollution analysis, etc.).
- External Services & Integrations:
- Google Cloud Platform services (Google Earth Engine and Vertex AI).
- Supabase for database and authentication.
- Google Maps API and Esri integration endpoints.
- Additional external libraries and APIs (OpenAI ChatGPT API, LangChain for RAG, Maplibre GL for maps, Turf for spatial operations).

##### Relationships and Interactions
- User Interface (React components, pages) makes API calls (using Next.js API routes) to the backend.
- Authentication flows: There is a dedicated (auth) module handling login, confirm flows, and Esri-specific OAuth workflows.
- Knowledge Base/RAG: Integration for the retrieval-augmented generation is managed within related “features/knowledge-base” components and supported by custom configurations and actions.
- Database and Authentication: Supabase is integrated for storing chat histories, user profiles, usage metrics, and document uploads (knowledge base documents) as indicated by the “db-schema” folder and environment variable guidelines.
- External Data and Processing: The backend orchestrates interactions with GEE for heavy geospatial computations, forwarding the results to the chat interface and map components.

##### Architectural Patterns & Principles
- Modular & Feature-driven Design: The project is organized in a feature-first style with separate folders for each domain (e.g., chat, maps, knowledge base), facilitating clear boundaries.
- Serverless/API Routes: Next.js API routes are used to expose backend functionalities.
- Integration and Loose Coupling: The system decouples its frontend rendering from backend processing (e.g., calling external APIs, GEE analysis) to allow scalable deployment.
- Extensibility: The rich usage of custom configurations (custom-configs) and utility functions (lib, utils) suggest an architecture designed for further extensions (like adding new geospatial analyses).

a. Main Components:
- User Interface (Front-end): Displaying chat interfaces, map views, user profile modals, and integration pages.
- API Gateway / Next.js API Routes: Split into categories (Authentication, Chat, Geospatial analysis, and Feedback/Services).
- Geospatial Analysis Engine: Google Earth Engine integration, including sub-components for various analyses (UHI, land cover, air pollution analysis).
- External Integrations: Connectors to Supabase (database & auth), Google Maps / Esri, Vertex AI, OpenAI, and additional external services.
- Supporting components: Utility libraries and feature branches (knowledge base, text editor, file/document management).

b. Relationships & Interactions:
- Bi-directional interactions where needed; for example, the user’s interactions affect map updates and chat responses.
- That the configuration and utility libraries underpin both UI and API functionalities.

c. Technologies and Their Placement:
- Next.js as the front-end framework & server-side rendering.
- Google Cloud products (GEE, Vertex AI, Cloud Run) as processing services.
- Supabase as a database/authentication layer.
- Additional integration modules for Google Maps, Esri, and OpenAI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend (Next.js UI)
    subgraph "Frontend (Next.js UI)"
        F1["UI: Auth"]:::frontend
        F2["UI: Broadcast"]:::frontend
        F3["UI: Main"]:::frontend
        F4["UI: Components"]:::frontend
        F5["UI: Chat"]:::frontend
        F6["UI: Maps"]:::frontend
        F7["UI: Knowledge Base"]:::frontend
        F8["UI: User Profile"]:::frontend
        F9["UI: Text Editor"]:::frontend
        F10["UI: Charts"]:::frontend
    end

    %% Backend (API Routes)
    subgraph "Backend (API Routes)"
        B1["Auth API"]:::backend
        B2["Chat API"]:::backend
        B3["Geo API"]:::backend
        B4["Maps Service API"]:::backend
        B5["Esri Service API"]:::backend
        B6["RAG Actions"]:::backend
    end

    %% External Services
    subgraph "External Services"
        E1["Google Earth Engine (GEE)"]:::external
        E2["Vertex AI"]:::external
        E3["OpenAI ChatGPT"]:::external
        E4["Supabase DB/Auth"]:::external
        E5["Google Maps API"]:::external
        E6["Esri External"]:::external
    end

    %% Utility & Configuration Layer
    subgraph "Utility & Configs"
        U1["Auth Utils"]:::utility
        U2["Geospatial Utils"]:::utility
        U3["General Utils"]:::utility
        U4["Custom Configs"]:::utility
        U5["Supabase Utils"]:::utility
    end

    %% Connections from Frontend to Backend
    F1 -->|"auth_call"| B1
    F5 -->|"chat_call"| B2
    F3 -->|"geo_query"| B3
    F6 -->|"map_request"| B4
    F2 -->|"esri_oauth"| B5
    F7 -->|"rag_query"| B6
    F8 -->|"profile_auth"| B1

    %% Connections from Backend to External Services
    B1 -->|"db_auth"| E4
    B3 -->|"gee_proc"| E1
    B4 -->|"maps_data"| E5
    B5 -->|"esri_data"| E6
    B6 -->|"ai_proc"| E2
    B6 -->|"llm"| E3

    %% Connections from Backend and Frontend to Utility & Configs
    B1 -->|"auth_helper"| U1
    B3 -->|"geo_helper"| U2
    F4 -->|"common_util"| U3
    B1 -->|"db_middleware"| U5
    B6 -->|"ai_config"| U4

    %% Click Events for Frontend
    click F1 "https://github.com/georetina/chat2geo/tree/main/app/(auth)"
    click F2 "https://github.com/georetina/chat2geo/tree/main/app/(broadcast)"
    click F3 "https://github.com/georetina/chat2geo/tree/main/app/(main)"
    click F4 "https://github.com/georetina/chat2geo/tree/main/components"
    click F5 "https://github.com/georetina/chat2geo/tree/main/features/chat"
    click F6 "https://github.com/georetina/chat2geo/tree/main/features/maps"
    click F7 "https://github.com/georetina/chat2geo/tree/main/app/(main)/knowledge-base"
    click F8 "https://github.com/georetina/chat2geo/tree/main/features/user-profile"
    click F9 "https://github.com/georetina/chat2geo/tree/main/features/text-editor"
    click F10 "https://github.com/georetina/chat2geo/tree/main/features/charts"

    %% Click Events for Backend (API Routes)
    click B1 "https://github.com/georetina/chat2geo/tree/main/app/(auth)/api/auth"
    click B2 "https://github.com/georetina/chat2geo/tree/main/app/(main)/api/chat"
    click B3 "https://github.com/georetina/chat2geo/tree/main/app/(main)/api/gee"
    click B4 "https://github.com/georetina/chat2geo/tree/main/app/(main)/api/services/google-maps"
    click B5 "https://github.com/georetina/chat2geo/tree/main/app/(broadcast)/api/services/esri"
    click B6 "https://github.com/georetina/chat2geo/blob/main/app/actions/rag-actions.ts"

    %% Click Events for External Services
    click E2 "https://github.com/georetina/chat2geo/blob/main/custom-configs/ai-assistants.ts"
    click E4 "https://github.com/georetina/chat2geo/tree/main/utils/supabase"
    click E6 "https://github.com/georetina/chat2geo/tree/main/components/services/esri"

    %% Click Events for Utility & Configs
    click U1 "https://github.com/georetina/chat2geo/blob/main/lib/auth.ts"
    click U2 "https://github.com/georetina/chat2geo/tree/main/lib/geospatial"
    click U3 "https://github.com/georetina/chat2geo/blob/main/lib/utils.ts"
    click U4 "https://github.com/georetina/chat2geo/blob/main/custom-configs/project-config.ts"
    click U5 "https://github.com/georetina/chat2geo/tree/main/utils/supabase"

    %% Class Definitions (Color Coding)
    classDef frontend fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef backend fill:#f1f8e9,stroke:#33691e,stroke-width:2px;
    classDef external fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef utility fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
```
