Serenity Soother — System Glossary

# Serenity Soother — System Glossary
Version: 1.0.0
Status: ACTIVE
Created: 2025-12-26
Last Modified: 2025-12-26

---

Purpose

This glossary defines every core term used in the Serenity Soother project. Each definition includes:
- What it is: Precise definition
- What it is not: Explicit exclusions to prevent confusion
- Layer: Where this concept exists (Conceptual, Architectural, Runtime, Data, UI)

No overloaded or ambiguous language is permitted beyond this document.

---

Core Domain Terms

### Scene
| Attribute | Value |
|-----------|-------|
| What it is | A complete meditation experience consisting of 30 synchronized segments, each with an image, caption, prompt, and optional audio |
| What it is not | A single image; a video file; a streaming resource |
| Layer | Conceptual, Data |
| Swift Type | `PrecomputedScene` |
| Storage | Folder in `1792x1024/[index]/` containing subdirectories |

### Segment
| Attribute | Value |
|-----------|-------|
| What it is | A single unit within a Scene; contains one image, one caption, one prompt, and optionally one audio track |
| What it is not | A time-based slice; a frame; an arbitrary division |
| Layer | Conceptual, Data |
| Swift Type | `PrecomputedSegment` |
| Storage | Files at `image/[uuid]/image_N.png`, `caption/[uuid]/caption_N.txt`, `prompt/[uuid]/prompt_N.txt` |

### Session
| Attribute | Value |
|-----------|-------|
| What it is | A single playback instance of a Script or Scene, with start time, duration, and completion status |
| What it is not | A Scene itself; a Script; a user profile |
| Layer | Data, Runtime |
| Swift Type | `Session` (SwiftData model) |
| Storage | SwiftData persistent store |

### Script
| Attribute | Value |
|-----------|-------|
| What it is | A text-based hypnotherapy script, either AI-generated or user-created, with title, content, duration, and therapeutic metadata |
| What it is not | A Scene; a precomputed asset; audio content |
| Layer | Data |
| Swift Type | `Script` (SwiftData model) |
| Storage | SwiftData persistent store |

### Therapeutic Profile
| Attribute | Value |
|-----------|-------|
| What it is | User-provided preferences including primary concerns, preferred themes, session duration preferences, and therapeutic goals |
| What it is not | Medical diagnosis; treatment plan; prescription |
| Layer | Data |
| Swift Type | `TherapeuticProfile` (SwiftData model) |
| Storage | SwiftData persistent store |

---

UI/Presentation Terms

### AppearanceMode
| Attribute | Value |
|-----------|-------|
| What it is | User preference for visual theme: Light, Dark, System, or TimeOfDay |
| What it is not | The actual rendered color scheme (which is `ColorScheme`) |
| Layer | UI, Data |
| Swift Type | `AppearanceMode` enum |
| Values | `.light`, `.dark`, `.system`, `.timeOfDay` |

### ColorScheme
| Attribute | Value |
|-----------|-------|
| What it is | SwiftUI's binary light/dark mode indicator, resolved from AppearanceMode |
| What it is not | The user's preference (that's `AppearanceMode`) |
| Layer | UI (SwiftUI native) |
| Swift Type | `ColorScheme` (SwiftUI) |
| Values | `.light`, `.dark` |

### TimePeriod
| Attribute | Value |
|-----------|-------|
| What it is | Time-of-day classification used for adaptive theming and greetings |
| What it is not | A date; a timestamp; a duration |
| Layer | Conceptual, UI |
| Swift Type | `TimePeriod` enum |
| Values | `.dawn`, `.morning`, `.afternoon`, `.evening`, `.night` |

### SerenityTheme
| Attribute | Value |
|-----------|-------|
| What it is | Centralized color and styling definitions for the app, providing dynamic colors based on ColorScheme |
| What it is not | A view modifier; a style sheet; a SwiftUI Environment value |
| Layer | UI |
| Swift Type | `SerenityTheme` (static namespace, aliased as `AppTheme`) |

---

Architecture Terms

### ViewModel
| Attribute | Value |
|-----------|-------|
| What it is | An `@MainActor` `ObservableObject` that owns UI state and mediates between Views and Services |
| What it is not | A data model; a service; a View |
| Layer | Architectural |
| Pattern | MVVM |
| Example | `SegmentMediaPlayerViewModel` |

