# sohzm/cheating-daddy architecture

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

- Interactive diagram: https://gitdiagram.com/sohzm/cheating-daddy
- Repository: https://github.com/sohzm/cheating-daddy

## Overview

1. **What this repo is**
   - This is an **Electron desktop application** for real-time AI assistance during meetings/interviews.
   - There is **no backend server** in the repo; the app runs locally and talks to external AI APIs directly from the desktop app.

2. **Top-level runtime split**
   - The architecture is the standard Electron split:
     - **Main process**: app lifecycle, window creation, OS-level behavior, packaging.
     - **Preload layer**: safe bridge between Electron and the UI.
     - **Renderer/UI**: the user-facing assistant, settings, onboarding, and session screens.
   - The file layout strongly suggests `src/index.js` as the main entry, `src/preload.js` as the bridge, and `src/components/*` as the renderer app.

3. **Main-process responsibilities**
   - `src/utils/window.js` and `src/utils/windowResize.js` indicate the main process controls the desktop window: positioning, resizing, always-on-top behavior, and likely click-through toggling.
   - This is important because the app is not a normal page UI; it behaves like a **transparent overlay window** that can be moved and optionally made non-interactive.

4. **Renderer application structure**
   - `src/components/app/*` contains the top-level app shell, including `CheatingDaddyApp.js` and `AppHeader.js`.
   - `src/components/views/*` contains the feature screens:
     - `MainView` for the main session
     - `OnboardingView` for setup
     - `AssistantView` for live AI interaction
     - `CustomizeView` and `AICustomizeView` for profile/model tuning
     - `HistoryView`, `HelpView`, and `FeedbackView` for support and session history
   - `src/components/index.js` likely wires these views together into the renderer entry.

5. **Primary user flow**
   - The app flow appears to be:
     1. First-time setup/onboarding
     2. User enters API key and chooses a profile/language
     3. User starts a live session
     4. The assistant consumes screen/audio context and returns help in real time
   - The README’s shortcut-driven interaction and “transparent overlay” behavior imply the renderer is optimized for being present during other apps, not as a full-screen standalone workspace.

6. **AI integration layer**
   - `src/utils/gemini.js` is the core integration with **Google Gemini 2.0 Flash Live**.
   - `src/utils/cloud.js` and `src/utils/localai.js` suggest an abstraction over different model/runtime backends or transport modes, with cloud Gemini as the primary path and local AI as an alternate path.
   - `src/utils/prompts.js` centralizes prompt templates and session instructions, which likely vary by profile such as interview, sales, meeting, or presentation.

7. **Context gathering pipeline**
   - `src/audioUtils.js` plus the README’s audio notes show a dedicated audio-capture path.
   - Screen/audio context is the input to the AI layer: the assistant responds based on what is seen/heard rather than on a purely chat-driven conversation.
   - Platform-specific audio handling matters:
     - macOS uses the bundled `SystemAudioDump` asset
     - Windows uses loopback capture
     - Linux falls back to microphone input

8. **Persistence and local state**
   - `src/storage.js` is the local persistence boundary.
   - This likely stores user settings such as API key, selected profile, language, window preferences, and possibly history/session metadata.
   - The app appears to keep most state locally on the machine rather than in a remote account system.

9. **Cross-process communication boundary**
   - `src/preload.js` is the trust boundary between renderer and main process.
   - This is where the UI likely gets access to safe APIs for window control, storage, and maybe capture/session commands.
   - That boundary matters for the diagram because the renderer should be shown as isolated from direct Electron/OS access.

10. **Packaging and desktop distribution**
   - `forge.config.js` shows the project is packaged with **Electron Forge**.
   - `entitlements.plist` indicates macOS-specific signing/permissions support, which is relevant because the app needs screen/audio access and window control permissions.
   - `src/assets/*` contains icons and onboarding assets used in the packaged desktop app.

