# yoyongler/bedtime-ai architecture

> Architecture diagram of the GitHub repository yoyongler/bedtime-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yoyongler/bedtime-ai
- Repository: https://github.com/yoyongler/bedtime-ai

## Overview

Bedtime Unwind is a React relaxation app whose main workflow is choosing a breathing exercise, following its timed visual phases with optional sound, and reaching a completion screen. Its alternate Unload & Breathe flow accepts typed or dictated thoughts, generates reassurance through Gemini when configured (otherwise using a fallback), then transitions into breathing. The app also includes API-key configuration and volume controls. The graph follows documented screen flows and sampled calls; unsampled relationships are omitted rather than inferred.

Main entry points: [`src/App.tsx`](https://github.com/yoyongler/bedtime-ai/blob/main/src/App.tsx) (Screen flow), [`src/components/MindDumpScreen.tsx`](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/MindDumpScreen.tsx) (Thought and reassurance), [`src/components/HomeScreen.tsx`](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/HomeScreen.tsx) (Exercise selection), [`src/components/ExerciseScreen.tsx`](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/ExerciseScreen.tsx) (Breathing session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Relaxation experience"]
  node_app["Screen flow<br/>[App.tsx]"]
  node_home["Exercise selection<br/>[HomeScreen.tsx]"]
  node_exercise_data["Exercise definitions<br/>[exercises.ts]"]
  node_exercise["Breathing session<br/>[ExerciseScreen.tsx]"]
  node_completion["Completion screen"]
end

subgraph group_minddump["Mind-dump and speech"]
  node_mind_screen["Thought and reassurance<br/>[MindDumpScreen.tsx]"]
  node_speech_hook["Dictation lifecycle<br/>[useSpeechToText.ts]"]
  node_speech_wrapper["Speech API wrapper"]
end

subgraph group_audio["Sound and controls"]
  node_sound_engine["Audio synthesizer<br/>[audio.ts]"]
  node_volume["Volume controls<br/>[VolumeControl.tsx]"]
end

subgraph group_integration["External integrations"]
  node_gemini_service["Reassurance service<br/>[gemini.ts]"]
  node_key_modal["API key settings<br/>[ApiKeyModal.tsx]"]
end

node_user(("Sleeptime user"))
node_browser_speech{{"Browser speech service"}}
node_gemini{{"Google Gemini"}}
node_local_storage[("Browser localStorage")]

node_user -->|"uses"| node_app
node_app -->|"shows selection"| node_home
node_home -->|"selects exercise"| node_app
node_app -->|"loads config"| node_exercise_data
node_app -->|"shows session"| node_exercise
node_exercise -->|"signals completion"| node_app
node_app -->|"shows result"| node_completion
node_home -->|"selects mind dump"| node_mind_screen
node_app -->|"shows thought flow"| node_mind_screen
node_mind_screen -->|"proceeds to breathing"| node_app
node_mind_screen -->|"uses dictation"| node_speech_hook
node_speech_hook -->|"uses recognition helpers"| node_speech_wrapper
node_speech_wrapper -->|"detects and controls"| node_browser_speech
node_mind_screen -->|"requests reassurance"| node_gemini_service
node_gemini_service -->|"generates reassurance"| node_gemini
node_gemini_service -->|"reads saved key"| node_local_storage
node_key_modal -->|"saves key"| node_local_storage
node_app -->|"shows settings"| node_key_modal
node_app -->|"starts and stops ambience"| node_sound_engine
node_exercise -->|"plays phase cues"| node_sound_engine
node_home -->|"renders controls"| node_volume
node_app -->|"toggles mute"| node_sound_engine

click node_app "https://github.com/yoyongler/bedtime-ai/blob/main/src/App.tsx"
click node_home "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/HomeScreen.tsx"
click node_exercise_data "https://github.com/yoyongler/bedtime-ai/blob/main/src/constants/exercises.ts"
click node_exercise "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/ExerciseScreen.tsx"
click node_completion "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/CompletionScreen.tsx"
click node_mind_screen "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/MindDumpScreen.tsx"
click node_speech_hook "https://github.com/yoyongler/bedtime-ai/blob/main/src/hooks/useSpeechToText.ts"
click node_speech_wrapper "https://github.com/yoyongler/bedtime-ai/blob/main/src/utils/speechRecognition.ts"
click node_gemini_service "https://github.com/yoyongler/bedtime-ai/blob/main/src/services/gemini.ts"
click node_key_modal "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/ApiKeyModal.tsx"
click node_sound_engine "https://github.com/yoyongler/bedtime-ai/blob/main/src/utils/audio.ts"
click node_volume "https://github.com/yoyongler/bedtime-ai/blob/main/src/components/VolumeControl.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_home,node_exercise_data,node_exercise,node_completion,node_user,node_browser_speech toneBlue
class node_mind_screen,node_speech_hook,node_speech_wrapper,node_local_storage toneAmber
class node_sound_engine,node_volume toneMint
class node_gemini_service,node_key_modal toneRose
class node_gemini toneIndigo
```

## Components

### Relaxation experience

- [Screen flow](https://github.com/yoyongler/bedtime-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Exercise selection](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/HomeScreen.tsx): `src/components/HomeScreen.tsx`
- [Exercise definitions](https://github.com/yoyongler/bedtime-ai/blob/main/src/constants/exercises.ts): `src/constants/exercises.ts`
- [Breathing session](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/ExerciseScreen.tsx): `src/components/ExerciseScreen.tsx`
- [Completion screen](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/CompletionScreen.tsx): `src/components/CompletionScreen.tsx`

### Mind-dump and speech

- [Thought and reassurance](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/MindDumpScreen.tsx): `src/components/MindDumpScreen.tsx`
- [Dictation lifecycle](https://github.com/yoyongler/bedtime-ai/blob/main/src/hooks/useSpeechToText.ts): `src/hooks/useSpeechToText.ts`
- [Speech API wrapper](https://github.com/yoyongler/bedtime-ai/blob/main/src/utils/speechRecognition.ts): `src/utils/speechRecognition.ts`

### Sound and controls

- [Audio synthesizer](https://github.com/yoyongler/bedtime-ai/blob/main/src/utils/audio.ts): `src/utils/audio.ts`
- [Volume controls](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/VolumeControl.tsx): `src/components/VolumeControl.tsx`

### External integrations

- [Reassurance service](https://github.com/yoyongler/bedtime-ai/blob/main/src/services/gemini.ts): `src/services/gemini.ts`
- [API key settings](https://github.com/yoyongler/bedtime-ai/blob/main/src/components/ApiKeyModal.tsx): `src/components/ApiKeyModal.tsx`

### Other components

- **Sleeptime user**
- **Browser speech service**
- **Google Gemini**
- **Browser localStorage**

## Connections

- Sleeptime user → Screen flow: uses (evidence: `README.md`)
- Screen flow → Exercise selection: shows selection (evidence: `README.md`)
- Exercise selection → Screen flow: selects exercise (evidence: `README.md`)
- Screen flow → Exercise definitions: loads config (evidence: `src/App.tsx`)
- Screen flow → Breathing session: shows session (evidence: `src/App.tsx`)
- Breathing session → Screen flow: signals completion (evidence: `README.md`)
- Screen flow → Completion screen: shows result (evidence: `src/App.tsx`)
- Exercise selection → Thought and reassurance: selects mind dump (evidence: `README.md`)
- Screen flow → Thought and reassurance: shows thought flow (evidence: `src/App.tsx`)
- Thought and reassurance → Screen flow: proceeds to breathing (evidence: `src/App.tsx`)
- Thought and reassurance → Dictation lifecycle: uses dictation (evidence: `src/components/MindDumpScreen.tsx`)
- Dictation lifecycle → Speech API wrapper: uses recognition helpers (evidence: `src/hooks/useSpeechToText.ts`)
- Speech API wrapper → Browser speech service: detects and controls (evidence: `src/utils/speechRecognition.ts`)
- Thought and reassurance → Reassurance service: requests reassurance (evidence: `src/components/MindDumpScreen.tsx`)
- Reassurance service → Google Gemini: generates reassurance (evidence: `src/services/gemini.ts`)
- Reassurance service → Browser localStorage: reads saved key (evidence: `README.md`)
- API key settings → Browser localStorage: saves key (evidence: `README.md`)
- Screen flow → API key settings: shows settings (evidence: `src/App.tsx`)
- Screen flow → Audio synthesizer: starts and stops ambience (evidence: `src/App.tsx`)
- Breathing session → Audio synthesizer: plays phase cues (evidence: `src/components/ExerciseScreen.tsx`)
- Exercise selection → Volume controls: renders controls (evidence: `src/components/HomeScreen.tsx`)
- Screen flow → Audio synthesizer: toggles mute (evidence: `src/App.tsx`)