Spec: Cloud Sync & Sharing

Overview

Enable saving circuit files to cloud storage, sharing circuits via links, and optionally collaborating with others. Provides cross-device access and easy sharing for educational settings.

Motivation

• Students need to share circuits with instructors for grading.
• Users want to access their designs from multiple computers.
• Instructors want to distribute template circuits to entire classes.
• Community sharing enables a library of example circuits.
• Backup protection against local data loss.

Requirements

Functional Requirements

Cloud Storage

1. Cloud Save: Save circuit files to cloud storage (user's account).
2. Cloud Open: Browse and open circuits from cloud storage.
3. Auto-Sync: Optionally sync a local folder with cloud storage.
4. Conflict Resolution: Handle simultaneous edits with merge or last-writer-wins.
5. Offline Support: Work offline; sync when connection restored.
6. Version History: Cloud-stored files maintain version history.

Sharing

7. Share via Link: Generate a shareable URL for any circuit.
8. Permission Levels: View-only, duplicate (fork), or edit permissions.
9. Public/Private: Circuits can be public (anyone with link) or private (specific users).
10. Embed Code: Generate HTML embed code for websites/LMS.
11. QR Code: Generate QR code for easy mobile/classroom sharing.

Collaboration (Future)

12. Real-Time Collaboration: Multiple users edit the same circuit simultaneously.
13. Presence Indicators: See who else is viewing/editing.
14. Comments: Add comments on specific components or areas.
15. Change Attribution: Track who made each change.

Community

16. Public Gallery: Browse community-shared circuits by category.
17. Templates: Use shared circuits as starting templates.
18. Ratings/Favorites: Rate and bookmark shared circuits.

Non-Functional Requirements

• Cloud operations complete in under 3 seconds on reasonable internet.
• Offline-first: app works fully without internet; sync is additive.
• Data encrypted in transit (TLS) and at rest.
• User data is private by default; sharing is opt-in.
• Storage quota: at least 100MB per free user.

Design

Architecture

DigitalWorks App
    → CloudService (abstraction layer)
        → StorageProvider (OneDrive / GitHub / Custom backend)
        → SharingService (link generation, permissions)
        → SyncEngine (local ↔ cloud reconciliation)

Authentication

• Microsoft Account (OneDrive integration).
• GitHub (Gist/Repo for circuits).
• Custom backend (email/password or OAuth).

Storage Options

Provider	Pros	Cons
OneDrive	Native Windows integration	Microsoft account required
GitHub Gists	Version control built-in	Technical barrier for students
Custom Backend	Full control	Hosting cost, maintenance
Firebase	Real-time sync	Google dependency

Sync Strategy

1. Local file saved → compute hash
2. Compare with cloud version hash
3. If different:
   a. Cloud newer → pull and merge/overwrite
   b. Local newer → push to cloud
   c. Both changed → conflict resolution dialog
4. Maintain sync metadata (last sync time, version IDs)

Sharing Flow

User clicks "Share" → generates unique URL
    → https://digitalworks.app/circuit/{id}
    → Recipient clicks link → opens in app (or web viewer)
    → Permission check → view/fork/edit

Implementation Tasks

1. Design cloud service abstraction layer (ICloudStorageProvider).
2. Implement OneDrive/GitHub storage provider.
3. Implement authentication flow (OAuth 2.0).
4. Implement file upload/download with progress.
5. Implement sync engine with conflict detection.
6. Implement share link generation with permissions.
7. Create cloud file browser UI (open/save dialog).
8. Create sharing dialog (permissions, link copy, QR code).
9. Implement offline queue (pending uploads).
10. Create account/settings page for cloud configuration.
11. Implement public gallery browser (future phase).

Risks & Open Questions

• Which cloud provider to support first? OneDrive is natural for Windows.
• How to handle very large circuits (memory components with data)?
• Should real-time collaboration be in v1 or deferred to a later phase?
• Cost model: free tier vs. paid for extra storage/collaboration?
• Privacy: what data is sent to the cloud (telemetry, usage)?
• Web viewer: do we need a read-only web version for sharing recipients without the app?

Priority

Medium-Low — Nice-to-have for education scenarios, significant infrastructure investment.