docs: preserve direct-node architecture alternative

ALTERNATIVE.md

@@ -0,0 +1,165 @@
+# Alternative Architecture: Direct Node Data Plane
+
+This document preserves the original Clouderized Memories architecture principle:
+
+> The cloud should coordinate the experience, but customer media should not routinely flow through Clouderized application servers.
+
+The current PoC uses a broker-mediated relay because it is simpler to prove end to end. This alternative remains important because it is the stronger long-term privacy and bandwidth architecture.
+
+## Core Principle
+
+Separate the control plane from the data plane.
+
+```text
+Control plane:
+  client <-> Clouderized cloud
+
+Data plane:
+  client <-> customer storage node
+```
+
+Clouderized cloud should handle identity, metadata, authorization, device registration, and node discovery. It should not be the normal path for original photo/video bytes.
+
+## Components
+
+### Control Plane
+
+Cloud service responsible for:
+
+- user accounts and sessions
+- device registration
+- storage-node enrollment
+- asset manifests
+- backup state
+- signed upload and fetch authorization
+- node online/offline status
+- billing and entitlement state
+
+### Storage Agent
+
+Lightweight service running on customer-owned hardware.
+
+Responsibilities:
+
+- maintain a secure outbound control connection
+- expose a stable reachable media endpoint
+- receive authorized uploads
+- store encrypted media blobs on local storage
+- serve authorized encrypted blobs to clients
+- report capacity, health, and transfer outcomes
+- maintain local retry/checkpoint state
+
+### Clients
+
+Mobile and web clients are responsible for:
+
+- authenticating with the control plane
+- requesting upload/download grants
+- uploading media directly to the storage node when possible
+- fetching thumbnails/media directly from the storage node when possible
+- decrypting and rendering media locally
+
+## Preferred Data Path
+
+```text
+Client <-> Customer Storage Agent
+```
+
+The cloud authorizes the operation, but the actual media transfer happens directly between the client and the node.
+
+## Fallback Data Path
+
+```text
+Client <-> Encrypted Relay <-> Customer Storage Agent
+```
+
+Relay fallback may be necessary for difficult networks, but the relay should only forward encrypted bytes. It should not process or persist original media.
+
+## Addressing Model
+
+Every storage node needs a stable logical address, independent of the customer's residential IP.
+
+Candidate model:
+
+```text
+<node-id>.edge.clouderized.com
+```
+
+The hostname identifies the node. It should not imply a fixed public IP or manual router configuration.
+
+Possible approaches:
+
+- managed reverse tunnel fabric
+- direct peer connectivity with cloud signaling
+- hybrid transport with direct path first and relay fallback
+- existing tunnel substrate for early prototypes
+
+Cloudflare-style HTTP tunnels are not sufficient as the only bulk media path because request-size limits can break large photo/video uploads.
+
+## Upload Flow
+
+```text
+1. Client asks the control plane for an upload session.
+2. Control plane verifies user, entitlement, node status, and policy.
+3. Control plane returns:
+   - target node identity
+   - short-lived upload token
+   - expected metadata envelope
+4. Client streams encrypted payload directly to the storage node.
+5. Node validates the token and writes the blob locally.
+6. Node returns checksum/status.
+7. Control plane marks the asset committed.
+```
+
+## View Flow
+
+```text
+1. Client asks control plane for timeline metadata.
+2. Control plane returns asset summaries and short-lived fetch grants.
+3. Client fetches thumbnail/media bytes from the storage node.
+4. Client decrypts and renders locally.
+```
+
+## Thumbnail Strategy
+
+Preferred early strategy:
+
+- mobile client generates thumbnails during upload
+- storage node stores both original and thumbnail blobs
+- browser fetches thumbnails from the node and decrypts them locally
+
+Later options:
+
+- storage agent generates thumbnails for imports
+- encrypted relay/cache for derived thumbnails if economics justify it
+
+## Why This Matters
+
+Compared with the current broker-relay PoC, this alternative has stronger:
+
+- privacy story
+- bandwidth economics
+- long-term scalability
+- differentiation from normal cloud photo services
+
+The tradeoff is higher engineering complexity around:
+
+- node reachability
+- NAT traversal
+- resumable transfers
+- offline behavior
+- large video transfer reliability
+- cross-device key management
+
+## Relationship To Current PoC
+
+The current PoC is still valuable. It proves:
+
+- outbound node connection
+- broker-controlled routing
+- upload into customer storage
+- reverse fetch from customer storage
+- Android-to-node workflow through a managed service
+
+This alternative should guide the production architecture once the PoC graduates beyond proving the basic product loop.
+