# rajtoshranjan/earth architecture

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

- Interactive diagram: https://gitdiagram.com/rajtoshranjan/earth
- Repository: https://github.com/rajtoshranjan/earth

## Overview

##### Main Project and Purpose Overview
- The project is a rich interactive web application for exploring a 3D representation of Earth’s surface, featuring map interactions (zoom, pan), search, measurement tools, and layer management (both raster and vector).
- It is built primarily as a single-page application (SPA) using React while integrating Maplibre GL JS and custom hooks for managing map layers and interactions.

##### And List the Key Architectural Components
- User Interface Components:
- The Header component (providing search functionality and navigation).
- The Layer Panel (for adding layers, drawing features, and handling map overlays).
- The Map Container, which holds the interactive map view.
- Application Core:
- React entry point (src/main.tsx and src/app.tsx) that bootstraps the application.
- Global context (src/contexts) used for state management across components.
- Custom hooks under src/core/hooks, especially use-maplibre-layers, which encapsulate business logic related to managing the map’s layers and integrating with Maplibre.
- Maplibre integration housed in src/core/maplibre with utilities for map setup, initialization, and operations.
- Services and External APIs:
- API service for Maptiler (located in src/services/apis/maptiler) which likely provides map data, tiles, or geolocation services.
- Firebase configurations and GitHub workflows hint at CI/CD and hosting deployments, even if not strictly part of the application’s runtime logic.
- Assets and Styling:
- Tailwind CSS and PostCSS configurations indicate that styling is done using a utility-first approach.
- Environment and Configuration:
- Environment variables are managed via the env-files folder.
- Various config files (.eslintrc.js, tsconfig.json, vite.config.ts) ensure code quality, type safety, and build processes.

##### Relationships & Interactions between Components
- The User interacts with the UI elements (Header, Buttons, Inputs, etc.), which are implemented as React components.
- User actions in components trigger state changes via the global context and custom hooks.
- The Map Container communicates with the underlying Maplibre layer (through components in src/core/maplibre and hooks in src/core/hooks) to update map views and render layers.
- When layer changes or map interactions occur, the application might call external APIs (such as Maptiler, via the services layer) to fetch additional map data.
- The entire UI is stitched together through React’s component composition and state management. Configuration files and build scripts ensure proper development and deployment flows.

##### Important Architectural Patterns and Principles
- Component-Based Architecture: Clear separation into UI components (modular and reusable).
- Custom Hooks: Encapsulate map-related logic and side effects.
- State Management via Context API: Provides global state persistence (such as storing map state in local storage as mentioned in the README).
- Separation of Concerns: Distinct directories handle assets, business logic (core and hooks), UI presentation (components/ui), and external integration (services).
- Deployment & Quality Controls: CI/CD workflows (GitHub Actions for linting, testing, and Firebase deployment) and well-defined configuration files uphold best practices.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global User
    User["User"]:::external

    %% UI Components Subgraph
    subgraph "UI Components"
        Button["Button Component"]:::ui
        Dropdown["Dropdown Menu Component"]:::ui
        Icon["Icon Component"]:::ui
        Input["Input Component"]:::ui
        Modal["Modal Component"]:::ui
        Spinner["Spinner Component"]:::ui
    end
    click Button "https://github.com/rajtoshranjan/earth/tree/master/src/components/button"
    click Dropdown "https://github.com/rajtoshranjan/earth/tree/master/src/components/dropdown-menu"
    click Icon "https://github.com/rajtoshranjan/earth/tree/master/src/components/icon"
    click Input "https://github.com/rajtoshranjan/earth/tree/master/src/components/input"
    click Modal "https://github.com/rajtoshranjan/earth/tree/master/src/components/modal"
    click Spinner "https://github.com/rajtoshranjan/earth/blob/master/src/components/spinner.tsx"

    %% Header Component
    Header["Header Component"]:::ui
    click Header "https://github.com/rajtoshranjan/earth/tree/master/src/header"

    %% Layer Panel Subgraph
    subgraph "Layer Panel"
        LayerPanel["Layer Panel"]:::ui
        DrawTools["Draw Tools"]:::ui
    end
    click LayerPanel "https://github.com/rajtoshranjan/earth/tree/master/src/layer-panel"
    click DrawTools "https://github.com/rajtoshranjan/earth/tree/master/src/layer-panel/draw/draw-feature-modal"

    %% Map Container
    MapContainer["Map Container"]:::ui
    click MapContainer "https://github.com/rajtoshranjan/earth/tree/master/src/map-container"

    %% Application Core Subgraph
    subgraph "Application Core"
        Main["React Entry (main.tsx)"]:::core
        App["React App (app.tsx)"]:::core
        GlobalContext["Global Context"]:::core
    end
    click Main "https://github.com/rajtoshranjan/earth/blob/master/src/main.tsx"
    click App "https://github.com/rajtoshranjan/earth/blob/master/src/app.tsx"
    click GlobalContext "https://github.com/rajtoshranjan/earth/tree/master/src/contexts"

    %% Custom Hooks
    Hooks["use-maplibre-layers Hook"]:::core
    click Hooks "https://github.com/rajtoshranjan/earth/tree/master/src/core/hooks/use-maplibre-layers"

    %% Maplibre Integration
    Maplibre["Maplibre Integration"]:::core
    click Maplibre "https://github.com/rajtoshranjan/earth/tree/master/src/core/maplibre"

    %% Services & External API
    Maptiler["Maptiler Service"]:::service
    click Maptiler "https://github.com/rajtoshranjan/earth/tree/master/src/services/apis/maptiler"

    %% Assets and Styling
    Assets["Assets & Styling"]:::asset
    click Assets "https://github.com/rajtoshranjan/earth/tree/master/src/assets"
    Tailwind["Tailwind CSS Config"]:::asset
    click Tailwind "https://github.com/rajtoshranjan/earth/blob/master/tailwind.config.js"

    %% Environment & Config
    EnvConfig["Environment & Config"]:::env
    click EnvConfig "https://github.com/rajtoshranjan/earth/blob/master/env-files/.env.sample"

    %% CI/CD & Deployment
    Deployment["CI/CD & Deployment (Firebase, GitHub)"]:::deployment

    %% Relationships
    User -->|"interacts"| Header
    User -->|"interacts"| MapContainer

    Header -->|"updates"| GlobalContext
    LayerPanel -->|"updates"| GlobalContext

    GlobalContext -->|"triggers"| Hooks
    Hooks -->|"calls"| Maplibre
    Maplibre -->|"renders"| MapContainer
    MapContainer -->|"API calls"| Maptiler

    App -->|"build/deploy"| Deployment
    EnvConfig -->|"configures"| App
    Assets -->|"styles"| Header
    Assets -->|"styles"| LayerPanel

    %% Styling Definitions
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef asset fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef env fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef deployment fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#000,stroke-width:2px;
```
