Providers

Drive uses provider contracts so the UI does not need to know how storage is implemented.

Shared contract idea

The package defines a base DriveReader plus optional capabilities such as:

• DriveNodeMutations
• DriveDirectUpload
• DrivePresignedUpload
• DrivePreviewGenerator
• DriveReadonly
• DriveArchive

This is not just a docs abstraction. These contracts match the way the package is split in code:

• shared validators and DTO types live in @tulip-systems/drive
• provider-specific schemas and commands live in .../local and .../google
• client shells consume a provider-shaped node model without caring where it came from

Local provider

Use the local provider when your product owns:

• persistence
• upload sessions
• preview generation
• serving URLs
• archive and readonly policies

The local provider is the richer implementation today. It includes:

• upload intents and confirmation
• a route handler for opening files
• private/public asset visibility handling
• optimistic upload state
• archive and readonly toggles

Google provider

Use the Google provider when your product should work directly against a Google Drive tree while still rendering the same style of interface.

The Google provider maps Google-specific fields into the shared node model, while still exposing provider-specific metadata such as:

• googleDriveId
• mimeType
• webViewLink
• webContentLink
• thumbnailLink
• trashed / trashedAt
• googleParents
• canEdit

How to choose

Choose local when your app is the source of truth.

Choose google when Google Drive is the source of truth.

Avoid building a generic screen that assumes both providers behave identically around:

• upload flow
• URL generation
• archive semantics
• readonly enforcement
• remote consistency and caching