ShopSide AI
Multiplayer Commerce — Where Two People Decide Together and the Right Seller Finds Them
Inspiration
We started with a frustration that everyone has felt but no product has ever fixed.
You are moving in with someone. Different cities. You need a desk, two chairs, a lamp — $300 total. So you do what everyone does: send links on WhatsApp. They send links back. You have a phone call. You can't agree. Someone gives up. The purchase never happens.
Two trillion dollars of annual ecommerce happens after a conversation between two people. That conversation currently lives in fragmented messages, screenshots, and phone calls across different apps. The shopping happens separately even when the decision doesn't.
Meanwhile, a merchant somewhere had the right product and would have offered $20 less — if only they had known two people were right there, $20 away from buying.
That gap — between two deciding people and one responsive seller — is what ShopSide was built to close.
"A little closer, even from afar." That line appeared in our loading screen early in development. It became the soul of the product.
The Problem
For shoppers
Coordinating a shared purchase online is broken. People send links over WhatsApp, make phone calls, lose track of what they compared, and often abandon the purchase entirely. The shopping happens separately even when the decision doesn't. This isn't a rare edge case — it is how couples, roommates, friends, and families actually buy things together today.
For merchants
Sellers lose sales every day to hesitation they never see. A buyer was $20 over budget. The merchant would have offered $20 less. Nobody told them. There is currently no channel where a merchant can respond to qualified, consented purchase intent while the buyer is still deciding — not after they have left.
The Solution
ShopSide AI is a real-time multiplayer shopping platform where two people share one live room, build product bundles together, and let participating merchant AI agents respond when a deal is close but not done.
The full journey happens in one room.
Two people describe their goal — "Find us a desk and two chairs for under $300." ShopSide understands the shared budget, priorities, and preferences. The AI activates product search through Channel3, assembles compatible combinations within the budget, and shows both people the same results in real time.
Both people react, compare products on the Decision Board, and place items in a shared Three.js visualization space. Neither person's approval is assumed — both choose for themselves.
When a bundle lands $20 over budget and both people hesitate, ShopSide's Deal Rescue identifies the gap. With the shoppers' consent, it broadcasts a structured demand signal to participating merchant AI agents. Each agent — scoped to its own inventory and policy rules — evaluates the opportunity and sends a personalized offer directly into the room. Not an ad. Not a discount code. A direct response to verified, consented purchase intent at the exact moment of hesitation.
When both people approve, the designated payer authorizes a PayPal payment hold — funds reserved before capture. The merchant sees verified financial commitment. On confirmation, PayPal captures and ShopSide generates a shared decision receipt with the full approval timeline anchored to a confirmed PayPal order.
How We Built It
Frontend React and Next.js with a fully custom design system — 2,248 lines of original CSS built from scratch. No component library defaults. The visual language uses a pearl, ink, and coral palette designed to feel warmer than a typical commerce tool.
Backend FastAPI in Python. The main API runs to 2,561 lines and handles WebSocket synchronization, revision-based compare-and-swap to prevent lost updates, per-client rate limiting, Alembic database migrations, and idempotent PayPal operations throughout. PostgreSQL for persistence, deployed on Google Cloud Run via Docker.
AI and agents Google ADK and Gemini power four distinct agents: the room coordinator, the Smart Bundle builder, the merchant AI representative, and the shopping intent parser. Each agent has explicit tool budgets enforced by the backend — the Smart Bundle agent is capped at six model calls and ten Channel3 HTTP calls per request to keep the experience fast and cost-predictable during a live two-person session.
Testing 152 backend test functions across 25 test files, covering rooms, merchant checkout, payment authorization, smart bundles, deal rescue, price watches, Channel3 webhooks, and shortlist persistence. 66 Playwright frontend test cases across 25 spec files covering the full user journey.
How We Used PayPal
PayPal is not a button at the end of ShopSide. It is the trust infrastructure for the entire commerce journey.
AUTHORIZE before CAPTURE When both shoppers approve a merchant offer, ShopSide creates a PayPal order with AUTHORIZE intent — funds reserved in the buyer's account before capture. The merchant agent sees this authorization signal and knows the intent is financially real, not a browsing preference. Settlement then re-checks merchant identity, SKU, quantity, stock, buyer policy, currency, amount, and expiry against PayPal readback before capture completes. If the lower-capture capability is unavailable, ShopSide voids the hold and falls back to standard capture checkout with a fresh buyer approval. No funds can move without a confirmed PayPal order readback.
PayPal MCP — official integration ShopSide integrates the official PayPal MCP server as a stdio subprocess restricted to orders.get only — no payment initiation, no customer data, no scope creep. A fresh sandbox access token is generated per call. The MCP result is filtered to return only the order status string. Raw payment data never reaches any AI model or the shared room. This is the responsible way to integrate PayPal into an agentic workflow: the agent observes, the backend acts.
Webhook verification Every PayPal webhook signature is verified before any payment or alert state changes. The backend reads PayPal provider state before updating local state — no optimistic updates on financial data.
Decision Receipt After capture, ShopSide generates a structured receipt anchored to a confirmed PayPal order ID and capture ID. It records who approved, when, what alternatives were considered, the merchant offer conditions, and the final amount. This is a proof of joint decision — not just a transaction record.
How We Used Channel3
Channel3 provides the entire product intelligence layer. ShopSide integrates the full available API surface.
Search and discovery Standard search with price filters, advanced search with the full filter surface including mode, brand, retailer domain, category, condition, color, availability, and market locale. Agentic search mode is used inside the Smart Bundle agent loop. Image URL search and product URL lookup let users find live products from photos or existing links.
Product intelligence Full product detail with offers, variants, attributes, key features, ratings, and retailer-specific pricing. Variant-aware detail fetch preserves the buyer's selected retailer offer when enriching with fresh data. Similar products and cheaper alternatives are surfaced when the main product exceeds budget. Price history covers 90 days per product and variant.
Affiliate attribution Every Channel3 detail fetch carries a SHA-256 room and participant attribution ID. Affiliate click and transaction activity is retrievable via the reporting endpoints.
Price Watch — full subscription lifecycle Buyers can subscribe to exact product and variant price alerts. ShopSide enforces currency scoping deterministically — a GBP watch only triggers on GBP retailer offers, never on a USD price drop for the same product. Retailer-specific watches are supported. When two participants in the same room watch the same product at the same threshold, one Channel3 subscription is shared. Signed webhook delivery is verified before processing. Watches can be paused, resumed, and cancelled per participant.
Hallucination guard Every AI-generated product description passes through a sentence-level filter. Any sentence making a dimension or load claim is cross-referenced against structured Channel3 product data. If the numbers and units cannot be verified against the actual product record, the sentence is removed and a disclaimer is shown. The language model is never the source of truth for product specifications.
How We Used AG Grid
AG Grid is the data layer that makes collaborative decision-making and merchant intelligence actionable.
Decision Board — buyer-facing comparison grid When both people save products, the AG Grid Decision Board renders a live side-by-side comparison. Columns include name, price with currency, dimensions normalized across multiple data formats, seating capacity extracted across naming convention variants, material, delivery, evidence source with retrieval timestamp, and both participants' reactions. The grid uses themeQuartz with custom dark-mode parameters matched to ShopSide's design language. Column definitions use wrapText and autoHeight for dense product attribute data. The grid updates live as room state changes via WebSocket without rebuilding — stable row identity via getRowId prevents flicker and scroll position loss.
Merchant Dashboard — two live operational grids The Opportunity Feed grid shows real-time buyer demand signals routed to the merchant's agent: opportunity ID, shopping categories, buyer budget, deal stage, and time remaining with a custom value formatter. Row click navigates to the Deal Box with that opportunity pre-selected.
The Deal Box grid shows the full negotiation pipeline: matching product, offer amount, ownership, status, time remaining, and an action cell renderer with a button that opens the full deal detail drawer. Both grids use the same themeQuartz dark configuration as the Decision Board — consistent visual language across the full product.
Accomplishments We Are Proud Of
Responsible merchant AI The merchant agent enforces a mandatory evidence audit before any price proposal. It must call four read-only evidence tools in sequence — merchant policy, eligible products, market price context, and buyer opportunity — before proposing anything. If any step is skipped, the proposal is rejected with a hard error. Every AI-generated offer is then validated deterministically against a policy dataclass covering floor price, maximum discount in basis points, quantity limits, and offer expiry. The language model is never the authority on stock, price, currency, or offer validity.
PayPal as a trust layer, not a checkout button The AUTHORIZE hold means the merchant sees verified financial commitment before the deal closes. Only PayPal's consumer network can provide that signal. This changes PayPal from a final step into a negotiation trust layer present throughout the commerce journey.
Shortlist persistence across market switches When a buyer changes from USD to GBP search and runs a new discovery, previously shortlisted products are snapshotted before discovery is replaced. A restore endpoint silently re-fetches missing products. Rooms built over multiple sessions do not lose saved items.
Two-sided consent throughout Merchant agents receive only consented, anonymized intent data — categories, budget range, negotiation preference. Private room chat is never shared with any merchant. The room host controls whether seller offers are enabled. A human seller can join only with explicit room permission.
218 test cases 152 backend test functions and 66 Playwright frontend test cases. We prioritized correctness alongside features throughout the build.
Challenges
Making PayPal the trust layer, not just the button The hardest architectural decision was making the AUTHORIZE hold meaningful in the merchant negotiation flow. The timing between authorization, merchant agent response, and capture required careful state management with explicit status transitions, expiry enforcement, and a safe fallback to standard capture when lower-capture was unavailable. Getting this right took more iterations than any other feature.
The language model as a price or dimension authority Language models confidently generate plausible-sounding prices, dimensions, and stock levels. We built two independent guards: deterministic policy validation for every merchant AI offer before it reaches any buyer, and a sentence-level spec filter that strips every product claim not backed by Channel3 structured data. Both run on every request.
Products surviving a new search When a buyer changes market or runs a new search, previously saved products were silently overwritten. Solving this required snapshotting shortlisted products before each discovery replacement, a restore endpoint for stale sessions, and a merged product source combining catalog, shortlist snapshots, and current discovery. It took five new tests to cover the edge cases.
Real-time sync without infrastructure overhead Two people shopping together in real time needs WebSocket synchronization, revision-based compare-and-swap, per-client rate limiting, and graceful reconnection — without a heavy message broker. We built this directly on FastAPI with PostgreSQL and Cloud Run, keeping the architecture simple enough to ship and reliable enough to demo on two separate devices.
What We Learned
Channel3 — data quality demands humility We assumed product data would arrive clean and consistent. It does not. Dimensions come in multiple formats. Retailer offers carry different currencies across the same product. Affiliate attribution requires a stable deterministic user ID per room. The biggest lesson: never let the AI fill the gaps Channel3 leaves. When Channel3 does not return a dimension, the temptation is to let Gemini estimate one. That estimate becomes a confident lie the buyer reads before purchase. The hallucination guard exists because of this lesson.
Price Watch was deceptively complex. Currency scoping, retailer scoping, shared subscription reuse, and signed webhook verification were all required before it behaved correctly in real multi-person sessions.
AG Grid — real-time data needs stable row identity Our first Decision Board rebuilt the grid on every room state update. It flickered, lost scroll position, and reset column widths. The fix was getRowId — AG Grid's stable row identity system that lets the grid update individual rows in place. Once applied to the merchant grids, live deal updates became smooth. The second lesson was theming — matching the grid to ShopSide's design language required custom themeQuartz parameters, not just CSS overrides. The third: wrapText and autoHeight are essential for product attribute data that does not fit in fixed-height rows.
PayPal MCP — the agent must never touch payment state Our first instinct was to give the room AI coordinator direct access to PayPal API calls. We immediately reversed this. An agent with payment initiation capability — even in sandbox — is a liability. The correct architecture is what we implemented: the official MCP server runs as a sandboxed stdio subprocess restricted to orders.get only. The agent reads payment status and nothing else. Raw payment data never reaches the model. Read-only tool access is the right default for any financial integration in an agentic workflow.
Google ADK and Gemini — agents need hard budgets Unbounded agent loops are expensive and unpredictable. Our Smart Bundle agent's first implementation could run indefinitely. In practice it sometimes ran twelve or more Channel3 HTTP calls for a simple two-item bundle. We added explicit budgets enforced by the backend: a maximum of six model calls and ten Channel3 HTTP calls per bundle request. When the remaining budget drops below two model calls, the agent is told to finalize with what it has. This made bundle generation predictable, cost-controlled, and fast enough for a live two-person session.
The second ADK lesson was about trust boundaries. Product names, chat messages, and catalog descriptions are all surfaces where a user could inject text intended to manipulate agent behavior. Making untrusted data explicit in the system prompt — and validating all agent-proposed commercial actions deterministically in the backend — was not optional. It was the minimum bar for a commerce agent handling real payment flows.
What Is Next
Real World Validation & Building Marketplace
Try It
Live app: https://my-shopside-app.cloud.run/
GitHub: https://github.com/appinikrishnachaitanya/ShopSide
Built With
- adk
- agentic
- aggrid
- ai
- channel3
- docker
- fastapi
- gcp
- gemini
- mcp
- next.js
- paypal
- python
- react
- sql
- three.js
- typescript
- websockets