Hybrid P2P-Cloud Anonymous Transfer Engine

startTransfer(file)
  │
  ├─ state: p2p_pending  → connectAndOffer()  → start 5 s countdown
  │
  ├─ P2P connected before 5 s ─────┐        ┌──── timer expires (5 s)
  │                                ▼        ▼
  │                          state: p2p_active   state: cloud_active
  │                                │                  │
  │                    sendFile() via DataChannel   POST /api/upload
  │                       (16 KB chunks)            (5 MB S3 multipart)
  │                                │                  │
  │                                └────► state: completed ◄────┘

Graceful degradation at every layer

• Redis unavailable? → async InMemoryStore with asyncio.Lock and manual TTL eviction.
• WebRTC blocked? → 5-second timer triggers the S3 relay.
• S3 upload fails mid-stream? → abort_multipart_upload cleans up orphaned parts.
• Container crashes? → Kubernetes restarts the pod with resource limits preventing OOM cascade.

1  Alice → POST /api/auth/join {"anonymous_name": "Hacker_4821"}
2  Auth  → JWT token (UUID + name + 2 h expiry)
3  Alice → POST /api/heartbeat  (every 30 s)  → SETEX user_online:{uuid} 60
4  Bob   → GET  /api/users/online             → [{user_id, name}]   (Alice visible)
   ── Bob selects Alice from the lobby ──
5  Alice, Bob → emit('register', {uuid})      → Socket.IO userSocketMap
6  Alice → emit('offer',  {targetUuid, sdp})  → relayed to Bob
7  Bob   → emit('answer', {targetUuid, sdp})  → relayed to Alice
8  both  → emit('ice-candidate', …)           → trickled both ways

   ┌─ P2P succeeds (< 5 s) ───────────────────────────────────────┐
   │  DataChannel: JSON metadata {filename, size, type}           │
   │  DataChannel: binary chunks (16 KB)  → Bob writes IndexedDB  │
   │  Bob assembles Blob → triggers download                      │
   └─────────────────────────────────────────────────────────────┘
   ┌─ P2P fails (5 s timeout) ───────────────────────────────────┐
   │  Alice → POST /api/upload  (5 MB multipart stream to S3)    │
   │  S3    → 1-hour presigned URL → shared with Bob             │
   │  Bob   → downloads → triggers Lambda Nuke → S3 delete_object │
   └────────────────────────────────────────────────────────────┘

Redis presence store

Key pattern:   user_online:{uuid}
Value:         "{anonymous_name}"        e.g. "Hacker_4821"
TTL:           60 seconds
Heartbeat:     every 30 seconds (POST /api/heartbeat)
Scan method:   SCAN (non-blocking) + batched MGET

S3 object layout

Path:          uploads/{user_id}/{uuid4}.{extension}
Metadata:      {"sender_uuid": "{user_id}"}
Presigned URL: GET, expires in 3600 seconds (1 hour)
Lifecycle:     Expiration after 1 day
Multipart:     AbortIncompleteMultipartUpload after 1 day

IndexedDB (browser-side)

Database:      TransferCache
Object store:  chunks
Data:          raw binary ArrayBuffer (16 KB per entry)
Lifecycle:     cleared after Blob assembly and download trigger

Pydantic models

class JoinRequest(BaseModel):
    anonymous_name: str          # e.g. "Hacker_4821"

class TokenResponse(BaseModel):
    access_token: str            # HS256 JWT
    token_type: str              # "bearer"

REST API — FastAPI, port 8000

WebSocket signaling events — Socket.IO, port 3001

Authentication flow

Client                                  Server
  │  POST /api/auth/join {"anonymous_name": "X"}
  │ ─────────────────────────────────────►  generate UUID4
  │                                         sign JWT (HS256): sub=uuid, name=X, exp=+2h
  │  ◄─────────────────────────────────────  {"access_token": "eyJ..."}
  │  POST /api/heartbeat  Authorization: Bearer eyJ...
  │ ─────────────────────────────────────►  decode + verify HS256 + check exp
  │                                         SETEX user_online:{uuid} 60
  │  ◄─────────────────────────────────────  200 OK

Container security posture

• Non-root execution across all containers (appuser:appgroup, nginx:nginx).
• Multi-stage builds strip Node.js, npm, and pip from production images.
• Kubernetes resource limits — API 500m / 512Mi, frontend 200m / 128Mi, signaling 250m / 256Mi.
• AWS IAM least-privilege — the Lambda holds only s3:DeleteObject and s3:GetObject.
• No persistent credentials in containers — secrets injected via Kubernetes Secret objects.

One-command local development

python start.py
# boots FastAPI :8000 (hot-reload), Socket.IO :3001, Vite :5173
# waits 4 s, opens http://localhost:5173, monitors all 3 processes

Kubernetes deployment

kubectl apply -f infrastructure/k8s/app-secrets.yaml
kubectl apply -f infrastructure/k8s/api-deployment.yaml
kubectl apply -f infrastructure/k8s/frontend-deployment.yaml
kubectl apply -f infrastructure/k8s/socket-deployment.yaml
kubectl apply -f infrastructure/k8s/ingress.yaml
kubectl apply -f infrastructure/k8s/api-servicemonitor.yaml

Environment variables