# VoiceScribe Pro - Data Model Documentation

## Entity-Relationship Diagram

```mermaid
erDiagram
    User {
        UUID id PK
        string email
        string displayName
        timestamp createdAt
        timestamp lastActiveAt
        enum subscriptionTier
        enum subscriptionStatus
        timestamp subscriptionExpiresAt
        timestamp trialEndsAt
        int wordsUsedThisWeek
        int weeklyWordLimit
        stringArray preferredLanguages
        string defaultLanguage
        enum whisperModelSize
        bool enableCloudProcessing
        bool enableTelemetry
        bool privacyMode
        int totalWordsTranscribed
        int totalDictationSessions
        double averageWordsPerSession
        timeInterval totalTimeSpentDictating
        UUID teamId
        enum role
    }

    DictationSession {
        UUID id PK
        timestamp createdAt
        timestamp completedAt
        string applicationName
        string applicationBundleId
        enum contextType
        string language
        enum whisperModelUsed
        string audioFilePath
        double audioDurationSeconds
        int audioSampleRate
        int audioChannels
        string rawTranscript
        string enhancedTranscript
        string finalText
        double confidence
        int asrLatencyMs
        int llmLatencyMs
        int totalLatencyMs
        int wordCount
        string processingError
        stringArray fillersRemoved
        int grammarCorrections
        bool punctuationAdded
        int caseCorrections
        int editingCommands
        enum status
        bool isCloudProcessed
        bool privacyMode
    }

    VoiceCommand {
        UUID id PK
        string command
        string originalText
        string modifiedText
        enum commandType
        int processingTimeMs
        timestamp timestamp
    }

    PersonalDictionaryEntry {
        UUID id PK
        string word
        string pronunciation
        timestamp createdAt
        timestamp lastUsedAt
        bool learnedAutomatically
        double confidence
        int usageCount
        stringArray contextHints
        enum wordType
        enum category
        string language
        stringArray alternatives
        bool isCustom
        bool isActive
        string notes
    }

    Snippet {
        UUID id PK
        string name
        string trigger
        string content
        timestamp createdAt
        timestamp lastUsedAt
        enum category
        string language
        bool isActive
        int usageCount
        int estimatedSavingsSeconds
        bool isFormatted
        stringArray placeholders
        enumArray contextTypes
        bool isShared
        UUID createdByUserId
        UUID teamId
    }

    UserStatistic {
        UUID id PK
        date date
        UUID userId
        int wordsTranscribed
        int sessionsCount
        timeInterval totalDictationTime
        double averageSessionLength
        double averageWordsPerMinute
        double averageConfidence
        double errorRate
        int correctionsCount
        double averageLatency
        int cloudProcessingUsed
        int onDeviceProcessingUsed
        int voiceCommandsUsed
        int snippetsUsed
        int fillersRemoved
        int languagesSwitched
        json applicationUsage
        timeInterval estimatedTimeSaved
        double productivityScore
    }

    Team {
        UUID id PK
        string name
        string slug
        timestamp createdAt
        timestamp updatedAt
        enum subscriptionTier
        enum subscriptionStatus
        int maxUsers
        int currentUsers
        stringArray allowedDomains
        bool requireApproval
        bool enableSharedDictionary
        bool enableSharedSnippets
        bool enforcePrivacyMode
    }

    TeamMember {
        UUID id PK
        UUID userId
        enum role
        timestamp joinedAt
        UUID invitedBy
        enum status
        enumArray permissions
    }

    TeamDictionary {
        UUID id PK
        string word
        string pronunciation
        string definition
        enum category
        string language
        UUID createdByUserId
        timestamp createdAt
        UUID approvedBy
        timestamp approvedAt
        enum status
        int usageCount
        bool isActive
    }

    TeamSnippet {
        UUID id PK
        string name
        string trigger
        string content
        enum category
        string language
        UUID createdByUserId
        timestamp createdAt
        UUID approvedBy
        timestamp approvedAt
        enum status
        int usageCount
        bool isActive
        stringArray tags
    }

    AppSettings {
        UUID id PK
        UUID userId
        timestamp lastUpdated
        string globalHotkey
        string stopRecordingHotkey
        string cancelRecordingHotkey
        string commandModeHotkey
        string preferredMicrophone
        float inputGain
        enum noiseSuppressionLevel
        bool enableVAD
        float vadSensitivity
        enum preferredWhisperModel
        bool enableCloudProcessing
        bool fallbackToAppleSpeech
        int maxProcessingTime
        string primaryLanguage
        stringArray enabledLanguages
        bool autoLanguageDetection
        bool languageSwitchingEnabled
        bool enableFillerRemoval
        bool enableGrammarCorrection
        bool enablePunctuationInsertion
        bool enableCapitalization
        enum enhancementLevel
        bool showRecordingOverlay
        enum overlayPosition
        float overlayOpacity
        bool showWaveform
        bool showLiveTranscription
        bool showWordCount
        bool enableHapticFeedback
        bool privacyMode
        bool storeAudioFiles
        int audioRetentionDays
        bool shareUsageData
        bool enableCrashReporting
        bool enableSnippets
        bool enablePersonalDictionary
        bool enableAutoLearning
        bool showProductivityStats
        int dailyGoal
        bool debugMode
        bool betaFeatures
        json customPrompts
        stringArray experimentalFeatures
    }

    ApplicationContext {
        UUID id PK
        string bundleId
        string applicationName
        enum contextType
        string customPrompt
        stringArray enabledFeatures
        bool isActive
        timestamp lastUsed
        int usageCount
        string preferredLanguage
        enum enhancementLevel
        bool enableSnippets
        stringArray customSnippets
    }

    %% Relationships
    User ||--o{ DictationSession : "has many"
    User ||--o{ PersonalDictionaryEntry : "owns"
    User ||--o{ Snippet : "creates"
    User ||--o{ UserStatistic : "tracks"
    User ||--|| AppSettings : "configures"
    
    DictationSession ||--o{ VoiceCommand : "contains"
    DictationSession ||--o{ PersonalDictionaryEntry : "learns from"
    
    Team ||--o{ TeamMember : "has members"
    Team ||--o{ TeamDictionary : "shared dictionary"
    Team ||--o{ TeamSnippet : "shared snippets"
    
    TeamMember }o--|| User : "belongs to"
    
    ApplicationContext ||--o{ DictationSession : "provides context"
```

