Cartographer

Ruby on Rails app that finds viable routes for the CHIditarod, based on customizable criteria like leg length, overall race length, etc.

Runtime Environment

Variable Name	Purpose
GOOGLE_API_KEY	Google Cloud Platform API key with access to the APIs listed below.
MOCK_MAP	When true, use mock data instead of calling Google APIs. Useful for local development without an API key.

Google API Setup

Your Google Cloud Platform account and associated API key must have access to the following APIs:

• Distance Matrix API
• Geocoding API
• Static Maps API

Developer Setup

Tested on macOS Sequoia 15.1.1.

Prerequisites

• Xcode, Docker, Homebrew, Node.js (for the frontend)

Install rbenv & Ruby

brew install rbenv
rbenv install $(cat .ruby-version)
gem install bundler

Install Gems

brew install libffi libpq

bundle config --local build.ffi --with-ldflags="-L/opt/homebrew/opt/libffi/lib"
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/opt/homebrew/opt/libffi/lib/pkgconfig"

bundle config --local build.pg --with-opt-dir="/opt/homebrew/opt/libpq"
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/opt/homebrew/opt/libpq/lib/pkgconfig"

bundle install

Install Frontend Dependencies

cd frontend && npm install

Database Setup

Start the PostgreSQL container and set up the database:

docker compose up -d db
bundle exec rails db:create db:migrate
bundle exec rake db:seed       # optional: seeds sample locations

Booting the App Locally

You need two processes running — the Rails API server and the Vite dev server.

1. Start Rails (API)

Without a Google API key (mock mode):

MOCK_MAP=true bundle exec rails server

With a real Google API key:

GOOGLE_API_KEY=your-key-here bundle exec rails server

Rails starts on http://localhost:3000.

2. Start Vite (Frontend)

cd frontend && npm run dev

Vite starts on http://localhost:5173 and proxies /api requests to Rails.

Open the App

Navigate to http://localhost:5173 in your browser.

Running Tests

RSpec (Backend)

bundle exec rspec

Playwright (E2E)

cd e2e && npx playwright test --reporter=list

Tests are organized into two projects:

• seeded (tests/seeded/) — Tests that reset + seed the DB before each test
• fresh (tests/fresh/) — Tests that reset the DB and create their own data

DB management is handled automatically per-test via fixtures. No manual seeding/cleaning needed.

cd e2e && npx playwright test --project=seeded   # run only seeded tests
cd e2e && npx playwright test --project=fresh     # run only fresh tests

Frontend Build Check

cd frontend && npm run build

Usage via Rails Console

The web UI handles all of the below, but you can also use the Rails console directly.

Seed

bundle exec rake db:seed
GOOGLE_API_KEY=... bundle exec rails c

Generate Legs using Google Maps API

BulkLegCreator.perform_now(Location.pluck(:id))

Generate Routes

RouteGenerator.call(Race.first)
winners = Route.complete
puts winners.map(&:to_csv)
puts winners.map(&:to_s)

selected = winners.select { |r| r.name != nil }
selected.map(&:to_csv)

Geocode Locations using Google Maps API

GeocodeLocationJob.perform_now(Location.pluck(:id))

Create Route Maps

After selecting and naming routes, generate maps via the Google Maps API:

names = [
  [771,"A"],[778,"H"],[806,"J"],[809,"K"],[816,"L"],[890,"G"],
  [931,"I"],[991,"D"],[1013,"B"],[1051,"C"],[1058,"E"],[1134,"F"]
]

names.each do |n|
  r = Route.find(n[0])
  r.update!(name: n[1])
  puts "Route ID #{r.id} now has name #{r.name}"
end

Then visit routes in the browser:

http://localhost:3000/races/3/routes/771

Clean Up

Race.destroy_all; Route.destroy_all; Leg.destroy_all; Location.destroy_all; nil