11. **Platform/OS dependencies**
   - This is a **desktop-native** product with OS permissions and platform-specific capture behavior.
   - The design depends on screen recording permissions, audio capture permissions, and always-on-top window support.
   - The README explicitly notes best support on the latest macOS and Windows, with Linux treated more as a testing path.

12. **Important architectural takeaway**
   - The core architecture is: **desktop overlay UI → preload bridge → main-process window/control + local storage → AI service adapter → Gemini/other model backend**, with **screen/audio context** feeding the AI response loop.
   - If you are drawing it, the main boundaries are:
     - renderer UI
     - preload bridge
     - Electron main/OS integration
     - capture utilities
     - AI provider layer
     - local persistence

Main entry points: [`src/components/views/MainView.js`](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/MainView.js) (Main view), [`src/index.js`](https://github.com/sohzm/cheating-daddy/blob/master/src/index.js) (App entry), [`src/utils/gemini.js`](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/gemini.js) (Gemini live), [`src/utils/window.js`](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/window.js) (Window control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_main["Main process"]
  node_node_index["App entry<br/>electron main<br/>[index.js]"]
  node_node_window["Window control<br/>overlay window<br/>[window.js]"]
  node_node_resize["Resize logic<br/>window sizing<br/>[windowResize.js]"]
  node_node_storage[("Local state<br/>persistence<br/>[storage.js]")]
  node_node_audio["Audio capture<br/>capture pipeline<br/>[audioUtils.js]"]
end

subgraph group_group_renderer["Renderer UI"]
  node_node_renderer_entry["Renderer entry<br/>ui bootstrap<br/>[index.js]"]
  node_node_app_shell["App shell<br/>react shell"]
  node_node_header["Header<br/>ui chrome<br/>[AppHeader.js]"]
  node_node_mainview["Main view<br/>session hub<br/>[MainView.js]"]
  node_node_onboarding["Onboarding<br/>setup flow<br/>[OnboardingView.js]"]
  node_node_assistant["Assistant<br/>live aid<br/>[AssistantView.js]"]
  node_node_customize["Customize<br/>settings view<br/>[CustomizeView.js]"]
  node_node_ai_customize["AI tuning<br/>settings view<br/>[AICustomizeView.js]"]
  node_node_history["History<br/>session log<br/>[HistoryView.js]"]
  node_node_help["Help<br/>support view<br/>[HelpView.js]"]
  node_node_feedback["Feedback<br/>support view<br/>[FeedbackView.js]"]
end

subgraph group_group_ai["AI layer"]
  node_node_ai["Gemini live<br/>AI provider<br/>[gemini.js]"]
  node_node_cloud["Cloud adapter<br/>provider adapter<br/>[cloud.js]"]
  node_node_localai["Local adapter<br/>provider adapter<br/>[localai.js]"]
  node_node_prompts["Prompt pack<br/>prompt templates<br/>[prompts.js]"]
end

subgraph group_group_assets["Packaged assets"]
  node_node_assets["Assets<br/>packaged media"]
end

node_node_preload["Bridge<br/>preload api<br/>[preload.js]"]

node_node_index -->|"creates"| node_node_window
node_node_index -->|"loads"| node_node_preload
node_node_index -->|"uses"| node_node_storage
node_node_index -->|"coordinates"| node_node_audio
node_node_window -->|"delegates"| node_node_resize
node_node_window -->|"hosts"| node_node_renderer_entry
node_node_preload -->|"exposes api"| node_node_renderer_entry
node_node_renderer_entry -->|"mounts"| node_node_app_shell
node_node_app_shell -->|"includes"| node_node_header
node_node_app_shell -->|"routes"| node_node_mainview
node_node_mainview -->|"first run"| node_node_onboarding
node_node_mainview -->|"session"| node_node_assistant
node_node_mainview -->|"settings"| node_node_customize
node_node_customize -->|"refines"| node_node_ai_customize
node_node_mainview -->|"reviews"| node_node_history
node_node_mainview -->|"supports"| node_node_help
node_node_mainview -->|"reports"| node_node_feedback
node_node_assistant -->|"consumes"| node_node_audio
node_node_assistant -->|"queries"| node_node_ai
node_node_ai -->|"primary path"| node_node_cloud
node_node_ai -->|"fallback"| node_node_localai
node_node_ai -->|"uses"| node_node_prompts
node_node_storage -->|"persists"| node_node_customize
node_node_storage -->|"saves"| node_node_onboarding
node_node_assets -->|"feeds"| node_node_onboarding

click node_node_index "https://github.com/sohzm/cheating-daddy/blob/master/src/index.js"
click node_node_window "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/window.js"
click node_node_resize "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/windowResize.js"
click node_node_storage "https://github.com/sohzm/cheating-daddy/blob/master/src/storage.js"
click node_node_audio "https://github.com/sohzm/cheating-daddy/blob/master/src/audioUtils.js"
click node_node_preload "https://github.com/sohzm/cheating-daddy/blob/master/src/preload.js"
click node_node_renderer_entry "https://github.com/sohzm/cheating-daddy/blob/master/src/components/index.js"
click node_node_app_shell "https://github.com/sohzm/cheating-daddy/blob/master/src/components/app/CheatingDaddyApp.js"
click node_node_header "https://github.com/sohzm/cheating-daddy/blob/master/src/components/app/AppHeader.js"
click node_node_mainview "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/MainView.js"
click node_node_onboarding "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/OnboardingView.js"
click node_node_assistant "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/AssistantView.js"
click node_node_customize "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/CustomizeView.js"
click node_node_ai_customize "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/AICustomizeView.js"
click node_node_history "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/HistoryView.js"
click node_node_help "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/HelpView.js"
click node_node_feedback "https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/FeedbackView.js"
click node_node_ai "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/gemini.js"
click node_node_cloud "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/cloud.js"
click node_node_localai "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/localai.js"
click node_node_prompts "https://github.com/sohzm/cheating-daddy/blob/master/src/utils/prompts.js"
click node_node_assets "https://github.com/sohzm/cheating-daddy/tree/master/src/assets"

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_node_index,node_node_window,node_node_resize,node_node_storage,node_node_audio toneBlue
class node_node_renderer_entry,node_node_app_shell,node_node_header,node_node_mainview,node_node_onboarding,node_node_assistant,node_node_customize,node_node_ai_customize,node_node_history,node_node_help,node_node_feedback toneAmber
class node_node_ai,node_node_cloud,node_node_localai,node_node_prompts toneMint
class node_node_assets toneRose
class node_node_preload toneNeutral
```

## Components

### Main process

Electron lifecycle, windowing, capture coordination, and local persistence

- [App entry](https://github.com/sohzm/cheating-daddy/blob/master/src/index.js): electron main · Starts Electron and wires the desktop runtime · `src/index.js`
- [Window control](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/window.js): overlay window · Creates and manages the transparent always-on-top app window · `src/utils/window.js`
- [Resize logic](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/windowResize.js): window sizing · Handles window positioning, sizing, and interaction mode changes · `src/utils/windowResize.js`
- [Local state](https://github.com/sohzm/cheating-daddy/blob/master/src/storage.js): persistence · Stores settings, profile choices, and other machine-local state · `src/storage.js`
- [Audio capture](https://github.com/sohzm/cheating-daddy/blob/master/src/audioUtils.js): capture pipeline · Platform-specific audio input and loopback capture helpers · `src/audioUtils.js`

### Renderer UI

Desktop app shell and user-facing views

- [Renderer entry](https://github.com/sohzm/cheating-daddy/blob/master/src/components/index.js): ui bootstrap · Bootstraps the renderer application · `src/components/index.js`
- [App shell](https://github.com/sohzm/cheating-daddy/blob/master/src/components/app/CheatingDaddyApp.js): react shell · Top-level assistant layout and navigation frame · `src/components/app/CheatingDaddyApp.js`
- [Header](https://github.com/sohzm/cheating-daddy/blob/master/src/components/app/AppHeader.js): ui chrome · App-level controls and status header · `src/components/app/AppHeader.js`
- [Main view](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/MainView.js): session hub · Primary screen that routes between onboarding, sessions, and settings · `src/components/views/MainView.js`
- [Onboarding](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/OnboardingView.js): setup flow · First-run setup for keys, profile, and language choices · `src/components/views/OnboardingView.js`
- [Assistant](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/AssistantView.js): live aid · Real-time assistance interface during active sessions · `src/components/views/AssistantView.js`
- [Customize](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/CustomizeView.js): settings view · General preference and profile tuning screen · `src/components/views/CustomizeView.js`
- [AI tuning](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/AICustomizeView.js): settings view · Assistant and model-specific configuration screen · `src/components/views/AICustomizeView.js`
- [History](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/HistoryView.js): session log · Past sessions and saved activity review · `src/components/views/HistoryView.js`
- [Help](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/HelpView.js): support view · Usage guidance and troubleshooting · `src/components/views/HelpView.js`
- [Feedback](https://github.com/sohzm/cheating-daddy/blob/master/src/components/views/FeedbackView.js): support view · User feedback and issue reporting · `src/components/views/FeedbackView.js`

### AI layer

Provider adapters, prompts, and live assistant logic

- [Gemini live](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/gemini.js): AI provider · Primary live AI integration used during sessions · `src/utils/gemini.js`
- [Cloud adapter](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/cloud.js): provider adapter · Cloud-side transport and provider abstraction · `src/utils/cloud.js`
- [Local adapter](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/localai.js): provider adapter · Alternate local runtime or model backend · `src/utils/localai.js`
- [Prompt pack](https://github.com/sohzm/cheating-daddy/blob/master/src/utils/prompts.js): prompt templates · System prompts and role-specific session instructions · `src/utils/prompts.js`

### Packaged assets

Bundled icons and onboarding media

- [Assets](https://github.com/sohzm/cheating-daddy/tree/master/src/assets): packaged media · Icons and onboarding media bundled with the desktop app · `src/assets`

### Other components

- [Bridge](https://github.com/sohzm/cheating-daddy/blob/master/src/preload.js): preload api · Trusted IPC boundary that exposes safe app controls to the UI · `src/preload.js`

## Connections

- App entry → Window control: creates · Main process initializes the overlay window
- App entry → Bridge: loads · Main process attaches the preload bridge
- App entry → Local state: uses · Main process reads and writes local app state
- App entry → Audio capture: coordinates · Main process coordinates platform capture helpers
- Window control → Resize logic: delegates · Window behavior delegates sizing and positioning logic
- Window control → Renderer entry: hosts · Desktop window displays the renderer app
- Bridge → Renderer entry: exposes api · Renderer reaches main-process capabilities through the bridge
- Renderer entry → App shell: mounts · Renderer boots into the app shell
- App shell → Header: includes · Shell renders shared chrome and controls
- App shell → Main view: routes · Shell routes into the main working area
- Main view → Onboarding: first run · Initial setup path leads to onboarding
- Main view → Assistant: session · Primary live-assistance workspace
- Main view → Customize: settings · Main flow opens general customization
- Customize → AI tuning: refines · General settings flow into AI-specific tuning
- Main view → History: reviews · Users can inspect previous sessions
- Main view → Help: supports · Main flow includes help and troubleshooting
- Main view → Feedback: reports · Main flow includes feedback capture
- Assistant → Audio capture: consumes · Live assistant uses captured audio context
- Assistant → Gemini live: queries · Assistant sends context to the AI layer
- Gemini live → Cloud adapter: primary path · Gemini live uses the cloud provider path
- Gemini live → Local adapter: fallback · Local model adapter is an alternate backend
- Gemini live → Prompt pack: uses · Assistant behavior is shaped by prompt templates
- Local state → Customize: persists · Preferences and profile choices are stored locally
- Local state → Onboarding: saves · Onboarding selections are written to local state
- Assets → Onboarding: feeds · Onboarding uses bundled assets and media
