Vendor Events

Module Definition

The domain root is the event series — an ongoing or seasonal vendor event that owns two child lists: its dates and its registered vendors. Vendors themselves are city-wide identities, reusable across series through per-series registration. The series is optionally tied to a facility; when it is, Facility View can map each date's registered vendors onto the facility's spaces and the public viewer renders "who is where this week." The module mirrors the Boards shape: a detail page whose children (dates, registrations) parallel a board's meetings and members.

Within Facility View this remains the third overlay shape — event-scoped, capability-anchored (activates where published series exist, regardless of viewerType), internally-owned data. Only the assignment (the spatial junction) lives on the Facility View side; everything else belongs to this module.

What is in scope

• Vendor identity (cms.Vendor) — city-wide, staff-authored.
• The event series (cms.VendorEventSeries) with its dates (cms.VendorEventDate) and vendor registrations (cms.VendorEventRegistration).
• The spatial junction (cms.VendorEventAssignment): date + vendor + facility space, authored in Facility View's admin surface.
• A Vendor Events module page in the my/ portal (Boards-style detail: dates + vendors as child sections).
• The public viewer surface: date-scoped vendor list ↔ space highlight on the facility map.

What is out of scope (for now)

• Vendor self-service — applications become pending registrations via Forms/workflow later; V1 is staff-managed.
• Registration, payments, or stall fees — no money movement, no Programs involvement.

1 · Data Model

Five cms tables, all human-edited and IAuditable. The series owns dates and registrations; the assignment joins a date row to a vendor and a space.

cms.Vendor — city-wide vendor identity

cms.VendorEventSeries — the event (domain root)

cms.VendorEventDate — a series date

cms.VendorEventRegistration — series ↔ vendor membership

cms.VendorEventAssignment — the spatial junction (Facility View side)

Constraints: unique (vendorEventDateId, facilitySpaceId) — one vendor per stall per date; a vendor may hold two stalls on a date. Cascade chain assignment → date → series; vendor and space FKs are Restrict so history survives.

Options considered

2 · Calendar Relationship

Dates are domain rows; the calendar is downstream. The integration is publish, not read: a series with a calendar target (VendorEventSeries.CalendarId, staff-set) pushes its dates through the calendar-publish service the way program sessions do — VendorEventCalendarSyncService, one source per series (sourceKey "vendorEventSeries-{id}"), reconciled on every series/date mutation — so the market appears on the calendar (and in Exchange) from the same domain truth the viewer renders. Domain → calendar, never calendar → domain.

Dates are day-only domain rows, so they publish as all-day events titled with the series name; cancelled dates come off the calendar (the domain viewer keeps showing the cancelled state), and an unpublished series — or a cleared/re-pointed target — has its footprint removed. The published rows are the calendar's discovery surface only: their sourceKey routes any tap in the City Viewer (city Calendar tab or facility Events tab) into the series' own date-scoped vendor view (?facility=N&tab=events&series=S&date=D deep link) — the domain view stays the destination, so publishing never costs the custom market UI. This sourceKey-routing pattern is reusable for any domain that publishes to the calendar (e.g. program sessions → registration).

3 · API & Endpoints

Routes — Vendor Events module (staff, in the my/ portal)

Routes — spatial mapping (Facility View admin surface)

Routes — public viewer

4 · User Interface

Vendor Events module page (my/ portal — Boards pattern)

• Series list → series detail (header/info card: name, facility, published) with two child sections, each rows + drawer forms: Dates (add/cancel/remove; bulk "add a weekly run" convenience) and Vendors (register from the city-wide list / withdraw).
• Vendors section — the city-wide vendor directory with add/edit drawers, on the same module page (list view), since registration picks from it.

Social media image (per series date, on the detail page)

• Each date row offers Social image — a drawer composing a post-ready PNG: header (series name + "Vendor Map — date") → numbered vendor list beside the floor-plan map (badges match list numbers), with the series image overlaid on the map's bottom corner opposite the list — an overlay sized by its own knob, not a reserved band, so the map keeps the full height. Platform pixel presets (1080×1080, 1080×1350, 1200×630, 1080×1920), drag/zoom/rotate map framing, aerial-underlay and facility-boundary toggles (indoor venues cover the underlay; outdoor boundaries are usually just parcel lines), list side + font-size knobs; Save as series default persists the layout so week N is one click. Outputs: copy/download PNG, generated alt text, and a plain-text caption carrying the full numbered vendor list — the caption is the real accessibility artifact (platform alt-text fields are short), and doubles as post copy.
• Rendering is entirely client-side canvas, all native draws. The map layer is the exportSafe floor-plan SVG (labels off, styles inlined, underlay inlined as a data URI); stall badges, header text, and the vendor list are drawn with the canvas API so rotation keeps badges upright and no server-side rasterizer dependency is taken on. Two rejected alternatives: a server-side renderer (.NET SVG rasterization is a heavy dependency for an image the browser can compose from data it already has) and staff-authored header/footer HTML bands rasterized via foreignObject snapshot — built first, then removed: the snapshot needs valid XHTML, inline-only styles, and CORS-readable images, a fragility class staff authoring can't be expected to satisfy. Fixed header text + one series image covers the actual need.
• Canvas-bound image bytes come through the API (underlay: GET facility/{id}/floor-map/{floor}/underlay/image; series image: GET vendor-events/{id}/image): the static host serves no CORS headers, so drawing its bytes would taint the canvas and break copy/download. Revisit if the static server ever ships Access-Control-Allow-Origin for /media.

v1 limits & anticipated asks

The governing constraint behind all of these: every element must be a native canvas draw from CORS-readable bytes — no arbitrary HTML (the foreignObject path was tried and removed, above). Within that, each ask below is tractable:

Facility View admin — spatial mapping only

• For a facility hosting published/unpublished series: the assignment editor — pick a series date (from its date rows), then a display list of that date's placements beside the facility's interactive floor plan, cross-highlighted (library-workspace pattern): a row focuses its space; a free space opens an add drawer pre-filled with that space, an occupied one jumps to its row. Add/edit opens a drawer (space + vendor); every action — add, edit, remove, copy-previous — persists immediately via the bulk-replace endpoint, no separate "save date" step. The drawer's vendor field can register an existing directory vendor or create a brand-new one inline (embeds the module's own vendor/registration forms) so a last-minute vendor never requires a trip to the Vendor Events page. Nothing else from this domain is administered here.

Public viewer

• Find — vendor search beside space search, mirroring the library's space + catalog composition: a mapped vendor is a search result carrying its upcoming dates as chips (the same shape as the library's edition chips); picking a date shows that date's stall and highlights it on the map.
• Events — a banner per published series into the date-scoped vendor view (date chips → vendor list ↔ stall highlight; cancelled dates flagged).
• Space detail — a "who's here" block on mapped spaces.
• Vendor cards (search results, event view, who's-here) render the vendor's image where one is set.

5 · Build Sequence

1. Schema reshape — add VendorEventDate + VendorEventRegistration, series facility → nullable, drop calendarSourceKey, re-key assignments to the date row. Replacement migration (tables were empty at reshape time).
2. API — module CRUD (series/dates/registrations), reworked assignment + public endpoints.
3. Portal — the Vendor Events module page; Facility View admin slims to the assignment editor.
4. PWA — consume the reshaped read (empty/cancelled dates render; drop the calendar sourceKey row-matching).

6 · Deferred