gis

The Lego Principle — How Modern GIS Tools Actually Fit Together

The worst mental model for modern ArcGIS is thinking of it as one tool.

It's not. It's a brick system. Every piece has specific connectors. Every piece is designed to snap onto adjacent pieces in specific, documented ways. And once you can see those connectors clearly, you stop fighting the system and start composing it.

The bricks

Feature Layers are the data layer. The single source of truth. Lives in AGOL, has a schema, has an edit history, has access controls. Everything else pulls from it. One change in a Feature Layer propagates downstream automatically — to the Web Map, the Dashboard, the thin HTML app, the EB widget. This is the architecture that should underlie every data-driven tool, and almost always doesn't.

Web Maps are configuration layers. They don't hold data — they describe how to display it. Which Feature Layers. In what order. With what symbology, labels, and popups. Web Maps are portable — they open in Map Viewer, Experience Builder, the JS SDK, a mobile app. Configure once, display everywhere.

Experience Builder is the assembly layer. Takes Web Maps, Feature Layers, and widgets and arranges them into interactive applications without code. Excellent for 80% of use cases. The other 20% is where the next brick matters.

The ArcGIS JavaScript SDK is the custom layer. Direct access to every underlying capability. No pre-built UI. No configuration surface. You write the assembly. The ceiling is essentially unlimited, and AI makes it as accessible as EB configuration.

Vercel is the delivery layer. A thin HTML SDK app needs a live URL with HTTPS and a CDN. Vercel provides this in under 2 minutes, auto-deployed on every push, free for public repos.

AI is the instruction manual. It knows every brick, every connector, every edge case. You describe the outcome. It writes the assembly code.

How a complete build fits together

Concrete example — a shelter capacity tool built for disaster response:

Feature Layer: Shelter data, hosted in AGOL, private to org, updated daily via Python script from an internal source
Web Map: Displays the shelter layer with custom symbology — filled polygons, capacity-based sizing, click popups with intake numbers
Experience Builder: Map widget using the Web Map, List widget filtered by selected county, Chart widget showing capacity trend
SDK thin app: Field team version — offline-capable, custom UI, reads the same Feature Layer directly (no Web Map in the middle)
Vercel: SDK app deployed to shelters.vercel.app, embedded in EB via Embed widget with ?arcgis-auth-origin= for SSO passthrough
Python script: Scheduled daily — queries the source system, transforms, upserts to the Feature Layer
AI: Wrote the SDK app, the Python script, the custom popup configuration. One afternoon.

Every brick does one thing. Every brick connects to adjacent bricks via stable, documented connectors. Nothing is bespoke. When data changes — one Feature Layer edit. Everything downstream updates.

The connectors that matter

Feature Layer → Web Map: Add the layer item ID to the Web Map's operational layers. Configure symbology and popups in the Web Map. The Feature Layer stays neutral.

Web Map → Experience Builder: Add it as a data source. EB reads the layer configuration and exposes each layer as a widget source.

Feature Layer → SDK app: FeatureLayer({ portalItem: { id: "ITEM_ID" } }). Direct. No Web Map required.

SDK app → Experience Builder: The app lives at a URL. EB's Embed widget iframes it. Append ?arcgis-auth-origin=https://experience.arcgis.com to pass the SSO credential.

SDK app → Vercel: Push to GitHub. Vercel picks it up automatically.

Python → Feature Layer: FeatureLayer.edit_features() via the ArcGIS Python API. Or direct REST if Python isn't available.

These connectors are stable. They work the same way in every project. Learning them once means every future project runs faster than the last.

Where people get stuck

Treating EB as the ceiling. It's the floor for no-code tools. When EB can't do it, the SDK can. And the SDK is no longer harder — just different.

Building outside the Feature Layer system. CSV files as data sources. Shapefiles uploaded directly to Web Maps. Custom databases that bypass AGOL entirely. These break the single-source-of-truth model and create maintenance debt immediately.

One massive Web Map. Thirty layers, eight group layers, fifteen definition expressions. This is a maintenance nightmare. Multiple focused Web Maps reading from the same Feature Layers is always the right answer.

Popups on Web Maps instead of layer items. Configure popups on the Feature Layer item itself. Every Web Map that includes the layer inherits the popup. One change propagates everywhere. Configuring popups on the Web Map creates a fork you'll spend hours reconciling later.

The payoff

Once the bricks are correctly assembled, changes are surgical.

Update the data schema → change the Feature Layer, recheck popups. Redesign the UI → redeploy the SDK app to the same URL, the EB embed is unchanged. Add a new map view → create a new Web Map from existing Feature Layers, add it to EB. New field team tool → new SDK app, same Feature Layer, 20 minutes.

The work compounds. Every correctly-built Feature Layer is reusable. Every Web Map is a reusable configuration. Every SDK app is a template for the next variant.

This is the architecture that looks simple from the outside and took years to build from the inside. AI didn't change the architecture. It changed who could implement it.

GIS is a brick system with known connectors. Learn the connectors. The builds get faster every time.