SurroundShow — Project Docs

Overview Features Flow Tech Roadmap Test results 🧪 Pair test plan

Overview

LiveBrand app of the LinkAll platform

Repo	microspaces/linkall (LinkAll platform — brand apps live under `apps/`)
Local	`C:/Users/AI/Repos/linkall`
Owner agent	`surroundshowdev`
Backend	Convex deployment `upbeat-capybara-284` — one shared schema, one deployment per brand, isolated data
Legacy	LinkAll8 multi-tenant ASP.NET (SiteId 1 = SurroundShow, SiteId 2 = FunFirst)
Sibling brand	FunFirst (`apps/funfirst-web`, port 3002) shares the same packages & CI; RedWave web moved to its own repo (`microspaces/redwave`)

Domain	Route	Wiring
surroundshow.com	`/` (brand shell)	Vercel project `surroundshow-web`
homeshow.com	`/homeshow`	host-matched rewrites in `apps/surroundshow-web/vercel.json`
weddingloco.com	`/wedding-loco`
barloco.com	`/bar-loco`

Home — stages & brand hero

/venue — venue settings

/order — mobile guest ordering

/bar — Bar Loco tickets

App features

Stages landing — brand hero + stage cards (HomeShow, Halloween, Christmas, New Year, Wedding Ceremony, Wedding Reception, Bar Loco), each a themed show space.
Show engine — Designer (layout editor), Player, Preview wall, and per-screen routes. Scene changes propagate to every subscribed player/screen reactively — no polling.
Venue module — /venue settings plus places (booths/tables) with guest place claim.
Mobile order tab — guest key (UUID in localStorage), /order binds the guest to a claimed place; /bar serves Bar Loco tickets.
Community — groups (state/county kinds from the legacy §-prefixed groups), feed with posts/replies/upvotes, people, events, marketplace.
Brand registry — @linkall/brands is the single source of truth for identity, nav, theming, and feature flags; per-route layouts keep show pages chrome-free.

Flow

Local dev

pnpm install  (repo root)
pnpm dev:surroundshow   →  turbo dev --filter=surroundshow-web
        │
        ▼
  Next.js 15 on :3001   (thin app — pages wire @linkall/ui components)
        │
        ▼
  Convex cloud  NEXT_PUBLIC_CONVEX_URL (per-brand deployment)

How the hybrid model replaces legacy multitenancy

Legacy SiteId column + domain→site middleware → each brand is its own Convex deployment; no tenant filtering anywhere.
SignalR DisplayHub scene sync → Convex reactive queries (shows.setScene updates every subscribed player/screen instantly).
Comment tables (group/profile chat) → posts table with replies + upvotes, live-updating.
Layout JSON engine (designer.json/player.json) → typed shows/scenes schema + real React components.
Views/{Tenant} + per-tenant CSS → brand registry + per-app Tailwind @theme tokens.

Deploy

Push to main. Two GitHub Actions workflows:

vercel-deploy.yml — matrix (surroundshow-web, funfirst-web): uploads the full monorepo so workspace:* resolves, PATCHes the Vercel project rootDirectory to apps/<app>, then vercel deploy --prod. Not Vercel git integration.
convex-deploy.yml — matrix (surroundshow, funfirst): npx convex deploy in packages/backend with CONVEX_DEPLOY_KEY_<BRAND>, on packages/backend/convex/** changes.

Domains: the per-show domains (homeshow.com, weddingloco.com, barloco.com) only work while attached to the surroundshow-web Vercel project — the host-matched rewrites live in that app's vercel.json.

Tech

Monorepo	pnpm 9.15.0 workspaces + Turbo 2.x. Root package name `linkall-platform`.
App	`apps/surroundshow-web` — Next.js 15, React 19, Tailwind 4, port 3001
Backend	`packages/backend` (`@linkall/backend`) — ONE Convex schema + functions; per-brand deployments. Venue service: `venue.ts` + `venueLogic.ts` + 13 indexes
Shared	`packages/ui` (`@linkall/ui`) — feed, groups, shows, designer/player, venue settings, guest night, app shell · `packages/brands` (`@linkall/brands`) — brand registry
Mobile	`apps/mobile` — Expo (expo-router), brand chosen by `EXPO_PUBLIC_BRAND`
Vercel	`framework: nextjs`, `installCommand: cd ../.. && pnpm install --frozen-lockfile`, `buildCommand: cd ../.. && pnpm --filter surroundshow-web build`, host-matched rewrites for show domains
CI	`.github/workflows/vercel-deploy.yml` + `convex-deploy.yml`, both matrix per brand
Local	`pnpm install` · `pnpm dev:surroundshow` · `pnpm typecheck` — Git Bash on Windows

apps/surroundshow-web/
  app/            # /, shows, designer, player, preview, venue, order, bar,
                  # groups, feed, people, market, events, [slug]/[act]/...
  vercel.json     # host-matched rewrites (show domains)
  .env.local      # NEXT_PUBLIC_CONVEX_URL
packages/
  backend/convex/ # venue.ts, venueLogic.ts, designer.ts, locos.ts, seed.ts, …
  brands/src/     # surroundshow | funfirst | redwave registry
  ui/src/         # shared feature components

🗂️ Roadmap

Live roadmap, managed as GitHub issues (linkall issues). Add or close items on GitHub — ☑ = done, close as “not planned” to remove.

Test results

2026-08-28 — venue module + mobile order verification (local)

pnpm dev:surroundshow — ready in ~2s against the production Convex deployment (upbeat-capybara-284).
All routes HTTP 200: /, /venue, /order, /bar (Next 15.5, 1000+ modules compiled).
Playwright captures with real Convex-WS hydration waits (headless Chrome snapshots fire before hydration): venue settings, mobile order place-claim grid, Bar Loco tickets — screenshots above, fully rendered.
Backend: venue service (venue.ts + 13 indexes) deployed to both brand deployments 2026-08-28, Main Room venues seeded (surroundshow venue id r571g4ymwdqr…).

Multi-screen player sync across physical devices not yet exercised — treat the 08-28 pass as feature + render verification, not a full QA pass.