kite/.planning/phases/05-cloud-storage-backends/05-DISCUSSION-LOG.md

# Phase 5: Cloud Storage Backends - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-28
**Phase:** 5-cloud-storage-backends
**Areas discussed:** Backend scope, OAuth flow & token refresh, Storage selection UX, Cloud document retrieval

---

## Backend Scope

| Option | Description | Selected |
|--------|-------------|----------|
| All 4 in one phase | OneDrive, Google Drive, Nextcloud, WebDAV all in Phase 5 | ✓ |
| WebDAV + Nextcloud first | Ship simpler (credential-based) backends first; OAuth providers in Phase 6 | |
| Just one provider as MVP | One end-to-end provider to prove the pattern, others follow | |

**User's choice:** All 4 in one phase
**Notes:** User wants the full feature set shipped together.

---

## OAuth Flow & Token Refresh

### OAuth callback architecture

| Option | Description | Selected |
|--------|-------------|----------|
| FastAPI handles it, then redirects to Vue | Backend exchanges code for tokens, saves encrypted creds, redirects browser to Vue with success/error query param | ✓ |
| Vue intercepts the callback | Frontend catches redirect, POSTs code to FastAPI — auth code briefly in frontend | |
| You decide | Claude chooses | |

**User's choice:** FastAPI handles it, then redirects to Vue
**Notes:** Keeps tokens entirely server-side; consistent with existing auth architecture.

### Token refresh strategy

| Option | Description | Selected |
|--------|-------------|----------|
| On-demand refresh | Catch 401, refresh silently, retry — transparent to user | ✓ (via Other) |
| Proactive Celery beat refresh | Background task refreshes before expiry | |
| Fail and prompt re-auth | Mark REQUIRES_REAUTH on expiry, no silent refresh | |

**User's choice:** Automatic refresh (on-demand, transparent). Also explicitly requested disconnect per-connection + "Disconnect all" option.
**Notes:** Falls back to REQUIRES_REAUTH only on `invalid_grant` (refresh token itself revoked).

### Nextcloud/WebDAV credential method

| Option | Description | Selected |
|--------|-------------|----------|
| URL + username + app password | App passwords revocable individually — recommended | ✓ (via Other) |
| URL + username + real password | Simpler; revocation requires changing entire account password | |
| You decide | Claude picks | |

**User's choice:** Show both options in the UI with explanations and trade-offs; recommend app passwords. Backend stores whichever the user picks.
**Notes:** Both use HTTP Basic Auth at the protocol level. UI copy explains the difference.

---

## Storage Selection UX

### Sidebar cloud folder tree depth

| Option | Description | Selected |
|--------|-------------|----------|
| Lazy-load one level at a time | Expand a node → fetch its children from cloud API | ✓ |
| Show only root of each provider | Single node per provider, click opens full-screen cloud browser | |
| Pre-fetch 2 levels deep on connect | Eager fetch on connect; faster browsing, stale quickly | |

**User's choice:** Lazy-load one level at a time
**Notes:** Cloud providers appear as top-level sidebar nodes alongside local MinIO folders, matching a Windows Explorer / Nextcloud-style file manager layout.

### Upload destination

| Option | Description | Selected |
|--------|-------------|----------|
| Follows the active folder | Upload goes to the backend of the folder the user is viewing | ✓ |
| Default backend in settings | Global setting overridden per-upload | |
| Per-upload choice at upload time | Dropdown on every upload dialog | |

**User's choice:** Follows the active folder (context-driven)
**Notes:** No explicit setting needed — the active folder's backend determines the destination.

### Existing document migration

| Option | Description | Selected |
|--------|-------------|----------|
| Stay in MinIO — no migration | Existing docs unaffected; local and cloud coexist | ✓ |
| Optional migration | Post-connect prompt to migrate existing docs | |
| You decide | | |

**User's choice:** Stay in MinIO — no migration
**Notes:** CLOUD-03 satisfied by coexistence without migration.

### Cloud provider management location

| Option | Description | Selected |
|--------|-------------|----------|
| Existing SettingsView, new "Cloud Storage" tab | Add tab to SettingsView alongside existing tabs | ✓ |
| Dedicated /cloud-storage route | New full-page view | |
| Sidebar action on cloud provider node | Gear icon → management popover | |

**User's choice:** New "Cloud Storage" tab in SettingsView

---

## Cloud Document Retrieval

### Upload path for cloud backends

| Option | Description | Selected |
|--------|-------------|----------|
| FastAPI intermediary | File bytes go through FastAPI → cloud provider API | ✓ |
| Cloud-native resumable upload URLs | Provider-specific upload session URL generated and sent to browser | |
| You decide | | |

**User's choice:** FastAPI intermediary for cloud uploads
**Notes:** Presigned-PUT-URL flow stays MinIO-only. Cloud backends' `generate_presigned_put_url` raises `NotImplementedError`.

### Download/preview path

| Option | Description | Selected |
|--------|-------------|----------|
| Same /api/documents/{id}/content proxy | Backend resolves StorageBackend from document.storage_backend | ✓ |
| Separate /api/documents/{id}/cloud-content | Parallel endpoint for cloud docs | |
| Temporary cloud provider URL (redirect) | Return provider's signed download URL to browser — exposes cloud URLs | |

**User's choice:** Same proxy endpoint
**Notes:** Frontend remains storage-backend-agnostic.

### Cloud folder tree freshness

| Option | Description | Selected |
|--------|-------------|----------|
| Live calls + 60s in-memory TTL cache | Per-folder cache keyed by user+provider+path; 60s TTL | ✓ |
| Live calls only, no cache | Always fresh; no protection against rapid UI interactions | |
| You decide | | |

**User's choice:** Live calls + 60s in-memory TTL cache
**Notes:** User raised valid concern about cloud API rate limits and potential throttling. Claude explained: human-paced browsing is well within all provider limits (Google Drive: 12k req/100s per user); TTL cache protects against collapse/re-expand patterns. No DB sync needed.

---

## Claude's Discretion

- Python OAuth library choice (Google: `google-auth-oauthlib`; Microsoft: `msal`)
- WebDAV Python library choice (`webdavclient3` vs. `aiohttp` with manual PROPFIND)
- TTL cache implementation (`cachetools.TTLCache` vs. dict + timestamp)
- OAuth state store implementation (Redis / short-lived DB row / signed JWT)

## Deferred Ideas

- Document migration between backends (local → cloud)
- Cloud-native resumable upload URLs (performance optimization)
- Shared/team cloud storage
- Cloud folder tree DB sync / offline cache
- Email notifications on REQUIRES_REAUTH