RipRoster — Streamer / Shop Guide

Who this is for: the store or streamer running the show. RipRoster is the companion app to a live YouTube Rip & Ship show run from a physical card store. You (and your team) manage inventory, members, trades, and the on-stream reveal; your members manage their own boxes.

This is the most detailed of the three RipRoster guides. If you are a community member, see the Member guide. If you are a YouTube viewer, see the Viewer guide.

This guide describes what RipRoster does today. Where a feature only comes alive after your store is deployed, or where a step is handled out-of-band, it says so plainly.

The five roles in one table (full capability detail is in docs/AUTH-ROLES.md):

1. Welcome & who this guide is for

RipRoster pairs your physical card store with your live YouTube Rip & Ship show. You, the store runner, see a dashboard (Overview, Inventory, Members, Trades, Shipping, and more). Your members each see their own box of cards and the trade floor.

The person signed in on the store side is a staff-shape role — one of owner, streamer, moderator, or staff. Most of the setup actions in this guide require the owner role. Where a step differs for streamer/moderator/staff, it is called out.

No capability gate — this is orientation.

📸 SCREENSHOT: owner dashboard landing (Overview) — Overview page — owner. Owner: capture from the live site and replace this block with the image.

2. Signing in & your dashboard

1. Sign in. In production, sign-in goes through the Cognito hosted login page (this guide describes the production hosted-login flow, not the local dev-auth shortcut). Social login (Google / Facebook / Apple) is staged and turned on at deploy — see docs/AUTH-ROLES.md §4.
2. You land on Overview, your store dashboard. Gate: the Overview nav is shown to any staff-shape role (owner/streamer/moderator/staff).
3. The left navigation an owner sees: Overview, Inventory, Card catalog, Members, Invite codes, Staff, Trade desk, Shipping, Store settings. Each item is gated by a capability, so a streamer, moderator, or staff member sees only the set their role allows (for example, a streamer does not see Store settings or Staff).

📸 SCREENSHOT: left-nav sidebar for a store runner — any page — owner. Owner: capture from the live site and replace this block with the image.

Today's note — the streamer role. There is no seeded pure-streamer identity in the local dev environment (it maps to owner for Phase-1 back-compat), so a true streamer walkthrough is produced from a real streamer-role login on the deployed site. A streamer sees the owner dashboard minus Store settings and Staff.

3. Set up your store (Settings)

1. Open Store settings.
2. Set your Community name.
3. Set the "Ship my order" Shopify product URL — the link your members use to buy shipping home.
4. Save.

Gate: settings:write — owner only. Streamer, moderator, and staff do not see the Store settings page at all.

Today's note — branding. There is no logo or color branding control yet. Custom store branding is planned for Phase 3.

📸 SCREENSHOT: Store settings form (Community name + Shopify URL) — #/settings — owner. Owner: capture from the live site and replace this block with the image.

4. Connect the stream overlay to OBS

This is the flagship streamer feature: the on-screen reveal animation that plays when a trade is completed on-air. You wire it once by pasting a browser-source URL into OBS.

In Store settings → Stream overlay panel:

1. Click Regenerate token to mint the one-time OBS browser-source URL.
2. Click Copy URL.
3. In OBS, add a Browser source and paste the URL.
4. Click Test (full) or Test (quick) to confirm the animation renders in OBS.

Gate: overlay:control — owner / streamer / moderator.

The URL is a shared secret shown once. Treat it like a password. If you regenerate the token, the previously pasted URL stops working, so you must copy the new one into OBS again.

Today's note — open OBS before you test. The overlay fires only to connected browser sources. If OBS (or the browser source) is not open when you press Test or Play on stream, you will see a "no overlay connected" / delivered-count-of-0 toast and nothing renders on stream. Open and confirm your OBS browser source first, then test.

Diagram D2 — Mail Day reveal (sequence)

