Lesson 1 — What we’re building

The application we’ll build over the course of this tutorial is called Vera Dispatch Manager. It’s a field-service operations app — the kind of system that a national broadband installer, a utility maintenance company, or a logistics business uses to schedule technicians, dispatch vehicles, and manage jobs across a wide geography.

That domain is a deliberate choice. Field service is one of the genuine sweet spots for spatial software: every job has a location, every technician has a position that matters, every service area is a polygon, and every operational decision involves “what’s near what.” The problems are real and the queries aren’t contrived. By the time we’ve finished, the app will exercise every interesting capability of PostGIS and MapLibre.

The setting is Australia. The data uses real Australian Bureau of Statistics SA3 boundaries (about 360 polygons covering the whole country) for service areas. Job density is weighted by SA3 population, so the heavy traffic is in Sydney, Melbourne, Brisbane, Perth, and Adelaide, with thinner coverage through regional areas — exactly as you’d expect for a real national service business. We’ll generate synthetic but plausible data for everything else: technicians, depots, vehicles, jobs, customer sites.

The shape of what you’ll have built

By the end of Module 10, the application includes:

A dispatcher’s home view showing live job activity across a service region. Sortable, filterable, paginated. Click a job, get a detail panel. Click a service area on the map, drill into its data.

A manager’s national dashboard with a choropleth view of job density across all of Australia, response-time aggregations per region, and drilldown into specifics. Loading half a million job records efficiently — vector tiles served from PostGIS, indexes that actually do their job.

A field officer’s view scoped to their own work — today’s jobs, upcoming, recently completed. Map showing the next destination. Update job status from the field.

A drawing tool that lets a dispatcher define ad-hoc service zones by drawing polygons on the map. The drawn shapes save to PostGIS, persist across sessions, and become queryable areas — “show me jobs inside this zone I just drew.”

A real-time fleet view where technician GPS positions stream live across the map. Vehicles glide between locations. ETAs update. New jobs appear as they’re created. All powered by Action Cable broadcasts.

That’s the application’s surface. Underneath, you’ll have built about a dozen tables with proper foreign keys and spatial geometry columns, about half a million seeded job records, GiST indexes on the geometry columns, vector-tile-serving controllers, Action Cable channels, Pundit-shaped policies for role-based access, and a small but capable Phlex component library for the UI.

Three roles, one chassis

The application has three user roles: field officer, dispatcher, and manager. Each sees the same chassis — the same top bar, sidebar, visual identity — but with different navigation items and different data scope. A field officer sees their own work; a dispatcher sees their region; a manager sees everything.

This matters because role-aware UI is a real-world requirement most tutorials skip. We’ll build it from chapter 1, with a development-mode role switcher in the top bar that lets you experience the app from each perspective without logging out. Lesson 4 of this module covers the roles in more detail.

What it looks like

The visual style is what we’re calling the dispatch deck — an operations console aesthetic. Information density. Status colours (green for active, amber for delayed, red for issues). A dark sidebar that anchors the layout. A small accent strip at the very top of every page. It’s not the editorial-style typography you’d see on a content site or a marketing page; it’s closer to the rhythm of an air-traffic control screen or a fleet dispatch terminal.

You’ll build this incrementally. The starter app for chapter 1 ships the chassis pre-built — top bar, sidebar, layouts, authentication, seed users with each role, the visual styling. Maps and spatial features start being added in Module 2. We don’t expect you to construct the chassis from scratch; we expect you to build the spatial work that goes inside it.

What this isn’t

This isn’t a Phlex tutorial. We use Phlex extensively for the UI components, and there’s a separate tutorial — Phlex on Rails — that covers Phlex from the ground up. Here we’ll explain Phlex idioms as they come up but won’t unpack them in depth. If a chapter says “render Components::DataTable.new(rows: @jobs)” and you’ve never seen Phlex before, the syntax may surprise you, but you’ll be able to follow what it’s doing without difficulty. If you want a deeper foundation, the Phlex on Rails tutorial is the place.

This isn’t a Rails tutorial either. We assume you’ve built Rails applications before — controllers, views, ActiveRecord, basic Hotwire. We won’t explain what params[:id] means or how a controller maps to a route. If you’re comfortable with the basics of Rails, you’re the right reader.

It also isn’t a complete GIS course. PostGIS is a deep system; we cover what’s needed to build the application well, including some genuinely interesting territory around spatial indexing and query optimisation, but we don’t visit topographies, raster data, or projection mathematics in depth. By the end you’ll have a solid working understanding of geographic queries in PostGIS — enough to build serious applications and to know which references to reach for when you need more.

What it is

A practical, application-driven tutorial that builds something useful, teaches GIS as it goes, and shows what map work in Rails can look like when you stop fighting it. Two audiences are explicitly served, and the next lesson covers them.