my_site/docs/superpowers/plans/2026-03-20-transfer-webrtc-share.md

Transfer WebRTC Share Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Turn the current mock transfer page into a real QR-to-webpage sharing flow where a sender opens /transfer, the receiver opens a public share URL, and the browsers exchange files over WebRTC P2P.

Architecture: Add a minimal backend signaling layer under backend/src/main/java/com/yoyuzh/transfer using in-memory session storage with short TTL. Keep the sender workspace inside the authenticated portal, add a public receiver route in the frontend, and exchange SDP / ICE over authenticated-or-public HTTP endpoints while the actual file bytes move through RTCDataChannel.

Tech Stack: React 19 + Vite + TypeScript, Spring Boot 3.3.8 + Java 17, WebRTC RTCPeerConnection, existing OSS deploy script, Maven tests, Node test runner.

---

Task 1: Define Share URL And Pure Frontend Protocol Helpers

Files:

• Modify: front/src/pages/transfer-state.ts

• Modify: front/src/pages/transfer-state.test.ts

• Modify: front/src/App.tsx

• Step 1: Write failing tests for share URL and protocol helpers

• Step 2: Run cd front && npm run test to verify the new tests fail

• Step 3: Implement minimal helpers for public share URLs, protocol message typing, and code parsing

• Step 4: Run cd front && npm run test to verify the helpers pass

Task 2: Add Backend Signaling Session APIs

Files:

• Create: backend/src/main/java/com/yoyuzh/transfer/TransferController.java

• Create: backend/src/main/java/com/yoyuzh/transfer/TransferService.java

• Create: backend/src/main/java/com/yoyuzh/transfer/TransferSessionStore.java

• Create: backend/src/main/java/com/yoyuzh/transfer/*.java DTOs for create/join/poll/post signal

• Modify: backend/src/main/java/com/yoyuzh/config/SecurityConfig.java

• Test: backend/src/test/java/com/yoyuzh/transfer/TransferControllerIntegrationTest.java

• Test: backend/src/test/java/com/yoyuzh/config/SecurityConfigTest.java

• Step 1: Write failing backend integration tests for session creation, public join, offer/answer exchange, ICE polling, and access rules

• Step 2: Run cd backend && mvn test to verify the transfer tests fail for the expected missing endpoints

• Step 3: Implement the minimal in-memory signaling service and public /api/transfer/** endpoints

• Step 4: Run cd backend && mvn test to verify backend green

Task 3: Replace Mock Transfer UI With Sender Workspace

Files:

• Modify: front/src/pages/Transfer.tsx

• Create: front/src/lib/transfer-client.ts if needed for request wrappers

• Test: front/src/pages/transfer-state.test.ts

• Step 1: Add failing tests for sender-side state transitions that now depend on created share sessions instead of mock codes

• Step 2: Run cd front && npm run test to verify failure

• Step 3: Implement sender-side session creation, QR/share URL generation, and WebRTC offer / data channel sending

• Step 4: Run cd front && npm run test to verify green

Task 4: Add Public Receiver Page

Files:

• Create: front/src/pages/TransferReceive.tsx

• Modify: front/src/App.tsx

• Modify: front/src/pages/Transfer.tsx

• Step 1: Add failing tests for public share route parsing or receiver helper logic

• Step 2: Run cd front && npm run test to verify failure

• Step 3: Implement the public receiver page, session join flow, answer/ICE exchange, and browser download assembly

• Step 4: Run cd front && npm run test to verify green

Task 5: Make OSS Publish Recognize Public Share Routes

Files:

• Modify: scripts/oss-deploy-lib.mjs

• Modify: scripts/oss-deploy-lib.test.mjs

• Step 1: Write failing tests for new SPA aliases such as t or transfer/receive

• Step 2: Run node scripts/oss-deploy-lib.test.mjs only if already used elsewhere; otherwise verify through existing frontend build and test coverage

• Step 3: Implement the minimal alias updates

• Step 4: Re-run the relevant checked-in verification command

Task 6: Full Verification And Release

Files:

• Modify only if verification reveals issues

• Step 1: Run cd front && npm run test

• Step 2: Run cd front && npm run lint

• Step 3: Run cd front && npm run build

• Step 4: Run cd backend && mvn test

• Step 5: Run cd backend && mvn package

• Step 6: Deploy frontend with node scripts/deploy-front-oss.mjs

• Step 7: Deploy backend jar to the discovered production host and restart my-site-api.service using the real server procedure