sequenceDiagram
    participant S as Streamer (RipRoster app)
    participant Srv as RipRoster server
    participant OBS as OBS browser source
    participant YT as YouTube audience
    participant M as Member's app

    S->>Srv: Click "Play on stream" (POST /api/overlay/trigger — trade must be completed)
    Srv->>OBS: Publish "event: reveal" over the per-tenant live channel (SSE)
    OBS->>OBS: Render the reveal animation
    OBS-->>YT: Audience sees the reveal on the YouTube stream
    Srv->>M: Best-effort write a reveal record
    M->>M: Member later sees it in "My Mail Day reveals"

📸 SCREENSHOT: Stream overlay panel with URL masked + Regenerate/Test buttons — #/settings — owner/streamer. Owner: capture from the live site and replace this block with the image.

📸 SCREENSHOT: the one-time OBS URL right after Regenerate (redact the token before sharing) — #/settings — owner/streamer. Owner: capture from the live site and replace this block with the image.

📸 SCREENSHOT: OBS "Browser" source config with the URL pasted — OBS (external app) — owner/streamer. Owner: capture from the live site and replace this block with the image.

📸 SCREENSHOT: the reveal animation playing in the OBS browser source — OBS — owner/streamer. Owner: capture from the live site and replace this block with the image.

5. Invite your team (staff invites)

Bring on co-hosts and helpers with a staff invite.

1. Open the Staff page.
2. Generate a staff invite. The role is fixed on the invite — streamer, moderator, or helper (staff). A staff invite can never grant owner or member.
3. Share the code with the invitee; they accept it to join your store with that fixed role.
4. Manage existing staff: change role or status (active / suspended) from the Staff page.

Gate: staff:manage — owner only.

The last-active-owner guard. Any change that would drop your store's active-owner count to zero is refused. There is always at least one active owner.

Diagram D4 — Invite → redeem / accept

flowchart TD
    subgraph A["Member invite code"]
        A1["Owner / streamer / moderator generates a code<br/>(invite:manage)"]
        A2["Member redeems the code<br/>(POST /api/invites/redeem)"]
        A3{"Valid? not revoked /<br/>not expired / not exhausted /<br/>not already a member"}
        A4["Joins the store as a member"]
        A1 --> A2 --> A3
        A3 -- yes --> A4
        A3 -- no --> A5["Rejected (409 / expired / exhausted)"]
    end
    subgraph B["Staff invite"]
        B1["Owner generates an invite with a FIXED role<br/>(staff:manage — streamer / moderator / staff)"]
        B2["Invitee accepts<br/>(POST /api/staff/accept)"]
        B3{"Valid? not revoked /<br/>not consumed"}
        B4["Joins with that fixed role (no box)"]
        B1 --> B2 --> B3
        B3 -- yes --> B4
        B3 -- no --> B5["Rejected (409)"]
    end

📸 SCREENSHOT: Staff page + "Invite a streamer, moderator, or helper" dialog — #/staff — owner. Owner: capture from the live site and replace this block with the image.

6. Invite your members (member invite codes)

Member invite codes are how your community joins.

1. Open the Invite codes page.
2. Generate a code. Defaults: multi-use (50 uses), 30-day expiry. Options: single-use, or never-expires.
3. Copy the code and share it with your members.
4. Revoke a code any time to stop further redemptions.

Gate: invite:manage — owner / streamer / moderator.

A member who redeems a code becomes a member in your store. See the invite flow in Diagram D4 above (shared with staff invites).

Today's note — a new member's box and handle. A freshly self-redeemed member starts with an empty box and no handle until you assign one. Today that box is stamped when you check their first inbound package into a location (see §7); there is no separate "assign a box" screen yet. Until then, a brand-new member can appear as a nameless "@" in trade-partner pickers.

📸 SCREENSHOT: Invite codes page + generate-code dialog + a created code — #/invites — owner/streamer/moderator. Owner: capture from the live site and replace this block with the image.

7. Receiving inbound packages (Inbound queue)

A member announces a package of cards they are shipping in. You receive it and check each card into their box.