## Database Schema Overview

### Core Entities

#### User Entity
- **Purpose**: Central user account and subscription management
- **Key Relationships**: One-to-many with sessions, dictionary entries, snippets, and statistics
- **Notable Fields**: 
  - Subscription tier and limits
  - Usage tracking (words, sessions, time)
  - Language preferences
  - Processing preferences

#### DictationSession Entity
- **Purpose**: Records each voice dictation session with complete metadata
- **Key Relationships**: Belongs to User, contains VoiceCommands, generates PersonalDictionaryEntries
- **Notable Fields**:
  - Application context (name, bundle ID, context type)
  - Audio metadata (duration, sample rate, file path)
  - Transcription results (raw, enhanced, final)
  - Performance metrics (latency, confidence)
  - Enhancement tracking (fillers removed, corrections made)

#### PersonalDictionaryEntry Entity
- **Purpose**: User's custom vocabulary learned automatically or manually added
- **Key Relationships**: Belongs to User, optionally linked to learning DictationSession
- **Notable Fields**:
  - Word classification (proper noun, technical term, etc.)
  - Usage statistics and confidence scoring
  - Context hints for better recognition

#### Snippet Entity
- **Purpose**: Text expansion shortcuts triggered by voice
- **Key Relationships**: Belongs to User, can be shared with Team
- **Notable Fields**:
  - Voice trigger phrase
  - Content with placeholder support
  - Usage tracking and time savings estimation

### Statistics & Analytics

#### UserStatistic Entity
- **Purpose**: Daily aggregated statistics per user
- **Key Relationships**: Belongs to User
- **Notable Fields**:
  - Productivity metrics (words per minute, time saved)
  - Accuracy metrics (confidence, error rate)
  - Feature usage tracking
  - Application-specific breakdowns

