Skip to main content

ArcGIS at a Glance

An operator opens the app and, within a couple of seconds, is looking at every camera in California drawn over terrain, with fire perimeters, battalion boundaries, aircraft tracks and weather underneath. Most of that picture is not ours. The basemap, the hundred-odd operational layers, the hosted camera service and the real-time streams all belong to Esri's stack and to the GIS team that curates it in ArcGIS Online. What is ours is everything that makes those layers behave like a wildfire console: the rotating arrows, the field-of-view wedges, the AI pulse, the filters, the hover and click behaviour, and the discipline that keeps 1,400 moving points at sixty frames a second.

This chapter is the long-form account of that integration. The map lessons under Features teach you to read and tune the map; this chapter explains the machinery underneath, end to end, in the order a new senior engineer would want to learn it. Start here, read in order, and by the last page you will know where every pixel on the map comes from and which repo, portal or service you have to change to move it.

The three contracts​

Everything Esri-related in this app sits on one of three contracts. Knowing which one you are touching is the first question to ask about any map change.

1. The WebMap. A portal item in ArcGIS Online, authored by the GIS team, identified by NEXT_PUBLIC_MASTER_MAP_PORTAL_ITEM_ID per environment. It carries the basemap, every operational layer, their symbology and popups, group structure, and the environment's camera feature service and Velocity streams. We load it by id and curate it; we never author it in code. Adding a fire-perimeter layer is a portal change, not a pull request.

2. The services. Hosted feature services on our ArcGIS Online organisation (services8.arcgis.com/X84q166Srnyl4JMV), the ArcGIS Velocity stream services on us4-iot.arcgis.com, Esri's basemap tile services, the World geocoder, and a handful of third-party public services the WebMap references (WFIGS on services3, CAL FIRE's own portal). Each has its own authentication story and its own request budget, and the chapter returns to both repeatedly.

3. The SDK in the browser. @arcgis/core 5.x plus the @arcgis/map-components web components, pinned together in package.json. The SDK is how the browser talks to contracts one and two, and it is large enough that where it loads is itself an architectural decision.

The shape to hold onto: the browser asks our server for a credential, and that credential lets the SDK speak to every Esri endpoint directly. The WebMap item comes from ArcGIS Online, features from the hosted services, streams from Velocity over a WebSocket, tiles from the basemap servers. Image bytes and map tiles never pass through the BFF.

What we draw, what the portal draws​

The same split, seen from the screen. Every graphic the operator can see belongs to one owner, and the owner decides where a change lives. Hover the map below and let it tell you.

Who owns which pixelHover or click anything on the map — the panel names its owner and where a change lives.
Hover the map

Every visual on the real map belongs to the portal or to this repo. Move over one, or pick it below, and the panel tells you which — the first question on any map ticket.

◇ portal-owned · ◆ code-owned · ◈ shared. Click to pin a visual; click again to release it.

The one that fools everyone is the camera site circle. It looks like ours because it sits under our arrow, but its size, colour and label are authored on the feature service. If someone asks for "bigger camera dots", the answer is a portal edit.

How the code is shaped​

Roughly forty-five source files import from @arcgis/core, and they fall into three tiers. The map core is components/organisms/TileView/FeatureMap/FeatureMap.tsx, which is mostly orchestration, and the hooks in hooks/featureMap/, one concern per file. The pure utilities in util/map/ hold geometry, layer factories, the WebMap layer catalog and Velocity discovery, and are written so that most of them can be unit-tested without a WebGL view. The secondary consumers are features that draw on the map without owning it: alerts, locate-on-map, what3words, the PeakFinder companion. Those reach the SDK through exactly one dynamic import boundary, for reasons the next page explains.

State never lives in ArcGIS objects. The view and the map are held in mapStore as opaque references; everything the app knows about cameras lives in the Zustand stores you met in the state chapter, and the map is a projection of them. That single rule is what makes the map replaceable: the Velocity source switch, documented later, swaps out the entire rendering path without any store noticing.

How this chapter is organised​

Read in order the first time. Each page opens with the problem it solves and closes with where to go next, so you can also drop into the page you need.

  1. Loading Esri Without Paying Twice — bundling, SSR, the single lazy boundary, and the SDK-level configuration that runs before any map exists.
  2. The Token Handshake — how a private WebMap earns a credential, from Key Vault to the WebSocket query string.
  3. One WebMap, One View, One Lifetime — the singleton map, the boot sequence, and the navigation constraints.
  4. Every Layer Has an Owner — the taxonomy of layers on the map and the drawing order between them.
  5. The Parking Lot — lazy layer loading, the Layers Menu pipeline, and role gating.
  6. Icons Without Image Files — renderers, generated SVGs, CIM symbols, Arcade, and the AI pulse symbol.
  7. From Poll to Pixel — the real-time update pipeline and the edit discipline behind it.
  8. When the AI Speaks — how a detection becomes a red, pulsing arrow, and who is allowed to see it.
  9. Streams, Beams, and the Handoff — ArcGIS Velocity: discovery, the source switch, and the persisted warm-start.
  10. Writing Back — the other direction: how the backend feeds Esri through two Event Hubs and one REST client, and which writer owns which service.
  11. Hit Tests and the Click Budget — hover, click, tap, pick modes, popups and callouts.
  12. Two Filters, Two Properties — definition expressions versus layer-view filters, and the area scope.
  13. Drawing on Top — graphics layers, markers, the alert capture, geocoding and the Esri widgets.
  14. The Request Budget — rate limits, render cost, bundle cost, and the telemetry that proves it.
  15. Working Without Esri Watching — local setup, Jest and Storybook strategy, and debugging recipes.
  16. When the Map Is Wrong — symptom-first troubleshooting and the portal-side change checklist.
  17. Glossary and File Map — the vocabulary, the constants, and which file owns what.

Wrapping up​

Three contracts: a WebMap we curate, services we query under a request budget, and an SDK we load deliberately. Every graphic has an owner, and the owner tells you whether a change is a portal edit or a pull request. The map is a projection of the stores, never a store itself.

Next: Loading Esri Without Paying Twice.