1. Open the Inbound queue. Packages waiting to be received appear first.
2. On an announced package, click Mark received.
3. For each declared card, either Check in (it lands in the member's box) or Didn't arrive.
4. When every card is handled, the package is fully processed (closed).

Gate: Mark received and Check in require inventory:write — owner / streamer / staff. (A moderator does not hold inventory:write, so moderators do not do inbound receiving.)

Today's note — live carrier status is inert until deploy. The optional Refresh status button and the live "In transit / Delivered" carrier chips only do something once your store is deployed with a real carrier provider key. With no key, that layer is a no-op — and the manual Mark received / Check in path above completes every flow on its own. When a key is configured, a carrier "Delivered" event can auto-advance a package from announced to received for you. See docs/CARRIER-TRACKING.md. Do not expect live carrier chips in a local or pre-deploy environment.

Diagram D3 — Inbound package → check-in

flowchart TD
    A["Member announces a package<br/>(announced)"] --> B["Streamer marks received<br/>(received)"]
    A -. "carrier reports Delivered<br/>(accelerator, once deployed with a key)" .-> B
    B --> C{"For each declared card<br/>(declared)"}
    C -- "card arrived" --> D["Check in to member's box<br/>(checked_in)"]
    C -- "card missing" --> E["Didn't arrive<br/>(not_arrived)"]
    D --> F["Package fully processed<br/>(closed)"]
    E --> F

📸 SCREENSHOT: staff Inbound queue (packages waiting to receive) — #/inbound — owner/streamer/staff. Owner: capture from the live site and replace this block with the image.

📸 SCREENSHOT: a package card with "Mark received" and the per-card Check-in / Didn't-arrive actions — #/inbound — owner/streamer/staff. Owner: capture from the live site and replace this block with the image.

8. Reviewing and completing trades (Trade desk)

The Trade desk is where you finalize in-hand trades — trades where both cards are already in members' boxes at your store.

1. Open the Trade desk.
2. Open a proposed or accepted trade to review it.
3. Physically move the cards between the two members.
4. Tick the confirmation box ("I've moved these items").
5. Click Complete swap. Ownership and box locations update automatically.

Gate: trade:complete — owner / streamer / moderator. Staff has no Trade desk (staff holds neither trade:propose nor trade:complete, so the page is hidden for them).

Diagram D5 — In-hand vs mail-in trade (decision)

flowchart TD
    Q{"Do you have the card<br/>in your box right now?"}
    Q -- "Yes, it's in my box" --> IH["In-hand trade<br/>(both cards already in boxes)"]
    Q -- "No, I'm shipping it in" --> MI["Mail-in trade<br/>(pick from box OR whole catalog;<br/>both parties ship; tracking + arrival<br/>gate completion)"]
    IH --> C["Streamer completes → instant ownership swap"]
    MI --> C
    C --> R["Reveal plays on stream"]

📸 SCREENSHOT: Trade desk list + review-trade modal showing the "move these items" notice + confirmation checkbox — #/trades — owner/streamer/moderator. Owner: capture from the live site and replace this block with the image.

9. Running a Mail Day reveal

Once a trade is completed, you fire its on-stream reveal.

1. On the completed trade (Trade desk or Mail Day board), click Play on stream.
2. Choose full or quick speed.
3. The overlay animation plays in your OBS browser source; your YouTube audience sees it.

Gate: overlay:control — owner / streamer / moderator.

Today's note — delivered-count feedback. If OBS is not connected, pressing Play shows a "no overlay connected" toast (delivered count of 0) and nothing renders. Confirm OBS is open first (see §4). The reveal sequence is Diagram D2 (in §4).

📸 SCREENSHOT: a completed trade with the "Play on stream" (full/quick) control — #/trades or Mail Day board — owner/streamer/moderator. Owner: capture from the live site and replace this block with the image.

10. The Mail Day board (mail-in trades)

In Store settings, beside the overlay controls, the Mail Day board shows mail-in trades that are on the way (in_transit) or arrived (arrived). An arrived trade is "ready to complete" — completing it fires its reveal, just like an in-hand trade.

Gate: the board renders for overlay:control (owner / streamer / moderator). The board's filter is on status (in_transit / arrived), not on a new role or capability.

Diagram D1 — Mail-in trade lifecycle

stateDiagram-v2
    [*] --> proposed: Offer sent (proposed)
    proposed --> awaiting_tracking: Accepted — both upload tracking within 72h (awaiting_tracking)
    proposed --> declined: Declined (declined)
    proposed --> cancelled: Cancelled (cancelled)
    awaiting_tracking --> in_transit: Both packages on the way (in_transit)
    awaiting_tracking --> expired: 72h window, fewer than 2 uploaded (expired)
    awaiting_tracking --> cancelled: Cancelled (cancelled)
    in_transit --> arrived: Both cards arrived & checked in (arrived)
    in_transit --> voided: 14d / mismatch / cancel-after-ship — cards ship back (voided)
    arrived --> completed: Done! Reveal fires, cards swap owners (completed)
    arrived --> voided: 14d / mismatch — cards ship back (voided)
    completed --> [*]
    declined --> [*]
    cancelled --> [*]
    expired --> [*]
    voided --> [*]

Acceptance auto-chains accepted → awaiting_tracking in one step. Ownership only ever swaps on completed; every other terminal (declined, cancelled, expired, voided) leaves the cards with their original owners, and a voided arrived card ships back to its sender.

📸 SCREENSHOT: the Mail Day board in Settings with at least one "arrived — ready to complete" trade — #/settings — owner/streamer/moderator. Owner: capture from the live site and replace this block with the image.

11. The streamer's view of mail-in trades

Open a mail-in trade to see its detail:

• The two catalog-identified sides — you see each card's catalog identity, never the counterparty's box or location.
• The sub-status chip (awaiting_tracking / in_transit / arrived / voided / expired).
• Both packages' tracking state and any mismatch flag.
• Void trade (a reason is required) — stops the trade, ships the cards back to their senders, and records a reliability note. No ownership changes on a void.
• Complete — available only when the status is arrived.

Gate: Void requires inventory:write OR trade:complete — so owner / streamer / staff / moderator can all void. Complete requires trade:complete and a status of arrived.

See the full mail-in lifecycle in Diagram D1 (in §10).

📸 SCREENSHOT: a mail-in trade detail modal (catalog sides, package bindings, Void button) + the void reason dialog — #/trades — owner/streamer/moderator. Owner: capture from the live site and replace this block with the image.

12. Shipping boxes home

When a member buys shipping, you pack and ship their cards.

1. Record the paid Shopify order in the Shipping queue.
2. Open the packing list for that order.
3. Add the tracking number.
4. Mark shipped.

Gate: shipment:write — owner / streamer / staff.

Resolve open trades first. A member's open trades must be settled before their box ships; the shipping flow enforces this gate so you do not ship a card that is mid-trade.

📸 SCREENSHOT: Shipping queue + packing-list modal with the tracking field — #/shipping — owner/streamer/staff. Owner: capture from the live site and replace this block with the image.

13. Role cheat-sheet & known limits

What each store role can do

trade:propose and profile:edit:own are member-only, so no store role proposes trades or edits member profiles. The authoritative matrix is docs/AUTH-ROLES.md §2.

Known limits today (honest notes)

• No self-serve store onboarding. Setting up a new store is not yet self-service (planned for Phase 3).
• No branding control. No logo or color customization yet (Phase 3).
• Shopify shipping is manual. You record paid orders and shipping by hand; there is no automated Shopify order sync.
• Live carrier tracking is deploy-only. The "Refresh status" button and live carrier chips are inert until your store is deployed with a carrier provider key; the manual receive / check-in path always works (§7, docs/CARRIER-TRACKING.md).
• New members need a box assigned. A self-redeemed member starts with an empty box/handle until you check in their first package (§6).
• Open OBS before testing reveals. With no OBS source connected, Test / Play on stream shows a "no overlay connected" (delivered = 0) toast and nothing renders (§4, §9).