The WCS Event Navigator & Packing Orchestrator

I am building an autonomous event logistics and preparation agent that eliminates the fragmented chore of planning for dance conventions.

Comment

Inspiration

West Coast Swing dance is a smooth, elastic partner dance characterized by its distinctive "slot" movement and immense musical improvisational freedom. I have been dancing and attending WCS events since 2022. Attending a dance convention is somewhat like college where you can sleep, eat, study, or party and choose two—except at a dance event, your choices are usually sleep, workshops, competing, or social dancing.

Often you will go to an event and find out you missed a workshop or that you should have scheduled your flights at a different time because of the event schedule. Again, it is not impossible to do, but it is a meticulous task to go to the event page, figure out the schedule, and coordinate that with purchasing the correct flights, making it surprisingly error-prone. Furthermore, surprisingly few hotel ballrooms actually have Wi-Fi, so loading a PDF schedule on the event website often fails. While you can download it ahead of time, the idea of my project was to build an intelligent assistant that automates these exact pain points.

What it does

When designing the WCS Navigator API for personalized dance event scheduling, we ultimately opted for a stateless, in-memory architecture. Our approach utilized zero database dependencies (no PostgreSQL, no Redis, no Firestore) and zero disk writes (no /tmp scratch files or filesystem container mounts). As a result, every byte of data—from raw multi-page convention PDF schedules and URL scrapings to the generated RFC 5545 .ics calendar files—is ingested, processed, and streamed entirely within memory via standard HTTP request/response lifecycles.

To achieve production reliability, dynamic arrival adaptations, transparent fallback capability, and a zero-friction UX, WCS Navigator operates across a modern multi-stage architecture:

  • Two-Pass Dual Gateway Architecture: Decouples schedule discovery (via Gemini-3.5-Flash or PyPDF) from constraint optimization, featuring a transparent fallback to client-side heuristics if the live backend is unreachable.
  • Pre-Flight Footprint Analysis: Dynamically evaluates the event timetable payload to generate a tactile, auto-advancing questionnaire tailored to the event's specific audition bands, parallel tracks, and headliners.
  • Dynamic Rule Engine & Buffer Math: Deterministically calculates safe travel buffers, adjusting flight targets and staging times based on dancer inputs like local commuting or pre-convention intensive registrations.
  • Real-Time Taskmaker Debug Inspector: Guarantees "Explainability First" by providing a four-tab dashboard to audit service telemetry, active processing engines, and step-by-step rule justifications.
  • Event-Based Local Transit Feed: Combines verified host venue logistics with a customizable, chronological schedule feed that supports one-click .ics and Markdown .md exports.

Search Omnibox & Custom Schedule Ingestion Dropzone

How we built it

1. Two-Pass Dual Gateway Pipeline

WCS Navigator decouples schedule discovery from schedule optimization through a hybrid client/backend execution pipeline:

sequenceDiagram
    autonumber
    participant SPA as React SPA (Frontend)
    participant GW as Dual Gateway Services
    participant API as FastAPI / Gemini-3.5-Flash Backend
    participant Heuristic as Client Heuristic / Rule Engine

    Note over SPA,API: Stage 1 Schedule Discovery
    SPA->>GW: POST /api/v1/discover (PDF File / Event URL)
    alt Live Gateway Connected
        GW->>API: Ingest & Parse via Gemini-3.5-Flash / PyPDF
        API-->>SPA: DiscoveryResponse (Taxonomy & Footprint)
    else Live Gateway Offline / Unreachable
        GW->>Heuristic: Trigger Client Heuristic Extractor
        Heuristic-->>SPA: Fallback Discovery & Suggested Questions
        Note over SPA: GatewayFallbackBanner Notifies User
    end

    Note over SPA,API: Stage 2 Constraint Optimization & Itinerary Generation
    SPA->>GW: POST /api/v1/generate (Questionnaire Answers)
    alt Live Backend Optimization
        GW->>API: Constraint Optimization & Schedule Stream
        API-->>SPA: GenerateResponse (.ics & Decision Trace)
    else Offline Rule Engine
        GW->>Heuristic: Execute scheduleRuleEngine.ts
        Heuristic-->>SPA: Adapted Decision Trace & Local .ics Stream
    end
  • Stage 1 Discovery (/api/v1/discover): Fast timetable extraction utilizing Gemini-3.5-Flash, PyPDF, or client heuristic extractors to build the event footprint (audition bands, parallel track streams, headlining champions, and airport logistics).
  • Stage 2 Generation (/api/v1/generate): Constraint-optimized schedule synthesis, returning personalized RFC 5545 .ics streams and mobile Markdown (.md) itineraries.
  • Transparent Gateway Fallback: If the live FastAPI backend is offline or unreachable, the application smoothly transitions using GatewayFallbackBanner to client-side heuristic extraction without disrupting user workflow.

