# the4n6analyst/coucou architecture

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

- Interactive diagram: https://gitdiagram.com/the4n6analyst/coucou
- Repository: https://github.com/the4n6analyst/coucou

## Overview

Coucou is a cross-platform agent-session companion: desktop agents surface activity and requests in a Mochi island, users inspect or respond, and paired phone apps can receive session updates and approvals. The macOS app also adds Flow dictation and call notes, while desktop variants expose chat and integrations. The tree and README establish these major capabilities, but excerpts show only selected implementation links; dashed edges mark important documented or unverified relationships, and unsampled subsystems are represented at supported directory paths.

Main entry points: [`windows/src/main.ts`](https://github.com/the4n6analyst/coucou/blob/main/windows/src/main.ts) (Windows Linux App), [`NotchBuddy/Sources/App/AppState.swift`](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/AppState.swift) (App State), [`NotchBuddy/Sources/App/HookServer.swift`](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/HookServer.swift) (Agent Hooks), [`windows/src-tauri/src/phone_link/server.rs`](https://github.com/the4n6analyst/coucou/blob/main/windows/src-tauri/src/phone_link/server.rs) (Phone Link Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Companion"]
  node_mac["macOS App"]
  node_winapp["Windows Linux App<br/>[main.ts]"]
  node_appstate["App State<br/>[AppState.swift]"]
  node_settings["Settings<br/>[main.ts]"]
  node_island["Island UI<br/>[island.ts]"]
  node_bridge["Desktop Bridge<br/>[bridge.ts]"]
  node_winstate["UI State<br/>[state.ts]"]
  node_whatsnew["Release Recap<br/>[controller.ts]"]
end

subgraph group_agent["Agent Sessions"]
  node_hook["Agent Hooks<br/>[HookServer.swift]"]
  node_winhook["Windows Hooks<br/>[main.rs]"]
  node_approval["Approvals Questions"]
  node_chat["Agent Chat<br/>[LocalChat.swift]"]
end

subgraph group_voice["Voice and Notes"]
  node_dictation["Flow Dictation"]
  node_parakeet["Offline Speech"]
  node_voiceengine["Voice Assistant<br/>[VoiceEngine.swift]"]
  node_notes["Call Notes<br/>[NoteTaker.swift]"]
end

subgraph group_phone["Phone Link"]
  node_phoneapp["Phone Apps"]
  node_phonelink["Phone Link Server<br/>[server.rs]"]
  node_phonehub["Phone Link Hub<br/>[hub.rs]"]
  node_androidlink["Android Link Client<br/>[LinkClient.kt]"]
  node_relay["Relay Service<br/>[index.ts]"]
end

subgraph group_platform["Shared UI"]
  node_mochi["Mochi Engine<br/>[BotEngine.swift]"]
  node_catalog["Pill Catalog<br/>[PillCatalog.swift]"]
  node_sound["Sound Engine<br/>[SoundEngine.swift]"]
end

node_user(("User"))

node_user -->|"uses"| node_mac
node_user -->|"uses"| node_winapp
node_user -->|"uses"| node_phoneapp
node_mac -.->|"coordinates"| node_appstate
node_winapp -->|"invokes"| node_bridge
node_winapp -->|"renders"| node_island
node_winapp -->|"updates"| node_winstate
node_settings -->|"configures"| node_bridge
node_appstate -.->|"starts"| node_hook
node_hook -.->|"routes requests"| node_approval
node_hook -.->|"surfaces events"| node_island
node_winhook -.->|"reports events"| node_winapp
node_appstate -->|"selects provider"| node_chat
node_island -.->|"renders"| node_mochi
node_winstate -->|"drives state"| node_mochi
node_catalog -->|"defines pills"| node_appstate
node_dictation -.->|"transcribes offline"| node_parakeet
node_voiceengine -.->|"supports capture"| node_dictation
node_notes -.->|"returns transcript"| node_user
node_phonelink -->|"dispatches messages"| node_phonehub
node_phonehub -.->|"sends updates"| node_phoneapp
node_androidlink -.->|"connects"| node_phonelink
node_phonelink -.->|"uses relay"| node_relay
node_mochi -->|"plays effects"| node_sound
node_whatsnew -->|"loads recap"| node_bridge

click node_mac "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/NotchBuddyApp.swift"
click node_winapp "https://github.com/the4n6analyst/coucou/blob/main/windows/src/main.ts"
click node_appstate "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/AppState.swift"
click node_settings "https://github.com/the4n6analyst/coucou/blob/main/windows/src/settings/main.ts"
click node_island "https://github.com/the4n6analyst/coucou/blob/main/windows/src/island/island.ts"
click node_mochi "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/CoucouKit/BotEngine.swift"
click node_catalog "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/CoucouKit/PillCatalog.swift"
click node_hook "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/HookServer.swift"
click node_winhook "https://github.com/the4n6analyst/coucou/blob/main/windows/hook/src/main.rs"
click node_approval "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/ApprovalQueue.swift"
click node_chat "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/LocalChat.swift"
click node_dictation "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/FlowDictation.swift"
click node_parakeet "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/ParakeetEngine.swift"
click node_voiceengine "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/Voice/VoiceEngine.swift"
click node_notes "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/NoteTaker.swift"
click node_phoneapp "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/Phone/CoucouPhoneApp.swift"
click node_phonelink "https://github.com/the4n6analyst/coucou/blob/main/windows/src-tauri/src/phone_link/server.rs"
click node_phonehub "https://github.com/the4n6analyst/coucou/blob/main/windows/src-tauri/src/phone_link/hub.rs"
click node_androidlink "https://github.com/the4n6analyst/coucou/blob/main/android/app/src/main/kotlin/com/coucou/android/link/LinkClient.kt"
click node_relay "https://github.com/the4n6analyst/coucou/blob/main/relay/src/index.ts"
click node_bridge "https://github.com/the4n6analyst/coucou/blob/main/windows/src/core/bridge.ts"
click node_winstate "https://github.com/the4n6analyst/coucou/blob/main/windows/src/core/state.ts"
click node_sound "https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/SoundEngine.swift"
click node_whatsnew "https://github.com/the4n6analyst/coucou/blob/main/windows/src/whats-new/controller.ts"

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_mac,node_winapp,node_appstate,node_settings,node_island,node_bridge,node_winstate,node_whatsnew,node_user toneBlue
class node_hook,node_winhook,node_approval,node_chat toneAmber
class node_dictation,node_parakeet,node_voiceengine,node_notes toneMint
class node_phoneapp,node_phonelink,node_phonehub,node_androidlink,node_relay toneRose
class node_mochi,node_catalog,node_sound toneIndigo
```

## Components

### Desktop Companion

- [macOS App](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/NotchBuddyApp.swift): `NotchBuddy/Sources/App/NotchBuddyApp.swift`
- [Windows Linux App](https://github.com/the4n6analyst/coucou/blob/main/windows/src/main.ts): `windows/src/main.ts`
- [App State](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/AppState.swift): `NotchBuddy/Sources/App/AppState.swift`
- [Settings](https://github.com/the4n6analyst/coucou/blob/main/windows/src/settings/main.ts): `windows/src/settings/main.ts`
- [Island UI](https://github.com/the4n6analyst/coucou/blob/main/windows/src/island/island.ts): `windows/src/island/island.ts`
- [Desktop Bridge](https://github.com/the4n6analyst/coucou/blob/main/windows/src/core/bridge.ts): `windows/src/core/bridge.ts`
- [UI State](https://github.com/the4n6analyst/coucou/blob/main/windows/src/core/state.ts): `windows/src/core/state.ts`
- [Release Recap](https://github.com/the4n6analyst/coucou/blob/main/windows/src/whats-new/controller.ts): `windows/src/whats-new/controller.ts`

### Agent Sessions

- [Agent Hooks](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/HookServer.swift): `NotchBuddy/Sources/App/HookServer.swift`
- [Windows Hooks](https://github.com/the4n6analyst/coucou/blob/main/windows/hook/src/main.rs): `windows/hook/src/main.rs`
- [Approvals Questions](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/ApprovalQueue.swift): `NotchBuddy/Sources/App/ApprovalQueue.swift`
- [Agent Chat](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/LocalChat.swift): `NotchBuddy/Sources/App/LocalChat.swift`

### Voice and Notes

- [Flow Dictation](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/FlowDictation.swift): `NotchBuddy/Sources/App/FlowDictation.swift`
- [Offline Speech](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/ParakeetEngine.swift): `NotchBuddy/Sources/App/ParakeetEngine.swift`
- [Voice Assistant](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/Voice/VoiceEngine.swift): `NotchBuddy/Sources/App/Voice/VoiceEngine.swift`
- [Call Notes](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/NoteTaker.swift): `NotchBuddy/Sources/App/NoteTaker.swift`

### Phone Link

- [Phone Apps](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/Phone/CoucouPhoneApp.swift): `NotchBuddy/Sources/Phone/CoucouPhoneApp.swift`
- [Phone Link Server](https://github.com/the4n6analyst/coucou/blob/main/windows/src-tauri/src/phone_link/server.rs): `windows/src-tauri/src/phone_link/server.rs`
- [Phone Link Hub](https://github.com/the4n6analyst/coucou/blob/main/windows/src-tauri/src/phone_link/hub.rs): `windows/src-tauri/src/phone_link/hub.rs`
- [Android Link Client](https://github.com/the4n6analyst/coucou/blob/main/android/app/src/main/kotlin/com/coucou/android/link/LinkClient.kt): `android/app/src/main/kotlin/com/coucou/android/link/LinkClient.kt`
- [Relay Service](https://github.com/the4n6analyst/coucou/blob/main/relay/src/index.ts): `relay/src/index.ts`

### Shared UI

- [Mochi Engine](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/CoucouKit/BotEngine.swift): `NotchBuddy/Sources/CoucouKit/BotEngine.swift`
- [Pill Catalog](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/CoucouKit/PillCatalog.swift): `NotchBuddy/Sources/CoucouKit/PillCatalog.swift`
- [Sound Engine](https://github.com/the4n6analyst/coucou/blob/main/NotchBuddy/Sources/App/SoundEngine.swift): `NotchBuddy/Sources/App/SoundEngine.swift`

### Other components

- **User**

## Connections

- User → macOS App: uses (evidence: `README.md`)
- User → Windows Linux App: uses (evidence: `README.md`)
- User → Phone Apps: uses (evidence: `README.md`)
- macOS App → App State: coordinates
- Windows Linux App → Desktop Bridge: invokes (evidence: `windows/src/core/bridge.ts`)
- Windows Linux App → Island UI: renders (evidence: `windows/src/main.ts`)
- Windows Linux App → UI State: updates (evidence: `windows/src/main.ts`)
- Settings → Desktop Bridge: configures (evidence: `windows/src/settings/main.ts`)
- App State → Agent Hooks: starts (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- Agent Hooks → Approvals Questions: routes requests (evidence: `NotchBuddy/Sources/App/HookServer.swift`)
- Agent Hooks → Island UI: surfaces events
- Windows Hooks → Windows Linux App: reports events
- App State → Agent Chat: selects provider (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- Island UI → Mochi Engine: renders
- UI State → Mochi Engine: drives state (evidence: `windows/src/core/state.ts`)
- Pill Catalog → App State: defines pills (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- Flow Dictation → Offline Speech: transcribes offline
- Voice Assistant → Flow Dictation: supports capture
- Call Notes → User: returns transcript
- Phone Link Server → Phone Link Hub: dispatches messages (evidence: `windows/src-tauri/src/phone_link/server.rs`)
- Phone Link Hub → Phone Apps: sends updates
- Android Link Client → Phone Link Server: connects
- Phone Link Server → Relay Service: uses relay
- Mochi Engine → Sound Engine: plays effects (evidence: `NotchBuddy/Sources/CoucouKit/BotEngine.swift`)
- Release Recap → Desktop Bridge: loads recap (evidence: `windows/src/whats-new/controller.ts`)
