Pathly

pathly_architecture_diagram

Inspiration

We wanted to make running feel less lonely and less repetitive. Most running apps are either utility-first or music-first. Pathly started from a simple question: what if a run felt like a live, intelligent podcast that reacted to your route, your pace, your surroundings, and your interruptions in real time?

Instead of just giving directions or tracking metrics, we wanted the experience to feel like two hosts, Maya and Theo, were actually running with you.

What It Does

Pathly is an English-first running companion that turns a workout into a live, content-first show.

During a run, the backend coordinates:

route generation
navigation-aware timing
local place context
curated news moments
interruption handling
reconnect-safe session continuity

The iOS frontend captures structured context such as location, motion, navigation state, and user actions. The backend decides what should happen next: who speaks, what content buckets are allowed, how long a turn should be, and when navigation or quiet mode should override normal show flow.

How We Built It

We split the system into a frontend and a backend with a contract-first design.

The backend was built around a typed service architecture in TypeScript and deployed online for real frontend integration. We implemented:

profile APIs
route generation APIs
session creation
websocket orchestration
session preference updates
route-aware turn planning
persistence and reconnect-safe checkpoints
Railway deployment for live testing

The system uses structured models for UserProfile, SessionPreferences, RouteCandidate, NavigationPayload, and session state. We also built adapters for:

Google Routes
Google Places
RSS ingestion
Gemini-based turn generation

Even where some integrations still use fallback behavior, the contract and orchestration layers are already wired so the frontend can develop against stable shapes.

Challenges We Faced

One challenge was making the backend match the evolving frontend/backend contract exactly. Small mismatches in field shape, response structure, or websocket payloads could break the iOS integration even when the core logic was correct.

Another challenge was balancing real-time orchestration with practical deployment constraints. We had to support:

live session updates over websocket
quiet mode and talk density overrides
navigation-aware suppression rules
reconnect-safe state recovery
a deployment target that could persist backend state reliably

We also spent time debugging production issues that were not product logic problems but deployment details, such as startup command mismatches, runtime environment differences, and response-shape failures that only appeared during end-to-end frontend testing.

What We Learned

We learned that for multimodal, real-time products, the contract layer is just as important as the model layer. A good AI experience is not only about generation quality; it is also about predictable interfaces, deterministic orchestration, and graceful recovery when the user interrupts or the session reconnects.

We also learned how much product quality depends on systems thinking. A route-aware companion is not just “LLM + maps.” It requires coordination across routing, navigation timing, persistence, websocket lifecycle, frontend state, and deployment reliability.