# adamscybot/react-leaflet-component-marker architecture

> Architecture diagram of the GitHub repository adamscybot/react-leaflet-component-marker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adamscybot/react-leaflet-component-marker
- Repository: https://github.com/adamscybot/react-leaflet-component-marker

## Overview

##### Project Type and Purpose
- This is a small, focused React component library (an open-source tool) named **react-leaflet-component-marker**.
- Purpose: allow users to drop *fully interactive* React components into a Leaflet map as markers, leveraging React Portals instead of static HTML rendering.

##### File-Structure Analysis
- Top-level build & config:
- `.github/workflows/` (CI for build and release)
- `package.json`, `tsconfig.json`/`tsconfig.build.json`, ESLint/Prettier configs
- Source code:
- `src/index.ts` – library entry point exporting the custom `Marker`.
- `src/Marker.tsx` – core React component wrapper around `react-leaflet`’s `<Marker>`.
- `src/lib/` – utilities: `logging.ts` (warnings, debug) and `useCoordsFromPointExpression.ts` (coordinate parsing).
- Tests:
- `cypress/` for component-level tests.
- Types:
- `@types/react-leaflet-core.d.ts` – extended typings.

##### Key Architecture Insights from README
- Uses React’s `createPortal` under the hood to mount marker children.
- Exposes an API identical to React-Leaflet’s `<Marker>` plus extended props (`componentIconOpts`).
- Supports two layout modes: `fit-content` and `fit-parent`.

##### Main Components
a. Consumer Application (downstream)
- A React app that imports and uses `@adamscybot/react-leaflet-component-marker`.
b. Library Module (`@adamscybot/react-leaflet-component-marker`)
- Entry: `src/index.ts`.
- Core: `src/Marker.tsx`
- Wraps `react-leaflet`’s `<Marker>`.
- Calculates CSS position via `useCoordsFromPointExpression`.
- Emits warnings via `logging.ts`.
- Utilities:
- `useCoordsFromPointExpression` – converts Leaflet points to pixel offsets.
- `logging` – console warnings.
c. External Dependencies
- React & React-DOM (for Portals)
- react-leaflet (for Map and Marker)
- leaflet (for map engine & DivIcon)
- Cypress (for component tests)
d. Build & Release
- TypeScript compiler – `tsconfig.build.json`.
- CI workflows: build, test, publish to npm.

##### Relationships and Data-Flow
1. **Consumer App** calls → **Library Entry**
2. **Library** delegates → **react-leaflet `<Marker>`**
3. When rendering, **Library**
- Creates a DOM `
` wrapper (Leaflet DivIcon)
- Uses React-DOM Portal to mount user’s JSX into that wrapper
- Listens to map events via `react-leaflet` context
4. **Leaflet Engine** controls actual map panning/zoom; `fit-parent` mode delegates size back to Leaflet.
5. **Tests** simulate user interactions via Cypress against the component in isolation.

##### Architectural Patterns & Principles
- **Adapter/Wrapper Pattern**: wraps existing `<Marker>` API, preserving original contract.
- **Portal Pattern**: detaches React component subtree and remounts it into an external DOM node.
- **Utility Extraction**: coordinate parsing & logging are factored into small hooks/modules.
- **Strong Typing**: full TypeScript coverage for API safety.

##### Detail Level
- Configuration (tsconfig, eslint, Prettier) grouped under “Dev Config.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    subgraph "Consumer Application" 
        CA[/"React App"/]:::external
        CA -->|imports| Entry
    end

    %% Library Module
    subgraph "Library: @adamscybot/react-leaflet-component-marker"
        Entry["src/index.ts"]:::module
        Marker["src/Marker.tsx"]:::module
        Typings["@types/react-leaflet-core.d.ts"]:::config
        subgraph "Utilities"
            Coords["useCoordsFromPointExpression"]:::module
            Logging["logging.ts"]:::module
        end
        Entry -->|exports Marker| Marker
        Marker -->|uses| Coords
        Marker -->|logs via| Logging
        Marker -->|wraps| RLMarker
    end

    %% External Dependencies
    subgraph "External Dependencies"
        React((React)):::external
        ReactDOM((React-DOM)):::external
        RL[(react-leaflet)]:::external
        Leaflet((leaflet)):::external
    end

    %% Runtime Flow
    CA -->|"calls render"| Entry
    Marker -->|delegates render to| RLMarker["<Marker>"]:::external
    RLMarker -->|inside| RL
    Marker -->|creates Portal| ReactDOM
    ReactDOM -->|mounts into| DivIcon["Leaflet DivIcon (DOM <div> wrapper)"]:::storage
    DivIcon -->|display| Leaflet

    %% Testing
    subgraph "Testing (Cypress)" 
        CypressTests["cypress/specs/marker.cy.tsx"]:::test
        Support["cypress/support"]:::test
        ConfigCypress["cypress.config.js"]:::config
        CypressTests -->|tests| Marker
        Support -->|setup| CypressTests
    end

    %% CI/CD and Build
    subgraph "Build & Release Pipeline" 
        BuildWF[".github/workflows/build.yml"]:::ci
        ReleaseWF[".github/workflows/release.yml"]:::ci
        TSBuild["tsconfig.build.json"]:::config
        TSConfig["tsconfig.json"]:::config
        ESLint["eslint.config.js"]:::config
        Prettier[".prettierrc"]:::config
        PackageJSON["package.json"]:::config
        BuildWF -->|run build via| TSBuild
        BuildWF -->|lint| ESLint
        BuildWF -->|type check| TSConfig
        ReleaseWF -->|publish to| NpmRegistry[(npm registry)]:::external
    end

    %% Styles and Classes
    classDef module fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px
    classDef external fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px
    classDef storage fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef ci fill:#E8F5E9,stroke:#43A047,stroke-width:2px
    classDef test fill:#FFFDE7,stroke:#FDD835,stroke-width:2px
    classDef config fill:#ECEFF1,stroke:#607D8B,stroke-width:2px

    %% Click Events
    click Entry "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/src/index.ts"
    click Marker "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/src/Marker.tsx"
    click Coords "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/src/lib/useCoordsFromPointExpression.ts"
    click Logging "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/src/lib/logging.ts"
    click Typings "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/@types/react-leaflet-core.d.ts"
    click BuildWF "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/.github/workflows/build.yml"
    click ReleaseWF "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/.github/workflows/release.yml"
    click CypressTests "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/cypress/specs/marker.cy.tsx"
    click Support "https://github.com/adamscybot/react-leaflet-component-marker/tree/main/cypress/support"
    click ConfigCypress "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/cypress.config.js"
    click TSBuild "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/tsconfig.build.json"
    click TSConfig "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/tsconfig.json"
    click ESLint "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/eslint.config.js"
    click Prettier "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/.prettierrc"
    click PackageJSON "https://github.com/adamscybot/react-leaflet-component-marker/blob/main/package.json"
```
