Add comprehensive iOS & Swift field guide documentation

[samkeen]

Summary

Added docs/relay-notes-ios-guide.html — a comprehensive, self-contained HTML field guide for seasoned programmers learning the Relay Notes codebase and iOS/Swift development patterns. The guide serves as a translation layer, mapping familiar software architecture concepts onto Swift, SwiftUI, and the app's concrete implementation.

Key Changes

• New documentation file: docs/relay-notes-ios-guide.html (1,274 lines)
  • Self-contained single-file HTML with embedded CSS and SVG diagrams
  • Dark theme optimized for readability (teal/indigo accent colors matching the app brand)
  • Responsive design with sticky sidebar navigation and mobile toggle
  • 12 major sections covering language, framework, concurrency, and architecture

Content Structure

The guide is organized as a progressive narrative:

1. §00 Start here — Positioning: what this guide is for and how to read it
2. §01 The 60-second tour — The recording pipeline and the transcription socket design
3. §02 The Rosetta Stone — Concept mapping (protocol ↔ interface, enum ↔ sum type, @mainactor ↔ UI thread affinity, etc.)
4. §03 Swift, the parts that bite — struct/class/actor/enum semantics, enums as tagged unions, state machines, optionals
5. §04 SwiftUI: UI as a function — Property wrappers (@State, @observable, @Environment, @query), composition root pattern
6. §05 Swift 6 concurrency — Actors, @mainactor, Sendable, AsyncStream, isolation domains (with diagram)
7. §06 The architecture spine — Protocol-based provider swapping, the Transcriber socket, factory pattern
8. §07 Tap → speak → saved — End-to-end data flow with concrete types
9. §08 Persistence: SwiftData — Model definition, queries, migrations
10. §09 Two engines, one socket — AppleSpeechTranscriber vs. WhisperMLXTranscriber implementation details
11. §10 iOS realities — AVAudioSession, interruptions, background modes, memory constraints
12. §11 Build & tooling — Xcode project structure, Swift Package Manager, test conventions
13. §12 Where to read next — Pointers to Apple docs, MLX, and further learning

Notable Implementation Details

• Diagrams: Inline SVG (no external dependencies) for the recorder state machine, concurrency isolation domains, and architecture overview
• Code examples: Syntax-highlighted Swift snippets with semantic token coloring (keywords, types, strings, comments)
• Callout styles: Tip/warning/gotcha/info boxes with left-border accent colors
• Responsive tables: Comparison tables for struct/class/actor/enum, property wrappers, and concept mapping
• Navigation: Sticky sidebar with numbered sections, smooth scroll anchors, mobile hamburger toggle
• Accessibility: Semantic HTML, ARIA labels, proper heading hierarchy

Rationale

This guide addresses the gap between "I can read Swift syntax" and "I understand how this app is built." It's written for people who already ship software in other languages/platforms and need a translation layer rather than a beginner tutorial. The guide is self-contained (single HTML file, no build step, no external CDN) so it can be read offline or embedded in documentation sites.

Per CLAUDE.md, this is a documentation artifact that future sessions will reference when onboarding to the codebase or explaining architectural decisions.

https://claude.ai/code/session_01W47XYXAX6wnMNT3KGJbzQh