#### SystemPerformance Entity
- **Purpose**: Technical performance monitoring
- **Usage**: Helps optimize model selection and identify issues
- **Notable Fields**:
  - Device-specific metrics
  - Processing times and resource usage
  - Error tracking and crash logs

### Team & Enterprise

#### Team Entity
- **Purpose**: Multi-user organization management
- **Key Relationships**: Has many TeamMembers, shared TeamDictionary and TeamSnippets
- **Notable Fields**:
  - Subscription management for groups
  - Sharing preferences and permissions
  - Domain-based user management

#### TeamDictionary & TeamSnippet Entities
- **Purpose**: Shared vocabulary and snippets across team members
- **Approval Workflow**: Pending → Approved/Rejected status
- **Notable Fields**:
  - Creator and approver tracking
  - Usage statistics across team

### Configuration & Settings

#### AppSettings Entity
- **Purpose**: Comprehensive user preferences and configuration
- **Key Relationships**: One-to-one with User
- **Sections**:
  - Keyboard shortcuts and audio settings
  - Processing and language preferences  
  - UI customization options
  - Privacy and data handling preferences
  - Productivity features configuration

#### ApplicationContext Entity
- **Purpose**: Per-application customization and optimization
- **Key Relationships**: Referenced by DictationSessions
- **Notable Fields**:
  - Context-specific prompts and enhancement levels
  - Application-specific feature enablement
  - Custom snippet associations

## Data Flow Architecture

### Session Lifecycle
1. **Session Start**: Create DictationSession with application context
2. **Audio Capture**: Store audio metadata and optional file path
3. **Processing**: Record ASR and LLM processing metrics
4. **Enhancement**: Track specific improvements made to text
5. **Completion**: Update user statistics and learn new vocabulary
6. **Analytics**: Aggregate into daily UserStatistic record

### Learning Pipeline
1. **Automatic Learning**: Extract proper nouns and technical terms from successful sessions
2. **Confidence Scoring**: Start with moderate confidence, increase with usage
3. **Context Association**: Link learned words to application contexts
4. **User Curation**: Allow manual review and editing of learned entries

### Team Sharing Workflow
1. **Creation**: Team member creates dictionary entry or snippet
2. **Approval Queue**: Pending status until admin approval
3. **Distribution**: Approved items available to all team members
4. **Usage Tracking**: Monitor adoption and effectiveness across team

## Performance Considerations

### Indexing Strategy
- **User queries**: Index on `User.id`, `User.email`
- **Session queries**: Composite index on `(user_id, created_at)`
- **Statistics queries**: Composite index on `(user_id, date)`
- **Dictionary lookups**: Index on `(user_id, word, is_active)`
- **Snippet triggers**: Index on `(user_id, trigger, is_active)`

### Data Retention
- **Audio files**: Configurable retention (0-90 days)
- **Session transcripts**: Indefinite retention for user review
- **Statistics**: Daily aggregation with optional raw data cleanup
- **Performance metrics**: Rolling 30-day window for system optimization

### Sync Strategy
- **CloudKit Integration**: Automatic sync for user data across devices
- **Conflict Resolution**: Timestamp-based with manual review option
- **Privacy Compliance**: Encrypted transmission, local-first storage
- **Team Data**: Separate sync container for enterprise customers

## Security & Privacy

### Data Classification
- **Public**: Application contexts, global analytics (anonymized)
- **Private**: User sessions, personal dictionary, individual statistics
- **Confidential**: Team data, enterprise audit logs
- **Restricted**: Audio files, raw transcripts (with user consent)

### Access Control
- **User Data**: Isolated by user ID, no cross-user access
- **Team Data**: Role-based permissions (owner/admin/member/readonly)
- **Enterprise Data**: Additional audit logging and compliance features

### Compliance Features
- **GDPR**: Data export, deletion, and consent management
- **HIPAA**: Audit logging and data encryption for enterprise
- **SOC 2**: System performance monitoring and security controls

This data model provides a comprehensive foundation for your VoiceScribe Pro application, supporting all the features outlined in your PRD while maintaining scalability, performance, and privacy compliance.