Design

Architecture, tech stack, and local development setup

Key Design Decisions

Why two API styles?

Google-compatible (/directions/v2:computeRoutes) lets teams migrate from Google Routes API by changing only the base URL. RESTful routes (/v1/routes) adds statefulness, async processing, and webhooks for production use cases. Both hit the same enrichment pipeline.

Why this resource design?

We adopted industry best practices: ULID-prefixed IDs (route_), an object field on every resource, idempotency keys, consistent error envelopes, and a processing/complete/failed state machine.

Why physics enrichment?

Google Routes API tells you distance and duration - but not road grade, curvature, or fuel consumption. For a 36-ton semi on a 6% grade, fuel burn can be 3× higher than flat road. Motion fills that gap using real elevation models and road-load physics equations.

Why cursor-based pagination?

Telemetry segments can number in the hundreds. We use cursor-based pagination with hasMore/nextCursor for predictable performance. Offset pagination would be fragile for large segment lists.

Architecture

Motion is a freight routing API built for hackathon speed and production-grade design. It wraps the open-source Valhalla routing engine and layers on physics-based enrichment computed from real USGS elevation data and road geometry.

Tech Stack

Layer	Technology	Purpose
Framework	FastAPI	Async Python web framework with automatic OpenAPI generation
Routing Engine	Valhalla	Open-source turn-by-turn routing with truck costing model
Database	PostgreSQL + asyncpg	Route persistence, events, zone polygons
Cache	Redis	Request deduplication, route caching, idempotency keys
Elevation	USGS EPQS	Real elevation data for grade computation
Migrations	Alembic	Database schema migrations
Validation	Pydantic v2	Request/response schema validation
Containerization	Docker Compose	One-command setup for all services

Local Development

Prerequisites: Docker and Docker Compose installed.

1. Clone and start

   git clone https://github.com/r-thak/motion.git
   cd motion
   docker compose up -d
   

   This starts PostgreSQL, Redis, Valhalla, and the Motion API on port 8000.

2. Verify

   curl http://localhost:8000/health
   # {"status": "ok"}
   
3. Run without Docker (optional)

   cd api
   pip install -e .
   python dev_server.py --real
   

   Requires PostgreSQL and Redis running separately.

Running Tests

cd api
python test_runner.py