# veloleha/hameleonweb architecture

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

- Interactive diagram: https://gitdiagram.com/veloleha/hameleonweb
- Repository: https://github.com/veloleha/hameleonweb

## Overview

HAMELEONWEB is an Electron desktop manager for multiple isolated WhatsApp Web accounts, with call recording and in-call prompting. The main workflow is: an operator adds or selects an account, uses its WhatsApp session, and records a call to an MP3; licensing gates access, and settings configure recording. The graph also shows the renderer-to-main IPC boundary and recording internals. README capabilities are included, but several implementation details are unsampled, so uncertain wiring—especially licensing and updates—is omitted.

Main entry points: [`src/main/main.js`](https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js) (Electron coordinator), [`src/main/waPreload.js`](https://github.com/veloleha/hameleonweb/blob/master/src/main/waPreload.js) (WhatsApp preload), [`src/main/recorder.js`](https://github.com/veloleha/hameleonweb/blob/master/src/main/recorder.js) (Recording controller), [`src/renderer/app.js`](https://github.com/veloleha/hameleonweb/blob/master/src/renderer/app.js) (App UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_renderer["App UI<br/>[app.js]"]
  node_bridge["UI IPC bridge<br/>[preload.js]"]
end

subgraph group_core["Application services"]
  node_main["Electron coordinator<br/>[main.js]"]
  node_accounts["Account management<br/>[accounts.js]"]
  node_settings["Recording settings<br/>[settings.js]"]
  node_auth["Licensing<br/>[auth.js]"]
  node_storage[("Local JSON storage<br/>[storage.js]")]
  node_updates["Version updates<br/>[main.js]"]
end

subgraph group_whatsapp["WhatsApp sessions"]
  node_sessions["Isolated account sessions<br/>[main.js]"]
  node_wa_preload["WhatsApp preload<br/>[waPreload.js]"]
  node_wa_inject["Call and prompt injection<br/>[waInject.js]"]
  node_rtc_patch["Call detection patch<br/>[waInjectPatch.js]"]
end

subgraph group_recording["Call recording"]
  node_recorder["Recording controller<br/>[recorder.js]"]
  node_helper["Microphone MP3 capture<br/>[Program.cs]"]
end

node_operator(("Operator"))
node_whatsapp["WhatsApp Web"]
node_ffmpeg["FFmpeg transcoder"]
node_recordings[("Recording files")]
node_license_service["License service"]

node_operator -->|"uses"| node_renderer
node_renderer -->|"calls API"| node_bridge
node_bridge -->|"invokes IPC"| node_main
node_main -->|"manages accounts"| node_accounts
node_main -->|"loads and saves"| node_settings
node_main -->|"handles licensing"| node_auth
node_auth -->|"persists auth"| node_storage
node_main -->|"creates and selects"| node_sessions
node_sessions -->|"loads session"| node_whatsapp
node_sessions -->|"attaches preload"| node_wa_preload
node_wa_preload -->|"receives page messages"| node_wa_inject
node_wa_preload -->|"observes call state"| node_rtc_patch
node_wa_preload -->|"sends IPC events"| node_main
node_main -->|"starts and stops"| node_recorder
node_recorder -.->|"launches capture"| node_helper
node_helper -->|"writes MP3"| node_recordings
node_recorder -->|"transcodes audio"| node_ffmpeg
node_recorder -->|"writes recordings"| node_recordings
node_main -->|"controls prompt and capture"| node_wa_inject
node_auth -.->|"validates licenses"| node_license_service
node_renderer -->|"requests updates"| node_updates

click node_renderer "https://github.com/veloleha/hameleonweb/blob/master/src/renderer/app.js"
click node_bridge "https://github.com/veloleha/hameleonweb/blob/master/src/renderer/preload.js"
click node_main "https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js"
click node_accounts "https://github.com/veloleha/hameleonweb/blob/master/src/main/accounts.js"
click node_settings "https://github.com/veloleha/hameleonweb/blob/master/src/main/settings.js"
click node_auth "https://github.com/veloleha/hameleonweb/blob/master/src/main/auth.js"
click node_storage "https://github.com/veloleha/hameleonweb/blob/master/src/main/storage.js"
click node_updates "https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js"
click node_sessions "https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js"
click node_wa_preload "https://github.com/veloleha/hameleonweb/blob/master/src/main/waPreload.js"
click node_wa_inject "https://github.com/veloleha/hameleonweb/blob/master/src/main/waInject.js"
click node_rtc_patch "https://github.com/veloleha/hameleonweb/blob/master/src/main/waInjectPatch.js"
click node_recorder "https://github.com/veloleha/hameleonweb/blob/master/src/main/recorder.js"
click node_helper "https://github.com/veloleha/hameleonweb/blob/master/src/main/recorder-helper/Program.cs"

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_renderer,node_bridge toneBlue
class node_main,node_accounts,node_settings,node_auth,node_storage,node_updates,node_recordings toneAmber
class node_sessions,node_wa_preload,node_wa_inject,node_rtc_patch toneMint
class node_recorder,node_helper toneRose
class node_operator,node_whatsapp,node_ffmpeg,node_license_service toneIndigo
```

## Components

### Desktop interface

- [App UI](https://github.com/veloleha/hameleonweb/blob/master/src/renderer/app.js): `src/renderer/app.js`
- [UI IPC bridge](https://github.com/veloleha/hameleonweb/blob/master/src/renderer/preload.js): `src/renderer/preload.js`

### Application services

- [Electron coordinator](https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js): `src/main/main.js`
- [Account management](https://github.com/veloleha/hameleonweb/blob/master/src/main/accounts.js): `src/main/accounts.js`
- [Recording settings](https://github.com/veloleha/hameleonweb/blob/master/src/main/settings.js): `src/main/settings.js`
- [Licensing](https://github.com/veloleha/hameleonweb/blob/master/src/main/auth.js): `src/main/auth.js`
- [Local JSON storage](https://github.com/veloleha/hameleonweb/blob/master/src/main/storage.js): `src/main/storage.js`
- [Version updates](https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js): `src/main/main.js`

### WhatsApp sessions

- [Isolated account sessions](https://github.com/veloleha/hameleonweb/blob/master/src/main/main.js): `src/main/main.js`
- [WhatsApp preload](https://github.com/veloleha/hameleonweb/blob/master/src/main/waPreload.js): `src/main/waPreload.js`
- [Call and prompt injection](https://github.com/veloleha/hameleonweb/blob/master/src/main/waInject.js): `src/main/waInject.js`
- [Call detection patch](https://github.com/veloleha/hameleonweb/blob/master/src/main/waInjectPatch.js): `src/main/waInjectPatch.js`

### Call recording

- [Recording controller](https://github.com/veloleha/hameleonweb/blob/master/src/main/recorder.js): `src/main/recorder.js`
- [Microphone MP3 capture](https://github.com/veloleha/hameleonweb/blob/master/src/main/recorder-helper/Program.cs): `src/main/recorder-helper/Program.cs`

### Other components

- **Operator**
- **WhatsApp Web**
- **FFmpeg transcoder**
- **Recording files**
- **License service**

## Connections

- Operator → App UI: uses
- App UI → UI IPC bridge: calls API
- UI IPC bridge → Electron coordinator: invokes IPC
- Electron coordinator → Account management: manages accounts
- Electron coordinator → Recording settings: loads and saves
- Electron coordinator → Licensing: handles licensing
- Licensing → Local JSON storage: persists auth
- Electron coordinator → Isolated account sessions: creates and selects
- Isolated account sessions → WhatsApp Web: loads session
- Isolated account sessions → WhatsApp preload: attaches preload
- WhatsApp preload → Call and prompt injection: receives page messages
- WhatsApp preload → Call detection patch: observes call state
- WhatsApp preload → Electron coordinator: sends IPC events
- Electron coordinator → Recording controller: starts and stops
- Recording controller → Microphone MP3 capture: launches capture
- Microphone MP3 capture → Recording files: writes MP3
- Recording controller → FFmpeg transcoder: transcodes audio
- Recording controller → Recording files: writes recordings
- Electron coordinator → Call and prompt injection: controls prompt and capture
- Licensing → License service: validates licenses
- App UI → Version updates: requests updates