# rbrown101010/bluey-by-riley architecture

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

- Interactive diagram: https://gitdiagram.com/rbrown101010/bluey-by-riley
- Repository: https://github.com/rbrown101010/bluey-by-riley

## Overview

Googly Eyes is a paired iPhone and Mac assistant: the user wakes it and holds the phone to ask; the phone streams microphone audio to OpenAI Realtime, while the Mac supplies short-lived credentials and executes screen, cursor, and computer-control tools. Replies appear as Mac cursor bubbles, with a phone chirp and saved transcript. The graph also preserves web research, pairing, settings, and session history. Edges follow README-documented behavior or source-index references; several unsampled implementations are represented only at their known paths.

Main entry points: [`Mac/Sources/GooglyMac/RealtimeHost.swift`](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/RealtimeHost.swift) (Tool host), [`iOS/Sources/GooglyApp.swift`](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/GooglyApp.swift) (App shell), [`Mac/Sources/GooglyMac/AppDelegate.swift`](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/AppDelegate.swift) (Menu bar app), [`iOS/Sources/BlueyAppView.swift`](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/BlueyAppView.swift) (Character and controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["iPhone experience"]
  node_ios_app["App shell<br/>[GooglyApp.swift]"]
  node_phone_ui["Character and controls<br/>[BlueyAppView.swift]"]
  node_face["Character face<br/>[FaceView.swift]"]
  node_voice["Voice session<br/>[LiveVoice.swift]"]
  node_pairing["Mac pairing<br/>[MacLink.swift]"]
  node_pair_ui["Pairing controls<br/>[PairingView.swift]"]
  node_history[("Session history<br/>[SessionStore.swift]")]
  node_chirp["Chirp controls<br/>[SoundButton.swift]"]
end

subgraph group_mac["Mac assistant"]
  node_mac_app["Menu bar app<br/>[AppDelegate.swift]"]
  node_phone_server["Phone server<br/>[PhoneServer.swift]"]
  node_realtime["Tool host<br/>[RealtimeHost.swift]"]
  node_overlay["Cursor and bubbles"]
  node_settings[("Preferences<br/>[Settings.swift]")]
  node_keys[("API key storage<br/>[Keychain.swift]")]
end

subgraph group_tools["Mac capabilities"]
  node_screen["Screen understanding<br/>[ScreenReader.swift]"]
  node_controls["Accessible controls"]
  node_computer["Computer actions"]
  node_research["Web research<br/>[WebResearch.swift]"]
  node_reports["Research reports<br/>[ReportPanel.swift]"]
end

subgraph group_shared["Shared protocol and design"]
  node_protocol["Pairing protocol<br/>[GooglyLink.swift]"]
  node_palette["Color palette<br/>[Palette.swift]"]
end

node_user(("User"))
node_openai_rt{{"OpenAI Realtime"}}
node_openai_resp{{"OpenAI Responses"}}
node_web{{"Web search"}}

node_user -->|"uses"| node_ios_app
node_ios_app -->|"presents"| node_phone_ui
node_ios_app -->|"shows"| node_face
node_phone_ui -->|"starts and asks"| node_voice
node_phone_ui -->|"shows sessions"| node_history
node_phone_ui -->|"uses"| node_pairing
node_ios_app -->|"presents"| node_pair_ui
node_ios_app -->|"uses"| node_history
node_ios_app -->|"presents"| node_chirp
node_pair_ui -->|"selects Mac"| node_pairing
node_voice -->|"streams audio"| node_openai_rt
node_voice -->|"requests token and tools"| node_pairing
node_voice -.->|"records turns"| node_history
node_pairing -->|"connects over Bonjour"| node_phone_server
node_phone_server -->|"exchanges packets"| node_protocol
node_mac_app -->|"starts server"| node_phone_server
node_mac_app -->|"controls sessions"| node_realtime
node_mac_app -->|"controls cursor"| node_overlay
node_mac_app -->|"updates preferences"| node_settings
node_realtime -->|"mints phone token"| node_phone_server
node_realtime -->|"creates client secret"| node_openai_rt
node_realtime -->|"runs screen tools"| node_screen
node_realtime -->|"runs action tools"| node_computer
node_realtime -->|"uses controls"| node_controls
node_realtime -->|"shows replies and pointing"| node_overlay
node_realtime -->|"invokes research"| node_research
node_realtime -->|"presents reports"| node_reports
node_realtime -->|"reads API key"| node_keys
node_research -->|"submits research"| node_openai_resp
node_openai_resp -->|"searches"| node_web
node_mac_app -->|"saves API key"| node_keys
node_screen -->|"reads controls"| node_controls
node_overlay -->|"reads display options"| node_settings
node_phone_ui -->|"uses colors"| node_palette
node_face -->|"uses colors"| node_palette
node_overlay -->|"uses colors"| node_palette

click node_ios_app "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/GooglyApp.swift"
click node_phone_ui "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/BlueyAppView.swift"
click node_face "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/FaceView.swift"
click node_voice "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/LiveVoice.swift"
click node_pairing "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/MacLink.swift"
click node_pair_ui "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/PairingView.swift"
click node_history "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/SessionStore.swift"
click node_chirp "https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/SoundButton.swift"
click node_mac_app "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/AppDelegate.swift"
click node_phone_server "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/PhoneServer.swift"
click node_realtime "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/RealtimeHost.swift"
click node_overlay "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/CursorOverlay.swift"
click node_settings "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/Settings.swift"
click node_keys "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/Keychain.swift"
click node_screen "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ScreenReader.swift"
click node_controls "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ControlsReader.swift"
click node_computer "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ComputerControl.swift"
click node_research "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/WebResearch.swift"
click node_reports "https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ReportPanel.swift"
click node_protocol "https://github.com/rbrown101010/bluey-by-riley/blob/main/Shared/GooglyLink.swift"
click node_palette "https://github.com/rbrown101010/bluey-by-riley/blob/main/Shared/Palette.swift"

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_ios_app,node_phone_ui,node_face,node_voice,node_pairing,node_pair_ui,node_history,node_chirp,node_user toneBlue
class node_mac_app,node_phone_server,node_realtime,node_overlay,node_settings,node_keys toneAmber
class node_screen,node_controls,node_computer,node_research,node_reports toneMint
class node_protocol,node_palette toneRose
class node_openai_rt,node_openai_resp,node_web toneIndigo
```

## Components

### iPhone experience

- [App shell](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/GooglyApp.swift): `iOS/Sources/GooglyApp.swift`
- [Character and controls](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/BlueyAppView.swift): `iOS/Sources/BlueyAppView.swift`
- [Character face](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/FaceView.swift): `iOS/Sources/FaceView.swift`
- [Voice session](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/LiveVoice.swift): `iOS/Sources/LiveVoice.swift`
- [Mac pairing](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/MacLink.swift): `iOS/Sources/MacLink.swift`
- [Pairing controls](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/PairingView.swift): `iOS/Sources/PairingView.swift`
- [Session history](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/SessionStore.swift): `iOS/Sources/SessionStore.swift`
- [Chirp controls](https://github.com/rbrown101010/bluey-by-riley/blob/main/iOS/Sources/SoundButton.swift): `iOS/Sources/SoundButton.swift`

### Mac assistant

- [Menu bar app](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/AppDelegate.swift): `Mac/Sources/GooglyMac/AppDelegate.swift`
- [Phone server](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/PhoneServer.swift): `Mac/Sources/GooglyMac/PhoneServer.swift`
- [Tool host](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/RealtimeHost.swift): `Mac/Sources/GooglyMac/RealtimeHost.swift`
- [Cursor and bubbles](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/CursorOverlay.swift): `Mac/Sources/GooglyMac/CursorOverlay.swift`
- [Preferences](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/Settings.swift): `Mac/Sources/GooglyMac/Settings.swift`
- [API key storage](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/Keychain.swift): `Mac/Sources/GooglyMac/Keychain.swift`

### Mac capabilities

- [Screen understanding](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ScreenReader.swift): `Mac/Sources/GooglyMac/ScreenReader.swift`
- [Accessible controls](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ControlsReader.swift): `Mac/Sources/GooglyMac/ControlsReader.swift`
- [Computer actions](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ComputerControl.swift): `Mac/Sources/GooglyMac/ComputerControl.swift`
- [Web research](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/WebResearch.swift): `Mac/Sources/GooglyMac/WebResearch.swift`
- [Research reports](https://github.com/rbrown101010/bluey-by-riley/blob/main/Mac/Sources/GooglyMac/ReportPanel.swift): `Mac/Sources/GooglyMac/ReportPanel.swift`

### Shared protocol and design

- [Pairing protocol](https://github.com/rbrown101010/bluey-by-riley/blob/main/Shared/GooglyLink.swift): `Shared/GooglyLink.swift`
- [Color palette](https://github.com/rbrown101010/bluey-by-riley/blob/main/Shared/Palette.swift): `Shared/Palette.swift`

### Other components

- **User**
- **OpenAI Realtime**
- **OpenAI Responses**
- **Web search**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Character and controls: presents (evidence: `iOS/Sources/GooglyApp.swift`)
- App shell → Character face: shows (evidence: `iOS/Sources/GooglyApp.swift`)
- Character and controls → Voice session: starts and asks (evidence: `iOS/Sources/BlueyAppView.swift`)
- Character and controls → Session history: shows sessions (evidence: `iOS/Sources/BlueyAppView.swift`)
- Character and controls → Mac pairing: uses (evidence: `iOS/Sources/BlueyAppView.swift`)
- App shell → Pairing controls: presents (evidence: `iOS/Sources/GooglyApp.swift`)
- App shell → Session history: uses (evidence: `iOS/Sources/GooglyApp.swift`)
- App shell → Chirp controls: presents (evidence: `iOS/Sources/GooglyApp.swift`)
- Pairing controls → Mac pairing: selects Mac (evidence: `iOS/Sources/PairingView.swift`)
- Voice session → OpenAI Realtime: streams audio (evidence: `README.md`)
- Voice session → Mac pairing: requests token and tools (evidence: `iOS/Sources/LiveVoice.swift`)
- Voice session → Session history: records turns
- Mac pairing → Phone server: connects over Bonjour (evidence: `README.md`)
- Phone server → Pairing protocol: exchanges packets (evidence: `README.md`)
- Menu bar app → Phone server: starts server (evidence: `Mac/Sources/GooglyMac/AppDelegate.swift`)
- Menu bar app → Tool host: controls sessions (evidence: `Mac/Sources/GooglyMac/AppDelegate.swift`)
- Menu bar app → Cursor and bubbles: controls cursor (evidence: `Mac/Sources/GooglyMac/AppDelegate.swift`)
- Menu bar app → Preferences: updates preferences (evidence: `Mac/Sources/GooglyMac/AppDelegate.swift`)
- Tool host → Phone server: mints phone token (evidence: `README.md`)
- Tool host → OpenAI Realtime: creates client secret (evidence: `README.md`)
- Tool host → Screen understanding: runs screen tools (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Tool host → Computer actions: runs action tools (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Tool host → Accessible controls: uses controls (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Tool host → Cursor and bubbles: shows replies and pointing (evidence: `README.md`)
- Tool host → Web research: invokes research (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Tool host → Research reports: presents reports (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Tool host → API key storage: reads API key (evidence: `Mac/Sources/GooglyMac/RealtimeHost.swift`)
- Web research → OpenAI Responses: submits research (evidence: `Mac/Sources/GooglyMac/WebResearch.swift`)
- OpenAI Responses → Web search: searches
- Menu bar app → API key storage: saves API key (evidence: `Mac/Sources/GooglyMac/AppDelegate.swift`)
- Screen understanding → Accessible controls: reads controls (evidence: `Mac/Sources/GooglyMac/ScreenReader.swift`)
- Cursor and bubbles → Preferences: reads display options (evidence: `Mac/Sources/GooglyMac/CursorOverlay.swift`)
- Character and controls → Color palette: uses colors (evidence: `iOS/Sources/BlueyAppView.swift`)
- Character face → Color palette: uses colors (evidence: `iOS/Sources/FaceView.swift`)
- Cursor and bubbles → Color palette: uses colors (evidence: `Mac/Sources/GooglyMac/CursorOverlay.swift`)
