# rizulsharma-2003/tamagotchi architecture

> Architecture diagram of the GitHub repository rizulsharma-2003/tamagotchi, 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/rizulsharma-2003/tamagotchi
- Repository: https://github.com/rizulsharma-2003/tamagotchi

## Overview

MacTamagotchi is a local-first macOS menu-bar pet and Claude Code companion. The central path is Claude hook setup, hook events delivered over a private Unix socket, and the app reflecting live session activity in Mochi and Patch; users also interact through the menu bar and optional desktop pet. Separate branches cover Ask Mochi, phone linking, room customization, and play/progression. Edges are limited to relationships explicit in the README or shown by the source index/excerpts; many internal details are unsampled.

Main entry points: [`Sources/App/Features/Assistant/AssistantController.swift`](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/AssistantController.swift) (Ask Mochi), [`Sources/App/Integration/IntegrationController.swift`](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Integration/IntegrationController.swift) (Hook setup), [`Sources/TamagotchiCore/World/CompanionWorld.swift`](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/World/CompanionWorld.swift) (Companion world), [`Sources/App/Features/Phone/PhoneController.swift`](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Phone/PhoneController.swift) (Phone sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Claude Integration"]
  node_hooksetup["Hook setup"]
  node_installer["Hook installer"]
  node_locator["Claude detection"]
  node_hookhelper["Hook helper<br/>[main.swift]"]
  node_bridge["Local event bridge<br/>[BridgeClient.swift]"]
  node_wire["Wire events<br/>[WireEvent.swift]"]
end

subgraph group_experience["Mac Companion"]
  node_app["App environment"]
  node_menubar["Menu bar scene"]
  node_scene["Scene rendering<br/>[SceneView.swift]"]
  node_desktop["Desktop pet"]
end

subgraph group_core["World and Progress"]
  node_world["Companion world"]
  node_achievements["Progress tracking"]
  node_settings[("Settings store")]
end

subgraph group_features["Companion Features"]
  node_assistant["Ask Mochi"]
  node_brain["Helper session<br/>[BrainSession.swift]"]
  node_quick["Quick commands"]
  node_macactions["Mac actions<br/>[MacActions.swift]"]
  node_room["Room editor"]
  node_catalog["Furniture catalog"]
  node_games["Mini-games"]
end

subgraph group_phone["Phone Link"]
  node_phone["Phone sync"]
  node_link[("Link security<br/>[LinkStore.swift]")]
  node_phoneapp["Mochi Pocket<br/>[ContentView.swift]"]
end

node_user(("Mac user"))
node_claude["Claude Code"]

node_user -->|"connects Claude"| node_hooksetup
node_hooksetup -->|"detects install"| node_locator
node_hooksetup -->|"installs hooks"| node_installer
node_installer -->|"configures hooks"| node_claude
node_claude -->|"emits hook events"| node_hookhelper
node_hookhelper -.->|"sends event"| node_bridge
node_bridge -->|"transfers JSON"| node_wire
node_app -.->|"owns companion"| node_world
node_world -.->|"records progress"| node_achievements
node_world -.->|"consumes events"| node_wire
node_app -.->|"uses settings"| node_settings
node_user -->|"interacts"| node_menubar
node_menubar -.->|"renders scene"| node_scene
node_user -->|"pets or moves"| node_desktop
node_desktop -->|"hosts scene"| node_scene
node_user -->|"asks Mochi"| node_assistant
node_assistant -->|"parses request"| node_quick
node_assistant -->|"performs action"| node_macactions
node_assistant -->|"sends complex request"| node_brain
node_user -->|"customizes room"| node_room
node_room -->|"checks furniture"| node_catalog
node_user -->|"plays games"| node_games
node_user -->|"connects phone"| node_phone
node_phone -->|"uses link store"| node_link
node_phone -.->|"syncs companion"| node_phoneapp

click node_app "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/AppEnvironment.swift"
click node_hooksetup "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Integration/IntegrationController.swift"
click node_installer "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Integration/ClaudeHookInstaller.swift"
click node_locator "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Integration/ClaudeCodeLocator.swift"
click node_hookhelper "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/HookHelper/main.swift"
click node_bridge "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiWire/BridgeClient.swift"
click node_wire "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiWire/WireEvent.swift"
click node_world "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/World/CompanionWorld.swift"
click node_achievements "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Progress/AchievementEngine.swift"
click node_settings "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Settings/SettingsStore.swift"
click node_menubar "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/MenuBar/StatusItemController.swift"
click node_scene "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Rendering/SceneView.swift"
click node_desktop "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Desktop/DesktopPetController.swift"
click node_assistant "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/AssistantController.swift"
click node_brain "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/BrainSession.swift"
click node_quick "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Assistant/QuickCommands.swift"
click node_macactions "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/MacActions.swift"
click node_room "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Room/RoomEditorController.swift"
click node_catalog "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Features/FurnitureCatalog.swift"
click node_games "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Games/GamesController.swift"
click node_phone "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Phone/PhoneController.swift"
click node_link "https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Link/LinkStore.swift"
click node_phoneapp "https://github.com/rizulsharma-2003/tamagotchi/blob/main/iOS/MochiPocket/ContentView.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_hooksetup,node_installer,node_locator,node_hookhelper,node_bridge,node_wire,node_user toneBlue
class node_app,node_menubar,node_scene,node_desktop toneAmber
class node_world,node_achievements,node_settings toneMint
class node_assistant,node_brain,node_quick,node_macactions,node_room,node_catalog,node_games toneRose
class node_phone,node_link,node_phoneapp,node_claude toneIndigo
```

## Components

### Claude Integration

- [Hook setup](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Integration/IntegrationController.swift): `Sources/App/Integration/IntegrationController.swift`
- [Hook installer](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Integration/ClaudeHookInstaller.swift): `Sources/TamagotchiCore/Integration/ClaudeHookInstaller.swift`
- [Claude detection](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Integration/ClaudeCodeLocator.swift): `Sources/TamagotchiCore/Integration/ClaudeCodeLocator.swift`
- [Hook helper](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/HookHelper/main.swift): `Sources/HookHelper/main.swift`
- [Local event bridge](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiWire/BridgeClient.swift): `Sources/TamagotchiWire/BridgeClient.swift`
- [Wire events](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiWire/WireEvent.swift): `Sources/TamagotchiWire/WireEvent.swift`

### Mac Companion

- [App environment](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/AppEnvironment.swift): `Sources/App/AppEnvironment.swift`
- [Menu bar scene](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/MenuBar/StatusItemController.swift): `Sources/App/MenuBar/StatusItemController.swift`
- [Scene rendering](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Rendering/SceneView.swift): `Sources/App/Rendering/SceneView.swift`
- [Desktop pet](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Desktop/DesktopPetController.swift): `Sources/App/Desktop/DesktopPetController.swift`

### World and Progress

- [Companion world](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/World/CompanionWorld.swift): `Sources/TamagotchiCore/World/CompanionWorld.swift`
- [Progress tracking](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Progress/AchievementEngine.swift): `Sources/TamagotchiCore/Progress/AchievementEngine.swift`
- [Settings store](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Settings/SettingsStore.swift): `Sources/TamagotchiCore/Settings/SettingsStore.swift`

### Companion Features

- [Ask Mochi](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/AssistantController.swift): `Sources/App/Features/Assistant/AssistantController.swift`
- [Helper session](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/BrainSession.swift): `Sources/App/Features/Assistant/BrainSession.swift`
- [Quick commands](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Assistant/QuickCommands.swift): `Sources/TamagotchiCore/Assistant/QuickCommands.swift`
- [Mac actions](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Assistant/MacActions.swift): `Sources/App/Features/Assistant/MacActions.swift`
- [Room editor](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Room/RoomEditorController.swift): `Sources/App/Features/Room/RoomEditorController.swift`
- [Furniture catalog](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Features/FurnitureCatalog.swift): `Sources/TamagotchiCore/Features/FurnitureCatalog.swift`
- [Mini-games](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Games/GamesController.swift): `Sources/App/Features/Games/GamesController.swift`

### Phone Link

- [Phone sync](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/App/Features/Phone/PhoneController.swift): `Sources/App/Features/Phone/PhoneController.swift`
- [Link security](https://github.com/rizulsharma-2003/tamagotchi/blob/main/Sources/TamagotchiCore/Link/LinkStore.swift): `Sources/TamagotchiCore/Link/LinkStore.swift`
- [Mochi Pocket](https://github.com/rizulsharma-2003/tamagotchi/blob/main/iOS/MochiPocket/ContentView.swift): `iOS/MochiPocket/ContentView.swift`

### Other components

- **Mac user**
- **Claude Code**

## Connections

- Mac user → Hook setup: connects Claude (evidence: `README.md`)
- Hook setup → Claude detection: detects install (evidence: `Sources/App/Integration/IntegrationController.swift`)
- Hook setup → Hook installer: installs hooks (evidence: `Sources/App/Integration/IntegrationController.swift`)
- Hook installer → Claude Code: configures hooks (evidence: `README.md`)
- Claude Code → Hook helper: emits hook events (evidence: `README.md`)
- Hook helper → Local event bridge: sends event
- Local event bridge → Wire events: transfers JSON (evidence: `Sources/TamagotchiWire/BridgeClient.swift`)
- App environment → Companion world: owns companion
- Companion world → Progress tracking: records progress
- Companion world → Wire events: consumes events
- App environment → Settings store: uses settings
- Mac user → Menu bar scene: interacts (evidence: `README.md`)
- Menu bar scene → Scene rendering: renders scene
- Mac user → Desktop pet: pets or moves (evidence: `README.md`)
- Desktop pet → Scene rendering: hosts scene (evidence: `Sources/App/Desktop/DesktopPetController.swift`)
- Mac user → Ask Mochi: asks Mochi (evidence: `README.md`)
- Ask Mochi → Quick commands: parses request (evidence: `Sources/App/Features/Assistant/AssistantController.swift`)
- Ask Mochi → Mac actions: performs action (evidence: `Sources/App/Features/Assistant/AssistantController.swift`)
- Ask Mochi → Helper session: sends complex request (evidence: `Sources/App/Features/Assistant/AssistantController.swift`)
- Mac user → Room editor: customizes room (evidence: `README.md`)
- Room editor → Furniture catalog: checks furniture (evidence: `Sources/App/Features/Room/RoomEditorController.swift`)
- Mac user → Mini-games: plays games (evidence: `README.md`)
- Mac user → Phone sync: connects phone (evidence: `README.md`)
- Phone sync → Link security: uses link store (evidence: `Sources/App/Features/Phone/PhoneController.swift`)
- Phone sync → Mochi Pocket: syncs companion