my_site/docs/superpowers/plans/2026-03-23-transfer-online-offline-mode.md

Transfer Online Offline Mode 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: Distinguish quick transfer online and offline sending so online stays one-time P2P, while offline persists files for 7 days in storage and can be received repeatedly.

Architecture: Keep the current in-memory WebRTC signaling flow for online transfers and add a persistent offline transfer path in the backend. Offline transfers store file metadata plus storage references, expose repeatable public download/import behavior, and let the frontend branch between P2P receive and offline download based on the transfer mode returned by the API.

Tech Stack: Spring Boot 3.3.8, Java 17, JPA/H2 tests, Vite 6, React 19, TypeScript, existing OSS/local storage abstraction

---

Task 1: Plan the transfer domain split

Files:

• Modify: backend/src/main/java/com/yoyuzh/transfer/CreateTransferSessionRequest.java

• Modify: backend/src/main/java/com/yoyuzh/transfer/TransferSessionResponse.java

• Modify: backend/src/main/java/com/yoyuzh/transfer/LookupTransferSessionResponse.java

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

• Create: backend/src/main/java/com/yoyuzh/transfer/OfflineTransfer*

• Step 1: Write the failing backend tests for mode-aware session responses

• Step 2: Run cd backend && mvn test -Dtest=TransferSessionTest,TransferControllerIntegrationTest and verify the new assertions fail for missing mode-aware behavior

• Step 3: Add the minimal transfer mode types, request fields, and response fields

• Step 4: Run the same Maven test command and verify the new mode assertions pass

Task 2: Add offline transfer storage and repeatable receive flow

Files:

• Modify: backend/src/main/java/com/yoyuzh/files/storage/FileContentStorage.java

• Modify: backend/src/main/java/com/yoyuzh/files/storage/LocalFileContentStorage.java

• Modify: backend/src/main/java/com/yoyuzh/files/storage/OssFileContentStorage.java

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

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

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

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

• Step 1: Write failing integration tests for offline create, upload, lookup, repeatable receive, and 7-day expiry metadata

• Step 2: Run cd backend && mvn test -Dtest=TransferControllerIntegrationTest and verify the offline scenarios fail for the expected missing endpoints/fields

• Step 3: Implement the minimal persistent offline transfer entities, repositories, service methods, and public download/import endpoints

• Step 4: Run cd backend && mvn test -Dtest=TransferControllerIntegrationTest and verify the offline scenarios pass

Task 3: Keep online transfers one-time

Files:

• Modify: backend/src/main/java/com/yoyuzh/transfer/TransferSession.java

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

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

• Step 1: Write the failing test that a second online receiver cannot join/re-receive

• Step 2: Run cd backend && mvn test -Dtest=TransferSessionTest and verify it fails for the current reusable online session behavior

• Step 3: Implement the minimal online single-receive guard

• Step 4: Run cd backend && mvn test -Dtest=TransferSessionTest and verify it passes

Task 4: Add frontend mode-aware API helpers and state

Files:

• Modify: front/src/lib/types.ts

• Modify: front/src/lib/transfer.ts

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

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

• Step 1: Write failing frontend tests for transfer mode options, request payloads, and helper text/state

• Step 2: Run cd front && npm run test and verify the new mode-aware tests fail

• Step 3: Implement the minimal frontend types and helpers for online/offline mode branching

• Step 4: Run cd front && npm run test and verify the helper tests pass

Task 5: Update the transfer send and receive pages

Files:

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

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

• Modify: front/src/lib/transfer.ts

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

• Step 1: Add failing tests for send-mode selection and receive-mode branching where possible in existing frontend test files

• Step 2: Run cd front && npm run test and verify the new assertions fail

• Step 3: Implement the minimal UI and flow split so online stays P2P and offline uses backend-backed receive/download behavior

• Step 4: Run cd front && npm run test and verify the mode flow tests pass

Task 6: Verify and release

Files:

• Modify: docs/architecture.md

• Modify: docs/api-reference.md

• Step 1: Run cd backend && mvn test

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

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

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

• Step 5: Run cd backend && mvn package

• Step 6: Update the docs to describe online/offline transfer behavior and offline endpoints

• Step 7: Publish frontend with node scripts/deploy-front-oss.mjs from repo root

• Step 8: Upload backend/target/yoyuzh-portal-backend-0.0.1-SNAPSHOT.jar to the real server and restart the existing backend service