Lesson 2 — The two audiences

This tutorial is written for two audiences whose needs overlap but aren’t identical. Most chapters speak to both. A few chapters are more useful for one than the other, and you’ll get more from the tutorial if you know which one you are.

Audience A — Rails developers familiar with GIS

You’ve worked with maps before. Probably Leaflet. You know roughly what a tile is, why coordinates use latitude and longitude, what GeoJSON looks like. You may have used PostGIS — even if just adding a geometry column and writing one or two ST_Within queries. You’re not surprised by the term “SRID.” You don’t need an explanation of projections; you’ve picked which one to use before.

What you want from this tutorial is bridging knowledge. You’re comfortable with the spatial concepts but you’ve been writing imperative JavaScript to handle the map side, and the maintenance overhead of that code has worn thin. You’d like to see what it looks like to declare maps as Phlex components. You’d like to understand how MapLibre differs from Leaflet (it’s a fork of Mapbox GL, vector-tile- native, and significantly more capable for serious work). You’d like to see how Hotwire — Turbo morph, frames, streams — integrates with maps without you writing a thick layer of glue Stimulus.

For Audience A, the demo site at https://vera-demo.example.com is also a useful resource alongside this tutorial. The demo site shows finished features in isolation — here’s what hover styling looks like, here’s how a Turbo Frame popup works. You can copy patterns from there and adapt them. The tutorial is the slower, more thorough walk; the demo site is the reference shelf.

You can read this tutorial from chapter 1 or skip ahead. Module 1 is framing — useful but not technical. Module 2 covers setup; if you already have a Rails 8 + PostGIS environment running you can skim it. Module 3 is foundational PostGIS material; you might know most of it. Module 4 onward — where we connect data to maps and start interacting — is where the bridging knowledge lives, and that’s where you’ll likely spend most of your time.

Audience B — Rails developers new to GIS

You’ve built Rails applications. You know your way around ActiveRecord, controllers, views. You’re comfortable with Tailwind, with Stimulus, with basic Turbo. But spatial software is unfamiliar territory. When someone says “geometry column” you have a vague idea but you’ve never created one. You haven’t used PostGIS. You don’t know the difference between a tile and a layer. You’re not sure if lat comes before lng or after. The reason you’re here is that an upcoming project needs maps — or you’ve decided you want to build something with maps — and you’re starting from the beginning.

For Audience B, this tutorial is your foundational text. It introduces GIS concepts as they become relevant — usually one new concept per chapter, anchored to a working application feature so you immediately see why it matters.

The most important thing to know reading as Audience B: don’t skip chapters. The earlier modules introduce concepts that later modules build on. If you skip Module 3 (Geometry in PostgreSQL) because the title sounds dry, you’ll be lost in Module 4 (Data into maps) when we connect a Phlex map component to a geometry column you don’t have. Each chapter introduces small new pieces; cumulative skipping compounds.

You should also expect occasional moments of “wait, why does this work?” — particularly when something happens between Rails and the browser that involves spatial data. Spatial software has more moving parts than typical web work because there’s a database type, a serialisation format (GeoJSON), a JavaScript library, a tile server, and a coordinate system to coordinate. The tutorial makes these visible as we go, but the first time something clicks across that stack, take a moment to feel it. The clicking is real progress.

What you’ll need either way

Regardless of which audience you are, the tutorial assumes:

• Rails experience. You’ve built Rails apps. You know what a migration is, what a Phlex component is even if you haven’t used one, how ActiveRecord scopes work. The Phlex on Rails tutorial is worth working through first if you’ve never written a Phlex component.

• Comfort with the command line. You can run a Rails console, invoke rake tasks, edit files in a terminal-friendly editor. You’re not afraid of psql.

• A development environment. macOS or Linux is straightforward; Windows works through WSL. You’ll need PostgreSQL with PostGIS installed locally — Module 2 walks through this if it’s new.

• Patience for setup. The first chapter where you start coding involves installing PostGIS and configuring a Rails 8 project. Like any setup chapter, it’s the least exciting part of the tutorial. Stick with it; everything afterwards is more interesting.

Reading on a phone

This tutorial has chapters that go three thousand words and contain code blocks with line numbers. The Hugo site renders responsively and the code blocks scroll horizontally on small screens, but you’ll have a much better time reading at a desk with a real keyboard and a wide enough screen to put the tutorial side-by-side with your editor. The activities expect you to be at a working development environment, not on a train.

That said — Module 1 is all framing. If you’re reading this on a phone right now, you’re fine. Pick this up at the desk for Module 2.

One more thing

Before we move on, an honest note about pacing. The first three modules feel like setup. You won’t have a working map until Module 2 Lesson 3, and you won’t have data on a map until Module 4. If that feels slow, it is — deliberately. The reason for the pace is that every later chapter benefits from the foundations laid here. Module 7’s chapter on spatial indexing is much better when you already understand the geometry column, the GeoJSON pipeline, and the SRID convention. Skipping the foundations to “get to the interesting bit” makes the interesting bit harder, not easier.

Module 9 is where everything comes together — the live dispatch view with vehicles streaming across the map. The reward at that chapter is real, and it’s better when you’ve earned it.