Module 4 — Data into maps

The first three modules built the application’s foundation — authentication, the operational model, the role-aware UI shell. Module 4 makes the application spatial. Rails data flows out as GeoJSON; MapLibre renders it; the user sees a real map with clickable, styled features that reflect what’s in the database.

The module’s arc is small but substantive:

Lesson 1 — GeoJSON as Rails data. GeoJSON is the lingua franca of geographic data on the web. The lesson covers what it is, the FeatureCollection shape, and how to produce it from ActiveRecord — using to_geojson patterns, as_json overrides, and the eventual move to PostGIS-driven ST_AsGeoJSON for performance. By the end of the lesson, a Rails endpoint returns service area boundaries as valid GeoJSON.

Lesson 2 — Sources and layers. MapLibre’s two visual primitives. A source is the data (a URL or inline GeoJSON); a layer is the rendering instruction (fill colour, line width). Multiple layers can read from the same source, which is how polygons get both a fill and an outline. The lesson sets up the first source and layer pair, watches polygons appear on the map, and explores how layer order produces the visual stack.

Lesson 3 — Styling polygons. From “polygons appear” to “polygons look meaningful.” Paint properties — fill_color, fill_opacity, line_color, line_width — applied through MapLibre’s style API. The lesson introduces data-driven styling (colour by attribute) which becomes a major theme later in Module 6’s choropleth work.

Lesson 4 — Extracting a map component. Inline JavaScript and ad-hoc <div> setup work for a first map but don’t scale. The lesson refactors the map into a Phlex component (Vera::Map) with a clean DSL for sources and layers, plus a Stimulus controller that handles the lifecycle. This component becomes the foundation for every map in subsequent modules.

Lesson 5 — Depots as points. Adding a second source — depot locations as GeoJSON points. Different layer type (circle), different paint properties, but the same source-and-layer infrastructure. The lesson reinforces the pattern by applying it to a different geometry type, and the dispatch deck now shows both regions and locations together.

What this module produces

A working map view with both polygons (service area boundaries) and points (depot locations), styled and rendered cleanly through a reusable Phlex component. The data flows from PostGIS through Rails to GeoJSON to MapLibre, with each step worth understanding.

What this module sets up

• The Vera::Map component pattern that subsequent modules use for every map
• The source/layer/paint mental model that underpins later styling work
• The discipline of producing GeoJSON in the database (ST_AsGeoJSON) rather than building it in Ruby — a performance choice that pays off as data volumes grow