Skip to content
Event Route Optimiser Docs
version: 1.1.2-7

ERO Requirements

What was needed. Event Route Optimiser is an offline-first Progressive Web Application for festival attendees. It calculates optimal walking paths between stages, resolves schedule conflicts, and tells a user where to be and when to leave.

This document states the constraints the product must satisfy. The design that satisfies them is in ERO Architecture.

1. Operating environment

The product is designed for the conditions that actually exist on a festival site, not for a desk.

  1. Zero or degraded connectivity. Crowd density saturates mobile infrastructure. Network calls are unreliable side effects, never a precondition for the user interface to respond.
  2. Bright outdoor glare. The interface must stay legible in direct sunlight, which drives a high-contrast, dark-native palette.
  3. Small screens held one-handed. The layout must work from 320 pixels wide upward.
  4. Limited battery. Work happens on device, but must not poll or spin needlessly.

2. Functional requirements

  1. Ingest a published line-up. Import festival, stage, day, and act data from a Clashfinder event and store it locally.
  2. Detect clashes. Identify overlapping set times across the acts a user has highlighted.
  3. Compute walking routes. Calculate travel time between consecutive acts using the site distance matrix, and recommend an exact departure time that minimises missed music.
  4. Answer now and next. Report the act currently playing, the next act, and the transition time between their stages, calculated entirely on device.
  5. Accept local overrides. A user must be able to adjust times and stages for last-minute changes, and those local edits must survive every subsequent synchronisation.
  6. Synchronise opportunistically. Queue changes while offline and push them automatically when connectivity returns.

3. Data requirements

  1. The client datastore and the edge datastore must maintain structural parity, so that synchronisation is a merge and never a translation.
  2. Master schedule data, meaning festivals, stages, and act times, is read-only on the client.
  3. Personal data, meaning highlighted acts, priorities, and overrides, is owned by the client and wins on conflict.
  4. Every record carries a synchronisation state so that pending work is never lost.

The concrete schemas and payloads are in ERO Reference.

4. Identity and privacy requirements

  1. Microsoft Entra External ID is the identity provider, federating to Google, Apple, Facebook, and Microsoft.
  2. Initial sign-in requests only the openid claim. No name, email address, or telephone number is collected at first sign-in.
  3. Any additional scope requires a documented purpose and is requested through progressive just-in-time consent at the point the feature needs it.
  4. Tokens are validated at the Cloudflare edge before any API access is granted.
  5. Local development must work with no network and no cloud identity dependency.

These derive from AG-ID-001 and AG-ID-002 in Platform Requirements.

5. Client platform policy

Client directories are named after the platform they target. app versus web expresses no platform boundary and must not be reintroduced.

apps/event-route-optimiser/
  web/       Astro offline-first PWA
  api/       Cloudflare Worker edge API
  mobile/    added only when the PWA cannot deliver a required capability
  shared/    extracted before any second client exists

5.1 The PWA is the mobile experience

Offline-first design, IndexedDB storage, service worker caching, and installability already target a phone with no connectivity. A mobile/ directory must not be created for parity alone. It is justified only by a capability the PWA cannot deliver, such as background notification delivery or deep operating system integration. Where that capability is a thin native wrapper around the same build output, mobile/ stays a shell and duplicates no application logic.

5.2 Shared logic is extracted before a second client

The Dexie schema, synchronisation engine, conflict resolution, now-and-next query, and routing engine must have exactly one implementation. Before any second client exists, that logic moves to shared/.

This ordering is not a preference. Duplicating a synchronisation engine that relies on logical timestamps and version vectors gives the same user different answers on different devices. Extraction must happen before the second client is created, never afterwards.

6. Accessibility and responsiveness

  • Body text contrast must meet WCAG AA.
  • Tap targets must maintain mobile-friendly sizing.
  • The typography scale must stay readable from 320 pixels wide through desktop widths.

7. Platform standards

ERO is an application on the Synkronyx platform and inherits every control in Platform Requirements. The standards that bear most directly on this product are AG-ARC-001 local-first reads and mutations, AG-ARC-002 interactive behaviour in React with Astro as the shell, AG-SYNC-001 conflict resolution rules, and AG-EDGE-001 Workers with Hono and D1.