2. Pre-Flight Footprint Analysis & Dynamic Questionnaire

Rather than presenting dancers with a generic survey, the agent evaluates the event timetable payload dynamically before generating interactive question steps:

export function analyzeEventFootprint(
  eventName: string,
  discovery?: DiscoveryResponse
): DynamicQuestionStep[] {
  // 1. Evaluate Audition Tiers & Division prerequisite gates
  // 2. Isolate Parallel Workshop Track themes
  // 3. Extract Headlining Champion Instructors scheduled for the weekend
  // 4. Determine Host Venue Airport Transit conditions & touchdown targets
  return [personaStep, trackStep, instructorStep, arrivalStep];
}

Dynamic Card Questionnaire with Tactile Selection

  • Audition Bands: Events with audition requirements (e.g., Boogie by the Bay Level 4/5) ask for tier placement.
  • Parallel Tracks: Classes are filtered by distinct workshop streams (e.g., Footwork & Connection, Musicality, Momentum Flow).
  • Fluid Auto-Advancing: Selecting any option highlights the card with a cyan glow and automatically advances to the next step after 180ms. Dancers can also skip individual questions or click "Skip All & Generate Itinerary" to immediately inspect their schedule.

3. Dynamic Rule Engine & Arrival Buffer Mathematics

The schedule rule engine (scheduleRuleEngine.ts) deterministically computes travel buffers and adjusts flight deadlines based on dancer choices:

export function adaptTraceToUserPreferences(
  baseTrace: AgentDecisionTrace,
  answers: Record<string, QuestionAnswerValue>,
  eventName: string = 'WCS Event'
): AgentDecisionTrace {
  // Evaluates arrival target & intensive registrations
  if (isLocalCommute) {
    calculatedArrivalDeadline = 'Local Commute (Drive-In)';
    calculatedStagingTime = '5:15 PM Friday';
  } else if (hasIntensive) {
    calculatedArrivalDeadline = '12:00 PM Friday';
    calculatedStagingTime = '1:45 PM Friday';
  } else if (isEveningArrival) {
    calculatedArrivalDeadline = '6:30 PM Friday';
    calculatedStagingTime = '8:00 PM Friday';
  }
  // Recalculates backward staging buffer: Transit + Hotel Settle + Shoe Check & Warmup
  return updatedTrace;
}
  • Local Commuter (arrival: "local"): Sets target to Local Commute (Drive-In) and buffer step to Local Hotel / Venue Arrival Buffer (4:15 PM), eliminating unnecessary airport flight transit calculations.
  • Pre-Convention Intensive Attendees (intensive: "yes"): Shifts safe flight touchdown target to 12:00 PM Friday to accommodate 2:00 PM pre-convention masterclasses.
  • Friday Evening Arrivals (arrival: "evening"): Adjusts flight landing target to 6:30 PM Friday and staging call to 8:00 PM Friday.
  • Zero-Assumption Dance Role Contract: Dance role (lead, follow, switch) remains strictly empty/unspecified unless explicitly chosen by the user, avoiding unconfirmed role assumptions.

4. Real-Time Taskmaker Debug Inspector (DecisionDebugInspector)

To ensure complete transparency and satisfy WCS Navigator's Explainability First requirement, the interface incorporates a four-tab real-time debug inspector:

Real-Time Decision Logic & Taskmaker Debug Inspector

  1. 🎯 Confirmed Inputs & Persona Extraction: Displays extracted competitor divisions, explicit or universal dance roles, computed arrival targets, and raw questionnaire answer mappings.
  2. ⚡ Gateway & Engine Telemetry (ServiceTelemetry): Tracks real-time service endpoints (e.g., /api/v1/discover, /api/v1/generate), execution latency (durationMs), HTTP response statuses (e.g., 200 OK), active processing engine (FastAPI / Gemini-3.5-Flash vs. Client Rule Engine), and collapsible request/response payloads.
  3. 🔍 Rule Engine Filtering Audit Matrix: Step-by-step human-readable justification matrix listing every session evaluated, showing inclusion (✅ Included) or filtering (⛔ Filtered Out) status alongside specific rule reasons.
  4. 📦 Raw JSON Schemas: Interactive schema inspection and one-click clipboard export for DiscoveryResponse, AgentDecisionTrace, and FlightBuffer structures.

5. Event-Based Local Transit & Chronological Schedule Feed

Generic countdown math is paired with verified host venue logistics:

