Product Architecture
How ShelfSpace works under the hood
A two-sided marketplace orchestrating discovery, booking, escrow, fulfillment, and in-store conversion — all in one workflow.
Three personas, one platform
Brand
Online-only e-commerce sellers seeking real-world retail exposure without long leases.
Host
Cafés, salons, boutiques and studios with unused shelf or window space.
Admin
Platform team handling moderation, payouts, and disputes.
Core booking flow
01
Discover
Brand filters by city, vibe, traffic
→
02
Request
Pick dates, weeks, product
→
03
Escrow
Funds held by platform
→
04
Setup
Brand ships; host installs
→
05
Live
QR generated & printed
→
06
Track
Scans + sales attributed
→
07
Payout
Funds released to host
System diagram
Major services and how data flows between them.
Clients
Brand web app
Host web app
Admin console
In-store QR landing
API gateway & services
Discovery service
Booking & escrow
QR + attribution
Messaging
Trust & safety
Data & infra
Postgres · primary
Search index · cities & vibes
Recommendation engine
Payments gateway
Realtime channel
Rules & matching engine
Deterministic rules + learned signals decide which shelves surface to which brand.
Hard rules
- city ∈ brand.target_cities
- shelf.status == 'active'
- shelf.dimensions ⊇ product.dimensions
- date_range ∉ shelf.unavailable_windows
- host.background_check == 'verified'
Soft scoring (0–100)
- vibe_overlap × 35
- foot_traffic_norm × 25
- historical_conv × 20
- price_fit × 12
- host_rating × 8
Escrow state machine
pending
→confirmed
→in escrow
→active
→completed
on_confirm() · brand approves booking
on_payment() · funds locked in escrow
on_setup_verified() · QR active, pop-up live
on_window_end() · funds released to host (minus 8% fee)
Tech stack at a glance
Frontend
React + TypeScript, TanStack Router
Backend
Node services, REST + WebSockets
Data
Postgres, Redis, search index
Payments
Stripe Connect · escrow + payouts