Events, host venues, and fair procurement

This page describes public events (one-off gigs where trucks apply) and host venues (recurring locations that publish a weekly truck schedule). It also explains procurement models and how we try to reduce power imbalance between organizers with budgets and cash-strapped truck operators.

Data model (Convex)

  • publicEvents — Organizer-owned listings with time range, location text, and a procurement model. Draft events become visible only after Publish (status published).

  • publicEventApplications — A truck owner applies with an optional message and, depending on model, a bid / ask in cents. Bid amounts are shown only to the organizer in the management UI — they are not exposed on public event pages or in public API summaries.

  • hostVenues — A named place (brewery lot, campus, office park) with optional address/coordinates.

  • hostVenueSlots — Recurring weekday + time range + your food truck. Custodians may only attach trucks where foodTrucks.userId matches their account (same Square business tenant), so random operators cannot be listed without consent.

Open Graph / social previews

Dynamic preview images are generated for:

  • / — homepage (app/opengraph-image.tsx)

  • /trucks/[id] — truck profile

  • /events/[id] — public event

  • /venues/[id] — host venue

Canonical URLs and image links require a correct site origin. Set NEXT_PUBLIC_APP_URL in production (see Environment Variables).

After schema changes, deploy Convex before expecting sitemap or OG routes that query new tables to succeed in production.

Procurement models

Organizers choose one of three modes when creating an event:

fixed_stipend (recommended for operator fairness)

The organizer posts a guaranteed flat fee up front (in cents in the database; UI uses dollars). Trucks apply knowing exactly what is on the table — no bidding war, no race to the bottom.

budget_band

The organizer commits to a minimum and/or maximum budget band. Trucks may optionally state a desired compensation within that band; the amount is still organizer-only on the wire for listings (public pages do not list individual asks).

competitive_bids

Trucks submit a bid; the organizer compares offers privately. This can still pressure small vendors. The product keeps amounts off public pages so operators are not publicly undercutting each other in real time. We still recommend fixed stipend or budget band when the goal is predictable, fair pay.

Power dynamics (product stance)

Food truck owners are often margin-thin and time-constrained. Event organizers usually hold more leverage (access to crowd, permits, parking).

The platform bias is:

  1. Prefer transparent, upfront economics (fixed_stipend, clear budget_band).

  2. Keep bid/ask numbers private on the public site to avoid public auctions.

  3. Encourage organizers to post requirements (requirementsText) and realistic guest counts so trucks can self-screen before applying.

This is not legal or labor advice; it is a design direction for the software.

User flows

Organizer

  1. Sign in.

  2. Open Manage → Manage events.

  3. Create a draft (title, location name, times, procurement model, optional stipend/budget).

  4. Publish when ready — the event appears on /events and gains a shareable URL and OG image.

Applications are reviewed under Manage events → Applications for that event.

Truck operator

  1. Connect Square and register an active truck (existing flow).

  2. Open a public event on /events/[id].

  3. Submit an application (and bid where required).

Host venue custodian

  1. Sign in.

  2. Manage → Manage venues — create a venue and mark it public if it should appear on /venues.

  3. Add weekly slots only for trucks you operate (same business tenant).

Bootstrap and deploy checklist

When pulling new code:

  1. Run pnpm install at the repo root.

  2. In site-nextjs, run pnpm exec convex dev (local) or deploy Convex in CI so hostVenues, hostVenueSlots, publicEvents, and publicEventApplications exist in your deployment.

  3. Set NEXT_PUBLIC_APP_URL on Vercel (or your host) to the production origin so metadata, sitemaps, and social cards use absolute URLs.

See Getting Started and Convex Setup for the usual dev loop.

Future work (not implemented here)

  • Venue address geocoding and map embeds.

  • Multi-truck acceptance per event (today one organizer can accept multiple applications manually; closing the event is manual).

  • Truck-owner consent flow for third-party venues listing a truck they do not operate.

  • Payments / contracts — out of scope; this module is discovery + applications only.