Ebook Voice Player Privacy-First Architecture: Local Parsing, Minimal Cloud, Full Data Flow Transparency

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER DEVICE                                     │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────────┐  │
│  │  Document Files  │───▶│  Local Parser    │───▶│  Paragraphs (RAM)    │  │
│  │  (TXT/PDF/EPUB/  │    │  (reader.py)     │    │  - Zero network      │  │
│  │   DOCX/HTML)     │    │  - No cloud      │    │  - Full content      │  │
│  └──────────────────┘    └──────────────────┘    └──────────┬───────────┘  │
│                                                              │              │
│                          ┌───────────────────────────────────┘              │
│                          ▼                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    TTSService (Local Orchestration)                  │   │
│  │  - Playback state machine                                            │   │
│  │  - Audio queue management                                            │   │
│  │  - Bookmarks/Notes/Progress (local JSON)                            │   │
│  └──────────────────────────────────┬───────────────────────────────────┘   │
│                                     │                                        │
│                    ┌────────────────┴────────────────┐                      │
│                    ▼                                 ▼                      │
│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐   │
│  │      Local Cache            │    │      Network (HTTPS)            │   │
│  │  ~/.tts_ebook_reader/       │    │  *.azure.com / *.microsoft.com  │   │
│  │  audio_cache/c_<hash>.mp3   │    │  POST /cognitiveservices/v1     │   │
│  │  - SHA256(content|voice|rate)                 - Text only          │   │
│  │  - Atomic write + validate                     - No user ID        │   │
│  │  - User manually clearable                    - No metadata        │   │
│  └─────────────────────────────┘    └─────────────────────────────────┘   │
│                                     │                                        │
│                                     ▼                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                      Audio Playback (Local)                          │   │
│  │  - Kivy SoundLoader → SDL2 → System Audio                            │   │
│  │  - Zero network during playback                                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

# reader.py - All parsers are pure local library calls
def read_txt(filepath, encoding=None):
    # Pure file I/O + encoding detection, zero network requests
    ...

def read_pdf(filepath):
    # PyMuPDF / pdfplumber pure local parsing
    # Even encrypted PDFs only attempt local decryption
    ...

def read_epub(filepath):
    # ebooklib + BeautifulSoup pure local DOM traversal
    # EPUB internal resources (images/CSS/fonts) only read, never uploaded
    ...

def read_docx(filepath):
    # python-docx pure local XML parsing
    ...

# tts_engine.py - TTSGenerator.gen_one()
async def gen_one(idx, text):
    # Only sends: text content + voice ID + rate
    # Does NOT send: filename, chapter name, user settings, device info, identifiers beyond IP
    communicate = edge_tts.Communicate(text, self.voice, rate=rate_str)
    await communicate.save(str(tmp_file))

POST https://<region>.tts.speech.microsoft.com/cognitiveservices/v1
Headers:
  - Authorization: Bearer <short-lived token>  (edge service auto-fetches, no user credentials)
  - Content-Type: application/ssml+xml
  - X-Microsoft-OutputFormat: audio-24khz-48kbitrate-mono-mp3
Body (SSML):
  <speak version='1.0' xml:lang='zh-CN'>
    <voice xml:lang='zh-CN' xml:gender='Female' name='zh-CN-XiaoxiaoNeural'>
      <prosody rate='+10%'>Chapter One Content...</prosody>
    </voice>
  </speak>

