# ShiftRunner

> Hyper-local, zero-inflation walking food courier coordination system for frontline shift workers with strictly timed 30-minute breaks (anchored at 5161 South Cobb Dr, Smyrna, GA).

ShiftRunner coordinates batch pedestrian food runs across adjacent restaurant stops within a 1,600-foot walking radius. It eliminates third-party menu price inflation, preserves 100% of employee loyalty app rewards points, and provides a 3-second "Fast Dock" for ordering via client-side compressed screenshots (<90KB) or zero-cost browser voice dictation ($0.00).

## Core Documentation & Standards

- [Product Soul & Manifesto](SOUL.md): Core operating tenets, 30-minute break empathy, human personas, and anti-goals.
- [Design System & UI Tokens](DESIGN.md): The 60-30-10 color constitution, touch ergonomics (>=44px), custom keyframe micro-animations, and cashier modal tokens.
- [User Journeys & Edge Cases](USER_JOURNEYS_AND_EDGE_CASES.md): Full Mermaid sequence diagrams, Fast-Dock decision trees, kitchen failure state machines, and cashier verification flows.
- [Engineering Log & Architecture](DEVLOG.md): Chronological development history, architectural decisions, and trade-off analyses.
- [Developer Guide & State Architecture](AGENT_GUIDE.md): Codebase layout, in-browser relational database schemas, and rules for token-efficient agent modifications.
- [Full Consolidated Context](llms-full.txt): Complete consolidated single-file context for LLMs with full TypeScript types, schemas, and operational workflows.

## Technology Stack & Architecture

- **Frontend Core:** React 19, TypeScript 5, Vite 8, Tailwind CSS v4.
- **Client State / Relational Engine:** In-browser relational database persisted to `localStorage` (`profiles`, `restaurants`, `runs`, `foodRequests`, `requestEvents`, `chatMessages`).
- **Sync / Database Relay:** Optional Firestore live sync (`firebaseSync.ts`) and Supabase schema exporter for production migrations.
- **Fast Dock Engine (`src/fastOrder.ts`):**
  - **In-Memory Canvas Resizer:** Downscales 3MB–5MB phone screenshots to 75–90KB JPEGs in <20ms for instant transmission over weak breakroom cellular connections.
  - **Browser Web Speech API:** Client-side zero-cost voice dictation with real-time waveform audio pulse.
  - **Entity Extraction:** Heuristic regex parsing ($0 cost) + optional Gemini 2.5 Flash multimodal vision extraction (~$0.00002/order).
  - **Permanent Defaults:** Automatically saves and restores Name, Phone, Delivery Spot, and preferred Tip.
- **Accounting Architecture:** Strict integer-cents model (`runner_fee_cents = 250`, `estimated_subtotal_cents`, `actual_subtotal_cents`) to eliminate floating-point rounding errors.
- **Deployment Platform:** Cloudflare Pages & Cloudflare Workers Static Assets with Node 22 (`wrangler.jsonc`, `.nvmrc`).

## Real-World Smyrna Walking Corridor (5161 S Cobb Dr)

1. **Chipotle Mexican Grill:** 150 ft, 1 min walk (Rack pickup, Chipotle Rewards).
2. **Wendy's:** 400 ft, 2 min walk (Counter/App check-in, Wendy's Points).
3. **Zaxby's:** 600 ft, 3 min walk (Counter pickup, Zax Club).
4. **Arby's:** 1,000 ft, 3 min walk (Counter pickup, Arby's Rewards).
5. **Dunkin':** 400 ft, 2 min walk (Shelf rack, Dunkin' Rewards).
6. **Chicago Pizza & Sports Grille:** 1,600 ft, 6 min walk (Counter code).
7. **Bojangles:** 800 ft, 4 min walk (Counter pickup).
8. **McDonald's:** 900 ft, 6 min walk (Counter/App code).
9. **Monterrey Mexican:** 1,200 ft, 9 min walk.
10. **Dumpling Crown:** 1,400 ft, 11 min walk.
*Note: Subway is permanently deactivated (`is_active: false`).*

## Key Codebase Locations

- [`src/types.ts`](src/types.ts): Canonical TypeScript interfaces and domain schemas.
- [`src/fastOrder.ts`](src/fastOrder.ts): Canvas image compression, voice dictation, and order extraction utilities.
- [`src/mockData.ts`](src/mockData.ts): Seed data, profiles, and Smyrna restaurant locations.
- [`src/App.tsx`](src/App.tsx): Primary reactive full-stack simulation interface and views.