TanStack Start Web App

Our primary user experience lives in a TanStack Start application that blends conversational workflows, guided offer creation, and real-time data pulled from Convex and our Hono services API. This page outlines how the frontend is wired together so you can understand the guarantees behind each screen.

High-Level Flow

flowchart LR
    User["Agent or Buyer"] --> UI["FinalOffer Web App<br>TanStack Start"]
    UI --> Router["TanStack Router<br>+ File-based Routes"]
    Router --> Loaders["Route Loaders<br>+ Server Functions"]
    Loaders --> Convex["Convex Queries & Mutations"]
    Loaders --> VoiceTools["Voice Agent Hooks<br>(ElevenLabs)"]
    Router --> UIState["Tailwind + shadcn/ui Components"]
    UI --> Auth["WorkOS AuthKit<br>Hosted Login"]
    UI --> Services["Services API<br>(Hono on Cloudflare Workers)"]
    Services --> CFWorkers["Cloudflare Workers<br>Firecrawl Orchestration"]
    Convex <---> Cache["Realtime Store<br>Optimistic Updates"]
    Services --> DataBackfill["Property & Contact Cache"]
    CFWorkers --> External["Firecrawl / Workers AI"]

The frontend is intentionally thin but orchestrated: route loaders coordinate Convex queries, while server functions marshal calls to the Services API so the UI never needs to embed scraping credentials. ElevenLabs and call tooling remain optional helpers controlled through Convex mutations.

Key Capabilities

• Contextual Routing – TanStack Start powers file-based routing with nested layouts, so flows like property insights → offer drafting share data via loader context and strongly typed hooks.
• Realtime Convex Data – We subscribe to listings, offers, and call transcripts with Convex's reactive hooks, enabling optimistic updates for property comparisons and agent coaching widgets.
• Tooling Shortcuts – UI components expose quick actions (create offer, request voice recap) that trigger Convex mutations which in turn hit our Cloudflare Workers service or voice stack.
• Hosted Authentication – WorkOS AuthKit keeps sensitive sign-in flows outside our repo, while client-side helpers read the AuthKit session and pass service tokens to Convex.
• Operational Guardrails – Sentry instrumentation, feature flags, and toast-level feedback keep agents informed when background refreshes are happening or cache reads are served.

How We Build Pages

1. Route definition – apps/web/src/routes/** declares TanStack Start routes, co-locating loader logic with the UI. Loaders connect to Convex via generated clients so data types stay aligned across the stack.
2. UI composition – Pages stitch together Tailwind primitives, shadcn/ui components, and Carbon icons for accessibility and rapid iteration.
3. Data hooks – Convex queries stream data into components; actions use Convex mutations or TanStack server functions for SSR-friendly workflows.
4. Edge-aware fetches – Any call that needs property/contact enrichment uses a tiny server function wrapper that hits the Services API so secrets remain on the server.
5. Deployment – The TanStack Start app deploys on Vercel with streaming SSR enabled, taking advantage of caching headers while still hydrating instantly.

Supporting Systems

• Background refresh – Convex cron jobs trigger the Services API to keep listings fresh; UI surfaces when data is mid-refresh.
• Maps & geodata – Mapbox powers address validation and inline map components used in offer creation.
• Voice integrations – ElevenLabs agents hand back transcripts and next-step suggestions which appear inside the TanStack Start UI via Convex subscriptions.

This doc complements the backend-focused Services API write-up so you can trace every click from the browser through Convex and out to our Cloudflare Workers infrastructure.