# aidanslab/pipboy3000companion architecture

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

- Interactive diagram: https://gitdiagram.com/aidanslab/pipboy3000companion
- Repository: https://github.com/aidanslab/pipboy3000companion
- Video tour (about a minute): https://gitdiagram.com/aidanslab/pipboy3000companion/video

## Overview

Pip-Boy 3000 Companion synchronizes Fallout 3/New Vegas player state and inventory to the USB-connected replica. Game-specific plugins collect game state and communicate snapshots over a named pipe; the desktop app coordinates connection, form-ID mapping, state reconciliation, and serial commands. The app also provides firmware installation. The README documents the end-to-end flow; sampled source confirms app orchestration and firmware-flash entry points, but plugin snapshot internals and most firmware modules were not sampled.

Main entry points: [`CompanionApp/src/app-core.js`](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/app-core.js) (App Orchestrator), [`GamePlugin/src-fo3/main.cpp`](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-fo3/main.cpp) (FO3 Plugin), [`CompanionApp/src/flash-fw.js`](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/flash-fw.js) (Firmware Installer), [`GamePlugin/FOSE/common/IPipeClient.cpp`](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/FOSE/common/IPipeClient.cpp) (Named Pipe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Game Plugins"]
  node_fo3plugin["FO3 Plugin<br/>[main.cpp]"]
  node_nvplugin["New Vegas Plugin<br/>[main.cpp]"]
  node_fo3engine["FO3 Engine Bindings<br/>[fo3_engine.h]"]
  node_gamepipe["Named Pipe<br/>[IPipeClient.cpp]"]
end

subgraph group_desktop["Companion App"]
  node_desktopui["Desktop UI<br/>[main.js]"]
  node_appcore["App Orchestrator<br/>[app-core.js]"]
  node_pipeclient["Pipe Client<br/>[pipe-client.js]"]
  node_mapper["Form ID Mapper<br/>[form-id-mapper.js]"]
  node_sync["Sync Engine<br/>[sync-engine.js]"]
  node_serial["Serial Bridge<br/>[serial-bridge.js]"]
  node_flash["Firmware Installer<br/>[flash-fw.js]"]
end

subgraph group_device["Pip-Boy Device"]
  node_firmware["Device Firmware<br/>[FW-decoded.js]"]
  node_settings["Device Settings"]
end

node_fallout(("Fallout 3 / NV"))
node_device(("Pip-Boy 3000"))

node_fallout -->|"provides game state"| node_fo3plugin
node_fallout -->|"provides game state"| node_nvplugin
node_fo3plugin -->|"uses bindings"| node_fo3engine
node_fo3plugin -->|"sends snapshots"| node_gamepipe
node_nvplugin -->|"sends snapshots"| node_gamepipe
node_gamepipe -->|"transfers JSON"| node_pipeclient
node_desktopui -->|"starts app"| node_appcore
node_desktopui -->|"invokes installer"| node_flash
node_appcore -->|"coordinates connection"| node_pipeclient
node_appcore -->|"processes snapshots"| node_sync
node_appcore -->|"maps device events"| node_mapper
node_appcore -->|"uses bridge"| node_serial
node_sync -->|"updates state"| node_device
node_serial -->|"sends commands"| node_device
node_flash -->|"uses bridge"| node_serial
node_flash -->|"installs firmware"| node_firmware
node_firmware -.->|"includes settings"| node_settings

click node_fo3plugin "https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-fo3/main.cpp"
click node_nvplugin "https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-nv/main.cpp"
click node_fo3engine "https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-fo3/fo3_engine.h"
click node_gamepipe "https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/FOSE/common/IPipeClient.cpp"
click node_desktopui "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/electron/main.js"
click node_appcore "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/app-core.js"
click node_pipeclient "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/pipe-client.js"
click node_mapper "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/form-id-mapper.js"
click node_sync "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/sync-engine.js"
click node_serial "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/serial-bridge.js"
click node_flash "https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/flash-fw.js"
click node_firmware "https://github.com/aidanslab/pipboy3000companion/blob/main/FW/FW-decoded.js"
click node_settings "https://github.com/aidanslab/pipboy3000companion/blob/main/FW/SETTINGS-decoded.js"

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_fo3plugin,node_nvplugin,node_fo3engine,node_gamepipe toneBlue
class node_desktopui,node_appcore,node_pipeclient,node_mapper,node_sync,node_serial,node_flash toneAmber
class node_firmware,node_settings toneMint
class node_fallout,node_device toneIndigo
```

## Components

### Game Plugins

- [FO3 Plugin](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-fo3/main.cpp): `GamePlugin/src-fo3/main.cpp`
- [New Vegas Plugin](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-nv/main.cpp): `GamePlugin/src-nv/main.cpp`
- [FO3 Engine Bindings](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/src-fo3/fo3_engine.h): `GamePlugin/src-fo3/fo3_engine.h`
- [Named Pipe](https://github.com/aidanslab/pipboy3000companion/blob/main/GamePlugin/FOSE/common/IPipeClient.cpp): `GamePlugin/FOSE/common/IPipeClient.cpp`

### Companion App

- [Desktop UI](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/electron/main.js): `CompanionApp/electron/main.js`
- [App Orchestrator](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/app-core.js): `CompanionApp/src/app-core.js`
- [Pipe Client](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/pipe-client.js): `CompanionApp/src/pipe-client.js`
- [Form ID Mapper](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/form-id-mapper.js): `CompanionApp/src/form-id-mapper.js`
- [Sync Engine](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/sync-engine.js): `CompanionApp/src/sync-engine.js`
- [Serial Bridge](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/serial-bridge.js): `CompanionApp/src/serial-bridge.js`
- [Firmware Installer](https://github.com/aidanslab/pipboy3000companion/blob/main/CompanionApp/src/flash-fw.js): `CompanionApp/src/flash-fw.js`

### Pip-Boy Device

- [Device Firmware](https://github.com/aidanslab/pipboy3000companion/blob/main/FW/FW-decoded.js): `FW/FW-decoded.js`
- [Device Settings](https://github.com/aidanslab/pipboy3000companion/blob/main/FW/SETTINGS-decoded.js): `FW/SETTINGS-decoded.js`

### Other components

- **Fallout 3 / NV**
- **Pip-Boy 3000**

## Connections

- Fallout 3 / NV → FO3 Plugin: provides game state
- Fallout 3 / NV → New Vegas Plugin: provides game state
- FO3 Plugin → FO3 Engine Bindings: uses bindings (evidence: `GamePlugin/src-fo3/fo3_engine.h`)
- FO3 Plugin → Named Pipe: sends snapshots
- New Vegas Plugin → Named Pipe: sends snapshots
- Named Pipe → Pipe Client: transfers JSON
- Desktop UI → App Orchestrator: starts app (evidence: `CompanionApp/electron/main.js`)
- Desktop UI → Firmware Installer: invokes installer (evidence: `CompanionApp/electron/main.js`)
- App Orchestrator → Pipe Client: coordinates connection (evidence: `CompanionApp/src/app-core.js`)
- App Orchestrator → Sync Engine: processes snapshots (evidence: `CompanionApp/src/app-core.js`)
- App Orchestrator → Form ID Mapper: maps device events (evidence: `CompanionApp/src/app-core.js`)
- App Orchestrator → Serial Bridge: uses bridge (evidence: `CompanionApp/src/app-core.js`)
- Sync Engine → Pip-Boy 3000: updates state
- Serial Bridge → Pip-Boy 3000: sends commands
- Firmware Installer → Serial Bridge: uses bridge (evidence: `CompanionApp/src/flash-fw.js`)
- Firmware Installer → Device Firmware: installs firmware
- Device Firmware → Device Settings: includes settings