# main_screen.py - save_settings()
def save_settings(self):
    data = {
        "font_size": self.font_size,
        "line_spacing": self.line_spacing,
        "page_margin": self.page_margin,
        "dark_mode": self._dark,
        "ui_lang": get_language(),           # UI language preference only
        "recent_files": self.recent_files,   # Local file path list
        "bookmarks": self.bookmarks,         # {file, paragraph, label}
        "annotations": self.annotations,     # {paragraph: note_text}
        "reading_stats": {                   # Aggregate counters only
            "total_sec": self._stats["total_sec"],
            "total_paras": self._stats["total_paras"],
        },
        "last_file": self._last_file,        # Last opened file path
        "last_position": self._last_position, # {file, paragraph}
    }
    # Storage: %APPDATA%\EbookVoicePlayer\settings.json (Windows)
    # or ~/.config/EbookVoicePlayer/settings.json (Linux/Android)
    with open(self._settings_path(), "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)

# tts_engine.py - get_cache_dir() & cleanup()
def get_cache_dir():
    app = App.get_running_app()
    if app is not None:
        base = Path(app.user_data_dir)  # System-assigned app private dir
    else:
        base = Path.home() / ".tts_ebook_reader"
    d = base / "audio_cache"
    d.mkdir(parents=True, exist_ok=True)
    return d

def cleanup(self):
    """User manual cleanup / auto on uninstall"""
    for f in get_cache_dir().glob("*.mp3"):
        try:
            f.unlink()
        except OSError:
            pass
    self._stale = []

# 1. Create allow rule for only above domains
New-NetFirewallRule -DisplayName "EbookVoicePlayer Allow TTS" `
    -Direction Outbound -Action Allow `
    -Program "C:\Program Files\WindowsApps\nannan2008.EbookVoicePlayer_*\TTSReader.exe" `
    -RemoteAddress (Resolve-DnsName "*.azure.com", "*.microsoft.com" -Type A).IPAddress

# 2. Block all other outbound
New-NetFirewallRule -DisplayName "EbookVoicePlayer Block Other" `
    -Direction Outbound -Action Block `
    -Program "C:\Program Files\WindowsApps\nannan2008.EbookVoicePlayer_*\TTSReader.exe" `
    -RemoteAddress Any

# 3. Verify: Wireshark capture shows ONLY TTS requests
# Filter: http.host contains "azure" or http.host contains "microsoft"

Normal session contains ONLY:
1. DNS query: <region>.tts.speech.microsoft.com
2. TLS handshake (TLS 1.2/1.3)
3. HTTP/2 POST /cognitiveservices/v1 (SSML body)
4. HTTP/2 200 OK (MP3 binary response)
5. Zero network during playback

Anomaly indicators (MUST NOT appear):
❌ Any analytics/telemetry endpoints
❌ Any ad/tracking domains
❌ Any non-azure/microsoft domains
❌ Any non-443 port connections
❌ Any periodic heartbeat/reporting traffic

# 1. Search network library imports
grep -r "requests\|httpx\|aiohttp\|urllib\|socket" --include="*.py" .

# Expected: ONLY in tts_engine.py via edge_tts indirect usage

# 2. Search telemetry/analytics keywords
grep -ri "telemetry\|analytics\|tracking\|metrics\|sentry\|crashlytics\|firebase\|amplitude\|mixpanel" --include="*.py" .

# Expected: ZERO matches

# 3. Search ad SDKs
grep -ri "admob\|adsense\|unityads\|applovin\|chartboost\|vungle\|ironsource" --include="*.py" .

# Expected: ZERO matches

# 4. Search account/auth related
grep -ri "oauth\|login\|register\|account\|password\|token\|jwt\|api_key" --include="*.py" .

# Expected: ONLY edge-tts internal token handling, no user auth flows

# 5. Search data upload
grep -ri "upload\|sync\|backup\|cloud\|remote.*config" --include="*.py" .

# Expected: ZERO matches

# requirements.txt
edge-tts==6.1.9
kivy==2.3.0
python-docx==1.1.0
PyMuPDF==1.23.0
pdfplumber==0.10.0
ebooklib==0.18
beautifulsoup4==4.12.0
lxml==4.9.0

# Audit Points:
# - NO requests/httpx direct HTTP libs (edge-tts uses aiohttp internally)
# - NO telemetry/analytics packages
# - NO ad SDK dependencies
# - All deps are well-known open-source, source auditable

# Monitor network connections at startup (Windows)
# Use TCPView / Resource Monitor / Wireshark

# 1. Launch app → ZERO network connections established
# 2. Open local EPUB → ZERO network connections
# 3. Click Play → Establish TLS to *.azure.com:443
# 4. Pause/Stop → Connection held or closed, no new connections
# 5. Switch voice/rate → New synthesis connections, old reused
# 6. Idle 10 minutes → ZERO heartbeat connections
# 7. Close app → All connections closed

# 1. Pre-warm cache: batch synthesize needed chapters in connected env
#    - Open book → Select all → Export MP3 (Menu: Tools → Export to Audio Files)
#    - After export, cache dir contains all paragraph audio

# 2. Offline deploy: Copy installer + cache dir to target machine
#    - Install app
#    - Copy cache dir to %APPDATA%\EbookVoicePlayer\audio_cache\

# 3. Offline use: Fully disconnected
#    - Open book → Parsing works
#    - Play → Reads cached MP3 directly, ZERO network
#    - Bookmarks/notes/progress → All local save

# Enterprise firewall/proxy policy example
rules:
  - name: "EbookVoicePlayer TTS Allow"
    action: allow
    app: "TTSReader.exe"
    dst_domains:
      - "*.azure.com"
      - "*.microsoft.com"
    dst_ports: [443]
    protocol: tcp

  - name: "EbookVoicePlayer Default Deny"
    action: deny
    app: "TTSReader.exe"
    dst: any
    log: true