# terra-online/oem-sdk architecture

> Architecture diagram of the GitHub repository terra-online/oem-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terra-online/oem-sdk
- Repository: https://github.com/terra-online/oem-sdk

## Overview

Open Endfield Map SDK lets host applications embed an interactive, versioned Endfield map. The main workflow is host configuration into the SDK widget, manifest/resource loading, map creation, feature and point rendering, and interactive results returned through map APIs and events. React wraps the widget lifecycle; hosts can also use the lower-level map package directly. The README documents localization, historical data, coordinate conversion, custom overlays, and clustering. Some subsystem links reflect documented capabilities and directory structure; only sampled source was inspected.

Main entry points: [`packages/sdk/src/widget.ts`](https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/widget.ts) (Widget lifecycle), [`packages/map/src/runtime/oem.ts`](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/runtime/oem.ts) (Map runtime), [`packages/map/src/index.ts`](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/index.ts) (Map creation), [`packages/core/src/index.ts`](https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/index.ts) (Core utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Host integration"]
  node_react["React wrapper<br/>[index.tsx]"]
  node_sdk["SDK entry<br/>[index.ts]"]
end

subgraph group_widget["Widget experience"]
  node_widget["Widget lifecycle<br/>[widget.ts]"]
  node_controls["Map controls<br/>[index.ts]"]
  node_clicktool["Click-point tool<br/>[clickPoints.ts]"]
end

subgraph group_map["Map runtime"]
  node_mapapi["Map API<br/>[api.ts]"]
  node_mapentry["Map creation<br/>[index.ts]"]
  node_runtime["Map runtime<br/>[oem.ts]"]
  node_repository[("Resource cache<br/>[repository.ts]")]
  node_canvas["Marker rendering"]
  node_mapconfig["Map configuration<br/>[config.ts]"]
end

subgraph group_data["Data and resources"]
  node_core["Core utilities<br/>[index.ts]"]
  node_manifest["Manifest validation<br/>[validation.ts]"]
  node_resources["Resource loading<br/>[resources.ts]"]
  node_coordinates["Coordinate conversion<br/>[coordinates.ts]"]
end

node_host(("Host application"))
node_oemdata[("OEM map assets")]

node_host -->|"configures"| node_sdk
node_host -.->|"mounts"| node_react
node_react -->|"creates and updates"| node_widget
node_sdk -->|"creates"| node_widget
node_widget -->|"loads manifest"| node_core
node_widget -->|"creates map"| node_mapentry
node_widget -->|"mounts controls"| node_controls
node_widget -->|"delegates commands"| node_mapapi
node_sdk -->|"exposes tool"| node_clicktool
node_clicktool -->|"subscribes and edits points"| node_mapapi
node_mapentry -->|"loads resources"| node_core
node_mapentry -->|"checks manifest"| node_manifest
node_mapentry -->|"constructs runtime"| node_runtime
node_runtime -->|"caches loads"| node_repository
node_runtime -->|"fetches assets"| node_oemdata
node_runtime -->|"renders markers"| node_canvas
node_runtime -->|"resolves updates"| node_mapconfig
node_core -->|"provides resource helpers"| node_resources
node_core -->|"provides conversions"| node_coordinates
node_resources -->|"resolves asset URLs"| node_oemdata

click node_react "https://github.com/terra-online/oem-sdk/blob/main/packages/react/src/index.tsx"
click node_sdk "https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/index.ts"
click node_widget "https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/widget.ts"
click node_controls "https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/components/index.ts"
click node_clicktool "https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/tools/clickPoints.ts"
click node_mapapi "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/api.ts"
click node_mapentry "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/index.ts"
click node_runtime "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/runtime/oem.ts"
click node_repository "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/runtime/repository.ts"
click node_canvas "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/atlos/canvas/canvasMarkerSurface.ts"
click node_mapconfig "https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/config.ts"
click node_core "https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/index.ts"
click node_manifest "https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/validation.ts"
click node_resources "https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/resources.ts"
click node_coordinates "https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/coordinates.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react,node_sdk toneBlue
class node_widget,node_controls,node_clicktool,node_oemdata toneAmber
class node_mapapi,node_mapentry,node_runtime,node_repository,node_canvas,node_mapconfig toneMint
class node_core,node_manifest,node_resources,node_coordinates toneRose
class node_host toneIndigo
```

## Components

### Host integration

- [React wrapper](https://github.com/terra-online/oem-sdk/blob/main/packages/react/src/index.tsx): `packages/react/src/index.tsx`
- [SDK entry](https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/index.ts): `packages/sdk/src/index.ts`

### Widget experience

- [Widget lifecycle](https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/widget.ts): `packages/sdk/src/widget.ts`
- [Map controls](https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/components/index.ts): `packages/sdk/src/components/index.ts`
- [Click-point tool](https://github.com/terra-online/oem-sdk/blob/main/packages/sdk/src/tools/clickPoints.ts): `packages/sdk/src/tools/clickPoints.ts`

### Map runtime

- [Map API](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/api.ts): `packages/map/src/api.ts`
- [Map creation](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/index.ts): `packages/map/src/index.ts`
- [Map runtime](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/runtime/oem.ts): `packages/map/src/runtime/oem.ts`
- [Resource cache](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/runtime/repository.ts): `packages/map/src/runtime/repository.ts`
- [Marker rendering](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/atlos/canvas/canvasMarkerSurface.ts): `packages/map/src/atlos/canvas/canvasMarkerSurface.ts`
- [Map configuration](https://github.com/terra-online/oem-sdk/blob/main/packages/map/src/config.ts): `packages/map/src/config.ts`

### Data and resources

- [Core utilities](https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/index.ts): `packages/core/src/index.ts`
- [Manifest validation](https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/validation.ts): `packages/core/src/validation.ts`
- [Resource loading](https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/resources.ts): `packages/core/src/resources.ts`
- [Coordinate conversion](https://github.com/terra-online/oem-sdk/blob/main/packages/core/src/coordinates.ts): `packages/core/src/coordinates.ts`

### Other components

- **Host application**
- **OEM map assets**

## Connections

- Host application → SDK entry: configures
- Host application → React wrapper: mounts
- React wrapper → Widget lifecycle: creates and updates
- SDK entry → Widget lifecycle: creates
- Widget lifecycle → Core utilities: loads manifest
- Widget lifecycle → Map creation: creates map
- Widget lifecycle → Map controls: mounts controls
- Widget lifecycle → Map API: delegates commands
- SDK entry → Click-point tool: exposes tool
- Click-point tool → Map API: subscribes and edits points
- Map creation → Core utilities: loads resources
- Map creation → Manifest validation: checks manifest
- Map creation → Map runtime: constructs runtime
- Map runtime → Resource cache: caches loads
- Map runtime → OEM map assets: fetches assets
- Map runtime → Marker rendering: renders markers
- Map runtime → Map configuration: resolves updates
- Core utilities → Resource loading: provides resource helpers
- Core utilities → Coordinate conversion: provides conversions
- Resource loading → OEM map assets: resolves asset URLs