# 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