kite/.planning/phases/12-cloud-resource-foundation/12-PATTERNS.md

Phase 12: Cloud Resource Foundation - Pattern Map

Mapped: 2026-06-18 Status: Complete

Purpose

Map Phase 12 files and data flow to existing DocuVault patterns so implementation extends established architecture without duplicating helpers, grids, or provider-specific UI logic.

Backend Pattern Map

New/changed area	Closest analog	Pattern to preserve
backend/migrations/versions/0006_cloud_resource_foundation.py	0005_system_settings.py	Typed Alembic table creation, named constraints/indexes, timezone timestamps, exact down_revision="0005", reversible downgrade
CloudItem and connection fields in backend/db/models.py	CloudConnection, Document, Folder	UUID PKs, explicit owner FKs with cascade, compound owner/navigation indexes, human names in DB only
backend/storage/cloud_base.py	backend/storage/base.py, backend/ai/base.py	Small abstract interface; normalized domain values; provider adapters own translation
Provider capability/metadata normalization	Existing Google/OneDrive/Nextcloud adapters	Keep SDK/HTTP details inside provider files, wrap synchronous SDK calls with asyncio.to_thread(), preserve canonical CloudConnectionError import
backend/services/cloud_items.py	Owner-scoped query patterns in api/folders.py, service exception policy in AGENTS.md	Filter by owner in every statement; service raises ValueError/domain exceptions, never HTTPException; use shared deps.utils.parse_uuid at router boundary
backend/api/cloud/ package	backend/api/documents/ and backend/api/admin/	One aggregator owns /api/cloud; sub-routers have no prefix; root empty-path routes register on parent if FastAPI requires it
Cloud response schemas	CloudConnectionOut in backend/api/schemas.py	Explicit field whitelist with from_attributes; never serialize ORM objects or credentials_enc directly
Metadata refresh/backoff	Celery retry conventions in document tasks	Bounded exponential retry, idempotent upsert/reconciliation, no retry around ownership/validation failures

Required Backend Corrections

• Current _upsert_cloud_connection() and _get_active_connection() use (user_id, provider) and must not be copied. Phase 12 uses connection UUID as identity to support multiple same-provider accounts.
• Current listing cache key {user_id}:{provider}:{folder_id} is insufficient. Any transitional key includes connection UUID; durable metadata belongs in PostgreSQL.
• Current provider listing dictionaries contain only id, name, is_dir, size. New adapters normalize parent, MIME/type, mtime, etag/version, per-item capabilities, and completeness/pagination.
• api/folders.py contains a private _parse_uuid; new cloud routers must import parse_uuid from backend/deps/utils.py under the project’s shared-helper rule.

Frontend Pattern Map

New/changed area	Closest analog	Pattern to preserve
Capability-aware rows	frontend/src/components/storage/StorageBrowser.vue	This remains the only grid; props drive layout/state and generic events travel upward
Sync indicator	frontend/src/components/ui/BreadcrumbBar.vue	Extend shared breadcrumb rather than adding cloud-only breadcrumb markup
Connection roots	Current CloudStorageView.vue plus StorageBrowser.vue	View owns store/router only; feed normalized root rows into shared browser
Cloud folder route	CloudFolderView.vue, FileManagerView.vue	Thin data provider; no duplicated toolbar, row, action, or tooltip layout
API functions	frontend/src/api/cloud.js + client.js barrel	Change route arguments behind the domain module; consumers retain barrel imports
Connection state	frontend/src/stores/cloudConnections.js	Pinia owns connection/folder state and errors; components stay store-agnostic
Shared formatting	frontend/src/utils/formatters.js	Reuse formatDate, formatSize, and provider helpers; do not redefine locally
Icons	frontend/src/components/ui/AppIcon.vue	Add registry entries only when an existing icon name cannot express status/action

UI Contract Patterns

• Unsupported actions use aria-disabled="true", remain focusable/tappable, and suppress action emission while surfacing explanation.
• Permanent unsupported state is gray; temporary unavailable state is amber. Do not hide actions based on mode === "local".
• StorageBrowser receives capabilities, folder freshness, connection root, last refresh time, and byte availability as props.
• Local storage supplies a supported capability set so local/cloud share one rendering path.
• Minimum touch target stays 36x36 px and all controls use existing indigo focus-ring utilities.
• Session-only last folder state uses sessionStorage keyed by connection UUID; JWT tokens remain Pinia-memory-only.

Testing Pattern Map

Coverage	Existing analog	Phase 12 use
API/ownership	backend/tests/test_cloud.py	Multiple same-provider accounts, foreign connection/item 404, admin rejection, credential exclusion
Adapter contracts	backend/tests/test_cloud_backends.py	Shared normalized fixtures, async methods, pagination/completeness, no destructive probes
DB/service	async fixtures in backend/tests/conftest.py	Fast SQLite unit loop plus marked real-PostgreSQL constraint/index/cascade tests
Pinia	frontend/src/stores/__tests__/cloudConnections.test.js	Connection UUID routes, duplicate providers, freshness/error transitions
Storage browser	StorageBrowser.dragmove/showSearch/skeleton.test.js	Capability rendering, action suppression, focus/tap explanations, local regression
Breadcrumb	components/ui/__tests__/BreadcrumbBar.test.js	Refreshing/fresh/warning labels, timestamps, fade behavior
Thin views	views/__tests__/FileManagerView.test.js	Cloud views pass props/handle events without grid duplication

Data Flow

1. Router authenticates regular user and parses connection_id with shared request helpers.
2. Service resolves (connection_id, user_id) and reads durable children by connection/parent.
3. Provider adapter normalizes a complete paginated listing and capability states.
4. Service upserts metadata using (connection_id, provider_item_id) and reconciles only after complete success.
5. Explicit Pydantic schemas return rows, capability messages, freshness, and connection identity without credentials.
6. Pinia/view maps API data into StorageBrowser; the browser renders shared rows/actions and emits generic commands.
7. Browse never calls provider byte download, writes MinIO, or changes quota.

Files Likely Modified

Backend

• backend/migrations/versions/0006_cloud_resource_foundation.py
• backend/db/models.py
• backend/storage/cloud_base.py
• backend/storage/cloud_backend_factory.py
• provider backend modules
• backend/services/cloud_items.py
• backend/api/cloud/__init__.py, connections.py, browse.py, schemas.py
• backend/main.py only if aggregator import changes
• focused backend tests and PostgreSQL integration coverage

Frontend

• frontend/src/api/cloud.js
• frontend/src/stores/cloudConnections.js
• frontend/src/router/index.js
• frontend/src/views/CloudStorageView.vue
• frontend/src/views/CloudFolderView.vue
• frontend/src/components/storage/StorageBrowser.vue
• frontend/src/components/ui/BreadcrumbBar.vue
• focused component/store/view tests

Documentation/Versioning

• AGENTS.md, README.md, backend/main.py, and frontend/package.json per the project documentation/version protocol after user-facing plan completion.

PATTERN MAPPING COMPLETE