You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _docs/dev/architecture/index.md
+153-1Lines changed: 153 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,4 +8,156 @@ has_toc: true
8
8
permalink: /_docs/dev/architecture
9
9
---
10
10
11
-
architecture intro
11
+
## What this app is
12
+
13
+
Half-Earth v3 is a Vite + React single-page application that renders a 3D ArcGIS SceneView “globe” alongside data-driven scenes and UIs. Redux powers routing and synchronizes UI/globe state into the URL, enabling shareable, reproducible views. Translations, analytics, and content integrations complete the platform.
14
+
15
+
Key technologies
16
+
- React 17, Redux, redux-first-router
17
+
-@arcgis/core 4.x (ArcGIS JS API) for the 3D globe
18
+
-@loadable/component for page-level code-splitting
19
+
-@tanstack/react-query for server-state
20
+
- Transifex Native for i18n
21
+
- SCSS modules for styles
22
+
23
+
Entry points
24
+
- index.html: loads ArcGIS CSS and bootstraps the app bundle
25
+
- src/index.jsx: creates the Redux store and mounts <App />
26
+
- src/app.jsx: initializes Transifex + React Query and lazy-loads pages based on the current route
27
+
28
+
## Code organization (where things live)
29
+
30
+
- Pages (src/pages/*)
31
+
- Top-level routes: data-globe, featured-globe, aoi, nrc (+ mobile variants under src/pages/mobile/*).
32
+
- Pages compose a scene with page chrome (headers, sidebars, modals, menus).
33
+
- Scenes (src/containers/scenes/*)
34
+
- Each scene wraps the ArcGIS SceneView via components/scene and owns per-scene configuration (sceneSettings).
35
+
- Orchestrates layers, sidebars, tooltips, onboarding, and other managers.
- Each action updates only its subtree in location.query, preserving the rest.
69
+
70
+
## State management (high level)
71
+
72
+
- The Redux store (store/store.ts) composes base reducers and supports dynamic reducer registration through store/reducerRegistry.js.
73
+
- Feature modules under store/redux-modules/<feature> export a reduxConfig that reducerRegistry.registerModule consumes to inject reducers at runtime (code-splitting friendly).
74
+
- Location (redux-first-router) provides routing and the URL-backed state used by selectors.
75
+
- Deep dive: State Management → /_docs/dev/architecture/state-management
76
+
77
+
## The ArcGIS “globe” architecture
78
+
79
+
Scene wrapper
80
+
- components/scene/scene.js + scene-component.jsx create an ArcGIS Map and a 3D SceneView for each scene.
81
+
- Applies per-scene settings (environment, constraints, padding, popup UI) via the sceneSettings prop.
82
+
- On mobile, the Scene uses a lower qualityProfile to reduce GPU load.
83
+
84
+
Camera, rotation, and URL sync
85
+
- Optional initial rotation animates the globe on first visit; a flag in localStorage avoids repeating.
86
+
- Uses @arcgis/core/core/reactiveUtils (via hooks/esri) to update the URL when the view becomes stationary (center + zoom).
87
+
88
+
Touch pan refinement
89
+
- A custom touch-pan handler in the Scene improves iOS Safari behavior for one-finger panning.
90
+
91
+
Basemap handling
92
+
- utils/layer-manager-utils.setBasemap composes a Basemap from configured base layers (constants/mol-layers-configs + constants/layers-urls).
93
+
94
+
Layer system overview
95
+
- Configuration-driven: constants/mol-layers-configs maps slugs → type (FeatureLayer, TileLayer, VectorTileLayer), URL or portalId, default opacity, optional renderer and bbox.
96
+
- Creation/activation: utils/layer-manager-utils.createLayer/addLayerToMap/activateLayersOnLoad and addActiveLayersToScene instantiate and add activeLayers from state.
97
+
- Visibility/order/opacity: containers/managers/arcgis-layer-manager calls utils/arcgis-layer-manager-utils.setLayersVisibility (and optionally setLayersOrder) based on activeLayers.
98
+
- Labels: containers/layers/labels-layer styles label layers with LabelClass rules from @arcgis/core.
99
+
100
+
Events and interactions
101
+
- containers/managers/globe-events-manager attaches pointer handlers and uses view.hitTest; utils/globe-events-utils centralizes hit results, cursor updates, flyTo helpers, and avatar/marker placement.
102
+
- hooks/esri.js exposes search and sketch widget logic, including area validation against configured limits.
103
+
104
+
Examples by scene
105
+
- Data scene (src/containers/scenes/data-scene/*): thematic layers, labels, tooltips, sidebars, and the globes menu. Configured via data-scene-config.js.
106
+
- AOI scene (src/containers/scenes/aoi-scene/*): AOI mask/outline, optional terrain exaggeration, basemap selector, and ZoomIntoGeometryManager for camera transitions.
107
+
108
+
### Per-scene layer configuration files
109
+
- Each scene ships with a dedicated config module that defines its initial globe and UI state, especially the list/order of layers.
110
+
- Examples:
111
+
- src/containers/scenes/data-scene/data-scene-config.js defines globe.activeLayers, zoom/center, padding, environment, popup and basemap.
112
+
- src/containers/scenes/aoi-scene/config.js defines activeLayers, padding, environment, constraints and basemap.
113
+
- How it flows:
114
+
1) The page builds sceneSettings from the scene’s config and passes it to the Scene component (components/scene).
115
+
2) On map load, activateLayersOnLoad(map, initialActiveLayers, layersConfig) instantiates those layers by looking up their slug in constants/mol-layers-configs.
116
+
3) ArcgisLayerManager keeps visibility/opacity in sync with activeLayers changes.
117
+
- This separation lets us evolve per‑scene defaults without touching the global layer registry (constants/mol-layers-configs, constants/layers-urls).
118
+
119
+
## Data and services
120
+
121
+
- ArcGIS Online: constants/layers-urls centralize FeatureServer/MapServer URLs and portal item ids per layer slug.
122
+
- Service helpers: src/services/esri-feature-service.ts wraps querying/editing via @arcgis/core and @esri/arcgis-rest-feature-layer.
123
+
124
+
### Contentful content and translations
125
+
- What we store there
126
+
- Layer metadata (descriptions, sources, credits) used across the UI.
127
+
- Featured maps stories (editorial content) shown in the Featured Globe and related views.
128
+
- Per-locale pages in Contentful
129
+
- Content entries are translated per locale in Contentful (separate localized pages/entries).
130
+
- The app requests the appropriate locale when fetching entries so users see the correct language.
131
+
- Where the locale comes from
132
+
- We keep the UI locale in the URL (location.query.lang) and initialize Transifex in src/app.jsx.
133
+
- The same locale value is used when requesting Contentful entries.
- Pages are lazy-loaded with @loadable/component to keep the initial bundle small.
141
+
- Redux reducers load on demand via reducerRegistry; avoid upfront loading of all modules.
142
+
- ArcGIS CSS is linked in index.html; ArcGIS API resources are lazily used by the Scene.
143
+
- Prefer reusing created layers; avoid unnecessary re-instantiation when toggling visibility/opacity.
144
+
145
+
## How to extend
146
+
147
+
Add or update layers
148
+
- Follow the guide: /_docs/dev/layers/add-update
149
+
- Typical steps: add/update constants/mol-layers-configs and constants/layers-urls entries; ensure the visibility/ordering path in arcgis-layer-manager is correct; test URL serialization for activeLayers.
150
+
151
+
Add a new scene/page
152
+
- Add a route in src/router.ts (path + page key).
153
+
- Create a page under src/pages/<page> and wire it in App (lazy-loaded with @loadable/component).
154
+
- Compose a scene in src/containers/scenes/<new-scene> with components/scene; define sceneSettings and required managers (layer, events, zoom).
155
+
- If the new state is URL-driven, add actions/selectors and update constants as needed; consider onboarding and mobile variants.
156
+
157
+
## Cross-links and related docs
158
+
159
+
- State management: /_docs/dev/architecture/state-management
160
+
- Working with layers (add/update): /_docs/dev/layers/add-update
0 commit comments