kite/.planning/research/SUMMARY.md

v0.3 Research Summary

Milestone: v0.3 Reimagining Cloud Storage integration Date: 2026-06-17

Stack Additions

• Keep the current stack and add a provider capability/action layer rather than replacing storage.
• Add PostgreSQL-backed cloud item metadata and analysis/index state.
• Add a bounded byte-cache/offload service for preview/extraction/open flows.
• Use Celery for cloud analysis, cache hydration, retries, and provider refresh jobs.
• Use PostgreSQL full-text search for keyword/sentence search; consider pgvector for idea/semantic search without a separate vector DB.

Feature Table Stakes

• Cloud files behave locally for open/preview/upload/move/delete/rename/create-folder where provider capabilities allow.
• Users can analyze selected files, folders, or whole connections.
• Analyzed cloud documents become classified and smart-searchable alongside local documents.
• Search never downloads bytes at query time; it reads persisted extracted/indexed data.
• DocuVault minimizes local storage by caching bytes only when needed and evicting them safely.

Architecture Direction

• Keep provider-owned cloud bytes as source of truth.
• Store metadata, text, topics, embeddings, and statuses in DocuVault.
• Separate local/imported documents from cloud item index records unless a later phase intentionally unifies them.
• Extend StorageBrowser.vue with capability-aware actions instead of creating a second file manager.
• Split backend/api/cloud.py as behavior grows.

Watch Out For

• Do not accidentally build a full cloud mirror.
• Treat destructive cloud actions as real provider mutations.
• Model provider capability differences explicitly.
• Track etags/versions so analyzed search data can become stale instead of silently wrong.
• Add preflight estimates and confirmation before large "analyze all" jobs.
• Preserve SSRF, credential encryption, ownership checks, and admin privacy boundaries.

Key Sources

• Microsoft Graph driveItem: https://learn.microsoft.com/en-us/graph/api/resources/driveitem?view=graph-rest-1.0
• Google Drive uploads: https://developers.google.com/workspace/drive/api/guides/manage-uploads
• Nextcloud WebDAV operations: https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/basic.html
• Celery task retries: https://docs.celeryq.dev/en/stable/userguide/tasks.html
• Redis cache eviction: https://redis.io/docs/latest/develop/reference/eviction/
• pgvector: https://github.com/pgvector/pgvector