# bitter-caramel/remote_control architecture

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

- Interactive diagram: https://gitdiagram.com/bitter-caramel/remote_control
- Repository: https://github.com/bitter-caramel/remote_control

## Overview

Remote_control is a two-program remote-assistance system: the user-side agent initiates a persistent connection to the helper, registers its identity, and bridges a persistent interactive shell; operators then view and control that terminal through the DOS panel, a local terminal window, or the browser console. The helper also supports one-shot command execution, role-based access, machine visibility levels, and persistent account/session/audit data. Edges use excerpts or README statements; some internal routing and unsampled subsystems are documented rather than shown in source excerpts.

Main entry points: [`helper/internal/app/main.go`](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/app/main.go) (Runtime Assembly), [`helper/internal/core/manager.go`](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/manager.go) (Bot Manager), [`user/internal/agent/main.go`](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/agent/main.go) (Agent Entry), [`helper/internal/webui/server.go`](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/webui/server.go) (Browser Console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["User Agent"]
  node_user_entry["Agent Entry<br/>[main.go]"]
  node_user_config["Identity Config<br/>[config.go]"]
  node_user_conn["Server Connection<br/>[conn.go]"]
  node_user_shell["Interactive Shell<br/>[shell.go]"]
  node_user_exec["One-shot Exec<br/>[agentexec.go]"]
end

subgraph group_server["Helper Runtime"]
  node_helper_app["Runtime Assembly<br/>[main.go]"]
  node_uplink["Agent Listener<br/>[listener.go]"]
  node_manager["Bot Manager<br/>[manager.go]"]
  node_bot["Bot Session<br/>[bot.go]"]
  node_heartbeat["Heartbeat Monitor<br/>[heartbeat.go]"]
end

subgraph group_access["Operator Interfaces"]
  node_panel["DOS Panel<br/>[panel.go]"]
  node_panel_bot["Panel Bot Actions<br/>[bot.go]"]
  node_ipc_server["Local IPC<br/>[server.go]"]
  node_ipc_window["Terminal Window<br/>[client.go]"]
  node_ipc_cli["CLI Agent<br/>[agentcli.go]"]
  node_webui["Browser Console<br/>[server.go]"]
end

subgraph group_security["Access and Records"]
  node_auth["Authentication<br/>[auth.go]"]
  node_store[("SQLite Records<br/>[store.go]")]
  node_admin["Account and Bot Admin<br/>[admin.go]"]
end

subgraph group_shared["Protocol and Logs"]
  node_protocol["Wire Protocol<br/>[message.go]"]
  node_user_protocol["Agent Protocol Copy<br/>[message.go]"]
  node_logging["Operational Logs<br/>[logx.go]"]
end

node_operator(("Operator"))
node_userhost(("Managed Host"))

node_userhost -->|"starts"| node_user_entry
node_user_entry -->|"loads identity"| node_user_config
node_user_entry -->|"dials and registers"| node_user_conn
node_user_entry -->|"starts shell"| node_user_shell
node_user_shell -.->|"streams terminal"| node_user_conn
node_user_entry -.->|"dispatches commands"| node_user_exec
node_user_entry -->|"exchanges messages"| node_user_protocol
node_user_conn -->|"connects to"| node_uplink
node_helper_app -->|"starts listener"| node_uplink
node_helper_app -->|"mounts routes"| node_webui
node_helper_app -->|"starts IPC"| node_ipc_server
node_helper_app -->|"runs panel"| node_panel
node_helper_app -->|"creates manager"| node_manager
node_helper_app -->|"opens database"| node_store
node_helper_app -->|"configures auth"| node_auth
node_uplink -->|"registers agents"| node_manager
node_manager -->|"tracks sessions"| node_bot
node_heartbeat -->|"marks missed beats"| node_manager
node_panel -.->|"dispatches actions"| node_panel_bot
node_panel_bot -.->|"gets bot state"| node_manager
node_panel -->|"opens terminal"| node_ipc_server
node_ipc_window -->|"attaches locally"| node_ipc_server
node_ipc_server -->|"subscribes to bot"| node_manager
node_ipc_cli -->|"uses CLI channel"| node_ipc_server
node_webui -->|"requires sessions"| node_auth
node_webui -->|"lists and bridges bots"| node_manager
node_webui -->|"reads access levels"| node_store
node_admin -.->|"manages accounts"| node_store
node_auth -.->|"checks credentials"| node_store
node_manager -->|"records connections"| node_logging
node_user_protocol -->|"mirrors schema"| node_protocol
node_operator -->|"enters commands"| node_panel
node_operator -->|"uses browser"| node_webui
node_user_conn -.->|"forwards input"| node_user_shell

click node_user_entry "https://github.com/bitter-caramel/remote_control/blob/main/user/internal/agent/main.go"
click node_user_config "https://github.com/bitter-caramel/remote_control/blob/main/user/internal/core/config.go"
click node_user_conn "https://github.com/bitter-caramel/remote_control/blob/main/user/internal/core/conn.go"
click node_user_shell "https://github.com/bitter-caramel/remote_control/blob/main/user/internal/term/shell.go"
click node_user_exec "https://github.com/bitter-caramel/remote_control/blob/main/user/internal/exec/agentexec.go"
click node_helper_app "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/app/main.go"
click node_uplink "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/uplink/listener.go"
click node_manager "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/manager.go"
click node_bot "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/bot.go"
click node_heartbeat "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/heartbeat.go"
click node_panel "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/panel/panel.go"
click node_panel_bot "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/panel/bot.go"
click node_ipc_server "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/server.go"
click node_ipc_window "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/client.go"
click node_ipc_cli "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/agentcli.go"
click node_webui "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/webui/server.go"
click node_auth "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/auth/auth.go"
click node_store "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/store/store.go"
click node_admin "https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/webui/admin.go"
click node_protocol "https://github.com/bitter-caramel/remote_control/blob/main/helper/protocol/message.go"
click node_user_protocol "https://github.com/bitter-caramel/remote_control/blob/main/user/protocol/message.go"
click node_logging "https://github.com/bitter-caramel/remote_control/blob/main/helper/logx/logx.go"

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_user_entry,node_user_config,node_user_conn,node_user_shell,node_user_exec toneBlue
class node_helper_app,node_uplink,node_manager,node_bot,node_heartbeat toneAmber
class node_panel,node_panel_bot,node_ipc_server,node_ipc_window,node_ipc_cli,node_webui toneMint
class node_auth,node_store,node_admin toneRose
class node_protocol,node_user_protocol,node_logging,node_operator,node_userhost toneIndigo
```

## Components

### User Agent

- [Agent Entry](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/agent/main.go): `user/internal/agent/main.go`
- [Identity Config](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/core/config.go): `user/internal/core/config.go`
- [Server Connection](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/core/conn.go): `user/internal/core/conn.go`
- [Interactive Shell](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/term/shell.go): `user/internal/term/shell.go`
- [One-shot Exec](https://github.com/bitter-caramel/remote_control/blob/main/user/internal/exec/agentexec.go): `user/internal/exec/agentexec.go`

### Helper Runtime

- [Runtime Assembly](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/app/main.go): `helper/internal/app/main.go`
- [Agent Listener](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/uplink/listener.go): `helper/internal/uplink/listener.go`
- [Bot Manager](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/manager.go): `helper/internal/core/manager.go`
- [Bot Session](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/bot.go): `helper/internal/core/bot.go`
- [Heartbeat Monitor](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/core/heartbeat.go): `helper/internal/core/heartbeat.go`

### Operator Interfaces

- [DOS Panel](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/panel/panel.go): `helper/internal/panel/panel.go`
- [Panel Bot Actions](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/panel/bot.go): `helper/internal/panel/bot.go`
- [Local IPC](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/server.go): `helper/internal/ipc/server.go`
- [Terminal Window](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/client.go): `helper/internal/ipc/client.go`
- [CLI Agent](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/ipc/agentcli.go): `helper/internal/ipc/agentcli.go`
- [Browser Console](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/webui/server.go): `helper/internal/webui/server.go`

### Access and Records

- [Authentication](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/auth/auth.go): `helper/internal/auth/auth.go`
- [SQLite Records](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/store/store.go): `helper/internal/store/store.go`
- [Account and Bot Admin](https://github.com/bitter-caramel/remote_control/blob/main/helper/internal/webui/admin.go): `helper/internal/webui/admin.go`

### Protocol and Logs

- [Wire Protocol](https://github.com/bitter-caramel/remote_control/blob/main/helper/protocol/message.go): `helper/protocol/message.go`
- [Agent Protocol Copy](https://github.com/bitter-caramel/remote_control/blob/main/user/protocol/message.go): `user/protocol/message.go`
- [Operational Logs](https://github.com/bitter-caramel/remote_control/blob/main/helper/logx/logx.go): `helper/logx/logx.go`

### Other components

- **Operator**
- **Managed Host**

## Connections

- Managed Host → Agent Entry: starts
- Agent Entry → Identity Config: loads identity (evidence: `user/internal/agent/main.go`)
- Agent Entry → Server Connection: dials and registers (evidence: `user/internal/agent/main.go`)
- Agent Entry → Interactive Shell: starts shell (evidence: `user/internal/agent/main.go`)
- Interactive Shell → Server Connection: streams terminal (evidence: `README.md`)
- Agent Entry → One-shot Exec: dispatches commands (evidence: `README.md`)
- Agent Entry → Agent Protocol Copy: exchanges messages (evidence: `user/internal/agent/main.go`)
- Server Connection → Agent Listener: connects to (evidence: `README.md`)
- Runtime Assembly → Agent Listener: starts listener (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → Browser Console: mounts routes (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → Local IPC: starts IPC (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → DOS Panel: runs panel (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → Bot Manager: creates manager (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → SQLite Records: opens database (evidence: `helper/internal/app/main.go`)
- Runtime Assembly → Authentication: configures auth (evidence: `helper/internal/app/main.go`)
- Agent Listener → Bot Manager: registers agents (evidence: `README.md`)
- Bot Manager → Bot Session: tracks sessions (evidence: `helper/internal/core/manager.go`)
- Heartbeat Monitor → Bot Manager: marks missed beats (evidence: `README.md`)
- DOS Panel → Panel Bot Actions: dispatches actions
- Panel Bot Actions → Bot Manager: gets bot state
- DOS Panel → Local IPC: opens terminal
- Terminal Window → Local IPC: attaches locally (evidence: `helper/internal/ipc/client.go`)
- Local IPC → Bot Manager: subscribes to bot (evidence: `helper/internal/ipc/server.go`)
- CLI Agent → Local IPC: uses CLI channel (evidence: `helper/internal/ipc/server.go`)
- Browser Console → Authentication: requires sessions (evidence: `helper/internal/webui/server.go`)
- Browser Console → Bot Manager: lists and bridges bots (evidence: `helper/internal/webui/server.go`)
- Browser Console → SQLite Records: reads access levels (evidence: `helper/internal/webui/server.go`)
- Account and Bot Admin → SQLite Records: manages accounts (evidence: `README.md`)
- Authentication → SQLite Records: checks credentials (evidence: `README.md`)
- Bot Manager → Operational Logs: records connections (evidence: `helper/internal/core/manager.go`)
- Agent Protocol Copy → Wire Protocol: mirrors schema (evidence: `README.md`)
- Operator → DOS Panel: enters commands (evidence: `README.md`)
- Operator → Browser Console: uses browser (evidence: `README.md`)
- Server Connection → Interactive Shell: forwards input (evidence: `README.md`)