### Service
| Attribute | Value |
|-----------|-------|
| What it is | A singleton or injected object that performs operations outside UI scope (API calls, file I/O, data processing) |
| What it is not | A ViewModel; a data model; a View |
| Layer | Architectural |
| Example | `PrecomputedSceneLibrary`, `AuthManager` |

### AppState
| Attribute | Value |
|-----------|-------|
| What it is | Global application state container, injected as `@EnvironmentObject`, managing onboarding status, active sessions, and appearance |
| What it is not | A ViewModel for a specific screen; a data model |
| Layer | Architectural |
| Swift Type | `AppState` class |

---

Data/Storage Terms

### SceneIndex
| Attribute | Value |
|-----------|-------|
| What it is | Cached metadata about all discovered precomputed scenes, including counts and last-indexed timestamp |
| What it is not | The scenes themselves; the segment data |
| Layer | Data |
| Swift Type | `PrecomputedSceneIndex` |
| Storage | UserDefaults (JSON encoded) |

### SynergyChatMetadata
| Attribute | Value |
|-----------|-------|
| What it is | JSON metadata file within a scene folder containing generation prompts, responses, and configuration |
| What it is not | The script content; the scene definition |
| Layer | Data |
| Swift Type | `SynergyChatMetadata` |
| Storage | `store/synergy_chat_N.json` files |

---

Playback Terms

### Playback State
| Attribute | Value |
|-----------|-------|
| What it is | Current status of media playback: playing, paused, stopped, loading |
| What it is not | The media content itself |
| Layer | Runtime |
| Represented by | `isPlaying`, `isLoading` booleans in ViewModel |

### Auto-Advance
| Attribute | Value |
|-----------|-------|
| What it is | Feature that automatically moves to the next segment when current segment's audio completes |
| What it is not | Looping; shuffling; manual navigation |
| Layer | Runtime, UI |
| Controlled by | `autoAdvance` boolean in `SegmentMediaPlayerViewModel` |

### Progress
| Attribute | Value |
|-----------|-------|
| What it is | Normalized (0.0-1.0) position within current segment's audio track |
| What it is not | Overall scene progress; segment index |
| Layer | Runtime |
| Swift Property | `progress: Double` |

---

File System Terms

### Precomputed Content Root
| Attribute | Value |
|-----------|-------|
| What it is | Base directory containing all precomputed scene folders |
| What it is not | App bundle; Documents directory |
| Layer | Data, Infrastructure |
| Path | `[home]/Desktop/SS/1792x1024/` |

### Scene Folder Structure
| Attribute | Value |
|-----------|-------|
| What it is | Standardized directory layout for a single scene |
| What it is not | Arbitrary file organization |
| Layer | Data |
| Structure | `[index]/image/[uuid]/`, `[index]/caption/[uuid]/`, `[index]/prompt/[uuid]/`, `[index]/recordings/`, `[index]/store/` |

---

API/External Terms

### Claude API
| Attribute | Value |
|-----------|-------|
| What it is | Anthropic's language model API used for script generation |
| What it is not | Local inference; on-device processing |
| Layer | External Service |
| Integration | `AnthropicService` |

### ElevenLabs API
| Attribute | Value |
|-----------|-------|
| What it is | Text-to-speech API used for generating narration audio |
| What it is not | On-device TTS; AVSpeechSynthesizer |
| Layer | External Service |
| Integration | `TTSService` |

---

Concurrency Terms

### @MainActor
| Attribute | Value |
|-----------|-------|
| What it is | Swift annotation ensuring code runs on the main thread, required for UI state updates |
| What it is not | A thread; a queue; a lock |
| Layer | Runtime, Architectural |
| Usage | All ViewModels, AppState, UI-updating services |

### Sendable
| Attribute | Value |
|-----------|-------|
| What it is | Swift protocol marking types safe to pass across concurrency boundaries |
| What it is not | A thread-safety guarantee for mutable state |
| Layer | Architectural |
| Usage | Data models passed between actors |

---

Change Log

---

END OF DOCUMENT — SYSTEM GLOSSARY v1.0.0