const EVENT_LOGISTICS_MAP = {
  'boogie-by-the-bay': {
    venueName: 'Hyatt Regency San Francisco Airport (Burlingame, CA)',
    primaryAirport: 'SFO — 5 mins away',
    transitTip: 'Complimentary 24/7 Hyatt Airport Shuttle departs every 15-20 mins. No rental car needed.',
    baggageAndCheckin: 'Complimentary bell desk luggage holding prior to 3:00 PM check-in; 3rd-floor atrium connects directly to Grand Ballroom.',
    travelBuffer: 'Target SFO landing by 2:30 PM Friday for zero-rush ballroom check-in before evening workshops.'
  }
};

Unified Chronological Schedule & Action Bar Export

  • Scannable Session Cards: Purely focused on Title, Time (Clock), Location (MapPin), and Category Badges (Workshops, Competitions, Socials).
  • Custom Schedule Persistence: Dancers can toggle individual sessions on/off or reset back to the AI plan.
  • One-Click Exports: Download .ics calendar files directly for Apple/Google Calendar or .md Markdown files for offline mobile viewing.

Challenges we ran into

  • Heterogeneous & Unstructured Convention Timetables: Every WCS event publishes schedules in wildly different formats (multi-column flyers, graphic-heavy PDFs, image tables, unstructured HTML). We engineered robust pre-processing with PyPDF and multi-modal Gemini prompting combined with heuristic fallbacks.
  • Hotel Ballroom Zero-Connectivity Realities: Convention basements and hotel ballrooms often lack reliable cellular service and Wi-Fi. Building a zero-dependency client-side heuristic engine was essential to guarantee that dancers always have access to schedule filtering and .ics generation offline.
  • Dynamic Arrival & Transit Buffer Math: Ensuring calculated flight arrival deadlines correctly factored in rideshare times, hotel bell desk luggage holding, wardrobe changes, and physical warmup buffers without arbitrary math.
  • Dance Role Agnosticism: Preventing the AI from making premature assumptions about Lead / Follow / Switch roles, preserving dancer autonomy until explicit input.

Accomplishments that we're proud of

  • Stateless Sub-Second In-Memory Guarantee: Full ingestion, parsing, constraint solving, and .ics streaming with zero persistent database dependencies and zero disk writes.
  • Explainability First Architecture: Building the 4-tab DecisionDebugInspector that gives users and developers 100% visibility into AI reasoning, latency metrics, engine status, and rule inclusion/exclusion matrices.
  • Tactile, Frictionless UI: Creating the auto-advancing 180ms card questionnaire that feels responsive and intuitive.
  • Universal Export Parity: Instant streaming of RFC 5545 compliant .ics calendar files with 15-minute reminders for Apple Calendar, Google Calendar, and Outlook, alongside offline Markdown .md itineraries.
  • Seamless Dual-Gateway Resilience: Zero-downtime client-side fallback when backend connections are unavailable.

What we learned

  • Neuro-Symbolic Synergy (LLMs + Rule Engines): LLMs excel at fuzzy perception, multi-modal ingestion, and unstructured taxonomy discovery, while deterministic rule engines excel at strict constraint satisfaction, time math, and calendar compliance. Blending both created a resilient, hallucination-free application.
  • The Power of Explainability: Providing dancers with the exact justification for why a session was scheduled or filtered out builds immense trust compared to opaque black-box AI generators.
  • Designing for Harsh Venue Environments: Treating offline fallback not as an edge case but as a core design priority makes web applications vastly more dependable in real-world convention scenarios.

What's next for The WCS Event Navigator & Packing Orchestrator

  • On-Device Gemma for Local Schema Validation & Sanitation: Deploying lightweight, open Google Gemma models (e.g., Gemma 2B via WebGPU / local edge runtime) to perform on-device PDF/text sanitation, validate structured JSON schemas locally, and filter noisy timetable extractions before dispatching upstream API requests.
  • Expanding Beyond WCS to Multi-Track Tech & Industry Events: Generalizing the two-pass footprint engine to support broader categories of multi-track conventions—including tech conferences, developer summits (parallel breakout tracks, keynote vs. lab conflicts, speaker prioritizations), academic symposiums, and hackathons.
  • Packing List Orchestrator: Generating customized packing checklists based on weekend theme nights (Glow Socials, Gala Cocktails, Athleisure) and division wardrobe requirements.
  • Live WSDC Points & Competitor Lookup: Integrating WSDC registry data to automatically recommend division placements and Jack & Jill tier eligibility.
  • Multi-Dancer Group & Roommate Syncing: Enabling dance groups and hotel room shares to coordinate flight arrivals and shared social itineraries.
  • Live Schedule Push & Contest Call Alerts: PWA push notifications alerting competitors when their division staging call is called to the floor.

Built With

Share this project:

Updates

Submission history