# theunknownodysseus/happy-sisyphus architecture

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

- Interactive diagram: https://gitdiagram.com/theunknownodysseus/happy-sisyphus
- Repository: https://github.com/theunknownodysseus/happy-sisyphus

## Overview

happy-sisyphus is an Electron desktop chat and project workspace for the Bonsai CLI. A user opens the app, which manages login and a persistent Bonsai terminal session; prompts and terminal output flow through IPC to the chat UI. The workspace also supports changed-file and Git status views, file browsing/editing, and an embedded shell. README and sampled source establish the main process, session, and renderer relationships; unsampled subsystem links are omitted where their callers are not evidenced.

Main entry points: [`src/main/index.ts`](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/index.ts) (Electron main), [`src/renderer/src/components/EditorView.tsx`](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorView.tsx) (Mini editor), [`src/renderer/src/App.tsx`](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/App.tsx) (App shell), [`src/main/BonsaiSession.ts`](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/BonsaiSession.ts) (Bonsai session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Desktop and session"]
  node_launcher["CLI launcher<br/>[index.js]"]
  node_main["Electron main<br/>[index.ts]"]
  node_session["Bonsai session<br/>[BonsaiSession.ts]"]
  node_watcher["File watcher<br/>[FileWatcher.ts]"]
  node_persistence[("Session persistence<br/>[persistence.ts]")]
end

subgraph group_chat["Chat interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_sessionhook["Session state hook<br/>[useSession.ts]"]
  node_prompt["Prompt input<br/>[PromptInput.tsx]"]
  node_terminal["Bonsai terminal<br/>[TerminalPanel.tsx]"]
  node_toolbar["Session toolbar<br/>[Toolbar.tsx]"]
  node_theme["Theme preference<br/>[useTheme.ts]"]
end

subgraph group_workspace["Project workspace"]
  node_shell["Workspace shell<br/>[ShellTerminal.ts]"]
  node_changed["Changed files<br/>[ChangedFiles.tsx]"]
  node_editorview["Mini editor<br/>[EditorView.tsx]"]
  node_tree["File tree<br/>[FileTree.tsx]"]
  node_finder["File finder<br/>[FileFinder.tsx]"]
  node_tabs["Editor tabs<br/>[EditorTabs.tsx]"]
  node_code["Code editor<br/>[CodeEditor.tsx]"]
  node_editorterm["Editor terminal<br/>[EditorTerminal.tsx]"]
  node_footer["Git footer<br/>[Footer.tsx]"]
  node_gitstatus["Git status hook<br/>[useGitStatus.ts]"]
  node_editsettings["Editor preferences"]
end

subgraph group_shared["IPC and state"]
  node_preload["Context bridge<br/>[index.ts]"]
  node_types["Shared IPC types<br/>[types.ts]"]
end

node_developer(("Developer"))
node_bonsai["Bonsai CLI"]

node_developer -->|"launches"| node_launcher
node_launcher -->|"opens app"| node_main
node_main -->|"owns session"| node_session
node_main -->|"starts watcher"| node_watcher
node_main -->|"uses persistence"| node_persistence
node_session -->|"drives PTY"| node_bonsai
node_main -->|"configures bridge"| node_preload
node_preload -->|"exposes IPC"| node_app
node_app -->|"reads session"| node_sessionhook
node_app -->|"renders"| node_prompt
node_app -->|"renders"| node_terminal
node_app -->|"renders"| node_changed
node_app -->|"renders"| node_editorview
node_app -->|"renders"| node_toolbar
node_sessionhook -->|"calls API"| node_preload
node_terminal -->|"subscribes data"| node_sessionhook
node_prompt -->|"sends prompts"| node_sessionhook
node_session -->|"streams events"| node_main
node_watcher -->|"reports changes"| node_main
node_editorview -->|"renders"| node_tree
node_editorview -->|"renders"| node_finder
node_editorview -->|"renders"| node_tabs
node_editorview -->|"renders"| node_code
node_editorview -->|"renders"| node_editorterm
node_tree -->|"reads status"| node_gitstatus
node_footer -->|"reads status"| node_gitstatus
node_editorview -->|"loads preferences"| node_editsettings
node_editorview -->|"uses theme"| node_theme
node_main -.->|"routes shell IPC"| node_shell
node_session -.->|"stores history"| node_persistence
node_main -->|"forwards file events"| node_changed
node_main -->|"uses channel contracts"| node_types
node_preload -->|"uses API types"| node_types

click node_launcher "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/bin/index.js"
click node_main "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/index.ts"
click node_session "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/BonsaiSession.ts"
click node_watcher "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/FileWatcher.ts"
click node_persistence "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/persistence.ts"
click node_shell "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/ShellTerminal.ts"
click node_preload "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/preload/index.ts"
click node_types "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/shared/types.ts"
click node_app "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/App.tsx"
click node_sessionhook "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useSession.ts"
click node_prompt "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/PromptInput.tsx"
click node_terminal "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/TerminalPanel.tsx"
click node_toolbar "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/Toolbar.tsx"
click node_changed "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/ChangedFiles.tsx"
click node_editorview "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorView.tsx"
click node_tree "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/FileTree.tsx"
click node_finder "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/FileFinder.tsx"
click node_tabs "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorTabs.tsx"
click node_code "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/CodeEditor.tsx"
click node_editorterm "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorTerminal.tsx"
click node_footer "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/Footer.tsx"
click node_gitstatus "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useGitStatus.ts"
click node_editsettings "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useEditorSettings.ts"
click node_theme "https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useTheme.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_launcher,node_main,node_session,node_watcher,node_persistence toneBlue
class node_app,node_sessionhook,node_prompt,node_terminal,node_toolbar,node_theme toneAmber
class node_shell,node_changed,node_editorview,node_tree,node_finder,node_tabs,node_code,node_editorterm,node_footer,node_gitstatus,node_editsettings toneMint
class node_preload,node_types toneRose
class node_developer,node_bonsai toneIndigo
```

## Components

### Desktop and session

- [CLI launcher](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/bin/index.js): `bin/index.js`
- [Electron main](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/index.ts): `src/main/index.ts`
- [Bonsai session](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/BonsaiSession.ts): `src/main/BonsaiSession.ts`
- [File watcher](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/FileWatcher.ts): `src/main/FileWatcher.ts`
- [Session persistence](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/persistence.ts): `src/main/persistence.ts`

### Chat interface

- [App shell](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Session state hook](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useSession.ts): `src/renderer/src/hooks/useSession.ts`
- [Prompt input](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/PromptInput.tsx): `src/renderer/src/components/PromptInput.tsx`
- [Bonsai terminal](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/TerminalPanel.tsx): `src/renderer/src/components/TerminalPanel.tsx`
- [Session toolbar](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/Toolbar.tsx): `src/renderer/src/components/Toolbar.tsx`
- [Theme preference](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useTheme.ts): `src/renderer/src/hooks/useTheme.ts`

### Project workspace

- [Workspace shell](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/main/ShellTerminal.ts): `src/main/ShellTerminal.ts`
- [Changed files](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/ChangedFiles.tsx): `src/renderer/src/components/ChangedFiles.tsx`
- [Mini editor](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorView.tsx): `src/renderer/src/components/EditorView.tsx`
- [File tree](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/FileTree.tsx): `src/renderer/src/components/FileTree.tsx`
- [File finder](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/FileFinder.tsx): `src/renderer/src/components/FileFinder.tsx`
- [Editor tabs](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorTabs.tsx): `src/renderer/src/components/EditorTabs.tsx`
- [Code editor](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/CodeEditor.tsx): `src/renderer/src/components/CodeEditor.tsx`
- [Editor terminal](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/EditorTerminal.tsx): `src/renderer/src/components/EditorTerminal.tsx`
- [Git footer](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/components/Footer.tsx): `src/renderer/src/components/Footer.tsx`
- [Git status hook](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useGitStatus.ts): `src/renderer/src/hooks/useGitStatus.ts`
- [Editor preferences](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/renderer/src/hooks/useEditorSettings.ts): `src/renderer/src/hooks/useEditorSettings.ts`

### IPC and state

- [Context bridge](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Shared IPC types](https://github.com/theunknownodysseus/happy-sisyphus/blob/main/src/shared/types.ts): `src/shared/types.ts`

### Other components

- **Developer**
- **Bonsai CLI**

## Connections

- Developer → CLI launcher: launches (evidence: `README.md`)
- CLI launcher → Electron main: opens app (evidence: `README.md`)
- Electron main → Bonsai session: owns session (evidence: `src/main/index.ts`)
- Electron main → File watcher: starts watcher (evidence: `src/main/index.ts`)
- Electron main → Session persistence: uses persistence (evidence: `src/main/index.ts`)
- Bonsai session → Bonsai CLI: drives PTY (evidence: `README.md`)
- Electron main → Context bridge: configures bridge (evidence: `src/main/index.ts`)
- Context bridge → App shell: exposes IPC (evidence: `README.md`)
- App shell → Session state hook: reads session (evidence: `src/renderer/src/App.tsx`)
- App shell → Prompt input: renders (evidence: `src/renderer/src/App.tsx`)
- App shell → Bonsai terminal: renders (evidence: `src/renderer/src/App.tsx`)
- App shell → Changed files: renders (evidence: `src/renderer/src/App.tsx`)
- App shell → Mini editor: renders (evidence: `src/renderer/src/App.tsx`)
- App shell → Session toolbar: renders (evidence: `src/renderer/src/App.tsx`)
- Session state hook → Context bridge: calls API (evidence: `src/renderer/src/hooks/useSession.ts`)
- Bonsai terminal → Session state hook: subscribes data (evidence: `README.md`)
- Prompt input → Session state hook: sends prompts (evidence: `src/renderer/src/components/PromptInput.tsx`)
- Bonsai session → Electron main: streams events (evidence: `src/main/index.ts`)
- File watcher → Electron main: reports changes (evidence: `README.md`)
- Mini editor → File tree: renders (evidence: `src/renderer/src/components/EditorView.tsx`)
- Mini editor → File finder: renders (evidence: `src/renderer/src/components/EditorView.tsx`)
- Mini editor → Editor tabs: renders (evidence: `src/renderer/src/components/EditorView.tsx`)
- Mini editor → Code editor: renders (evidence: `src/renderer/src/components/EditorView.tsx`)
- Mini editor → Editor terminal: renders (evidence: `src/renderer/src/components/EditorView.tsx`)
- File tree → Git status hook: reads status (evidence: `src/renderer/src/components/FileTree.tsx`)
- Git footer → Git status hook: reads status (evidence: `src/renderer/src/components/Footer.tsx`)
- Mini editor → Editor preferences: loads preferences (evidence: `src/renderer/src/components/EditorView.tsx`)
- Mini editor → Theme preference: uses theme (evidence: `src/renderer/src/components/EditorView.tsx`)
- Electron main → Workspace shell: routes shell IPC (evidence: `src/main/index.ts`)
- Bonsai session → Session persistence: stores history
- Electron main → Changed files: forwards file events (evidence: `README.md`)
- Electron main → Shared IPC types: uses channel contracts (evidence: `src/main/index.ts`)
- Context bridge → Shared IPC types: uses API types (evidence: `src/preload/index.ts`)
