Readme TTS Sharing Archtecture

Archtecure Decisions for Magic Link + QR Code Integration

1. Objective

Enable sharing of content (text, audio, image) via magic links and QR codes while maintaining a local-first, privacy-focused architecture. Ensure seamless syncing between local and Supabase databases with minimal UX friction.

---

2. Features

Magic Link

• Generate unique links for content that can be shared with other users.

• Links point to Supabase shared_content entries for download and import.

QR Code

• Generate scannable QR codes containing the magic link.

• QR codes enable offline sharing or fast access for nearby devices.

Database Adjustments

• Add uuid and expires_at to local Dexie.js database.

• Sync content and sharing metadata with Supabase shared_content table.

• Maintain user privacy by avoiding sensitive user-identifiable data.

---

3. Local Database Schema (Dexie.js)

Tables

1. textToSpeech

   • Fields:

     • id: Auto-incremented ID.

     • uuid: Unique identifier for syncing and sharing.

     • text: Original text content.

     • audioData: Binary data for audio.

     • imageUrl: Local or cloud URL of associated image.

     • sourceType: Content source ('url' | 'paste').

     • sourceUrl: Source URL (if applicable).

     • syncStatus: Status ('pending' | 'synced' | 'shared').

     • expires_at: Expiration timestamp for shared content.

     • size: Total size of content (text + audio).

     • timestamp: Creation or last modified time.

     • tokenCount: Token usage for billing or analytics.

2. awsCredentials

   • Fields:

     • id: Auto-incremented ID.

     • accessKeyId: Encrypted AWS Access Key ID.

     • secretAccessKey: Encrypted AWS Secret Key.

     • region: Encrypted AWS region.

---

4. Supabase Schema

Tables

1. shared_content

   • Fields:

     • id: Auto-incremented ID.

     • uuid: Unique identifier for sharing.

     • text: Original text content.

     • audio_path: Cloud storage path for audio file.

     • image_path: Cloud storage path for associated image.

     • source_url: Source URL (if applicable).

     • source_type: Content source ('url' | 'paste').

     • created_at: Timestamp of creation.

     • expires_at: Expiration timestamp for the shared content.

   • Key Features:

     • Use uuid as the primary identifier for syncing and sharing.

2. aws_credentials

   • Fields:

     • Matches local database schema but includes created_at and updated_at.

---

5. Workflow Implementation

Magic Link

1. Link Generation

   • Generate a UUID for the content (local database).

   • Sync the content to Supabase shared_content table.

   • Upload audio and image files to Supabase storage, and update audio_path and image_path.

   • Generate the magic link: https://app.com/sync/{uuid}.

2. Link Sharing

   • Provide users with an option to copy the magic link.

3. Content Retrieval

   • On receiving the link, query Supabase using the UUID to fetch the associated content.

   • Import content into the recipient's local Dexie.js database.

---

QR Code

1. Code Generation

   • Use the magic link to generate a QR code (e.g., using qrcode.react or qrcode.js).

   • Display the QR code in the sharing UI.

2. QR Code Scanning

   • Decode the link using a QR code scanner (e.g., zxing or built-in browser capabilities).

   • Process the link as a normal magic link to retrieve content.

---

Syncing with Supabase

1. Sync Logic

   • On app launch, query Supabase for content linked to the user's device_id or matching the local uuid.

   • Fetch new or updated entries and merge them into the local database.

2. Conflict Resolution

   • Use timestamp to determine the most recent update and apply changes accordingly.

3. Scheduled Sync

   • Periodically sync pending entries (syncStatus = 'pending') to Supabase in the background.

---

Offline Sharing

1. QR Code

   • Enables offline device-to-device sharing when the recipient has the app installed.

2. Import Flow

   • Upon scanning, the app decodes the link and fetches content when the device is online.

---

6. UX Guidelines

1. Minimal Friction

   • Auto-generate links/QR codes without requiring manual user input.

   • Add clear UI buttons for sharing via magic links or QR codes.

2. Visual Feedback

   • Indicate the sync status of content (pending, synced, shared).

3. Privacy Assurance

   • Clearly communicate that sensitive data stays local and sharing is opt-in.

---

7. Implementation Steps

1. Local Database Adjustments

   • Update Dexie.js schema to include uuid and expires_at.

2. Supabase Integration

   • Ensure Supabase schema is aligned with the updated local schema.

3. Magic Link Functionality

   • Implement UUID generation, cloud syncing, and link sharing.

4. QR Code Functionality

   • Add QR code generation and decoding using a library like qrcode.react.

5. Sync Mechanism

   • Set up periodic and on-demand sync flows between Dexie.js and Supabase.

---

8. Required Dependencies

• UUID Generation: uuid

• QR Code Library: qrcode.react or qrcode

• Encryption: Existing implementation for AWS credentials can be reused.

---

9. Future Enhancements

• Encrypted Magic Links

  • Use encrypted UUIDs for additional security.

• Custom Expiration

  • Allow users to set custom expiration times for shared content.

This specification ensures a seamless sharing experience while maintaining privacy and user control. Let me know if any further refinements are needed!