# louchi1984-coder/ow-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/louchi1984-coder/ow-bridge
- Repository: https://github.com/louchi1984-coder/ow-bridge

## Overview

OW Bridge is a cross-platform tray application that exposes isolated OpenCode models to WorkBuddy through a local OpenAI-compatible API. The primary workflow is: prepare the runtime, discover and test models, optionally import usable models into WorkBuddy, then translate WorkBuddy chat requests and tool proposals through the gateway. The graph includes the UI, lifecycle/orchestration, request-processing stages, and configuration integrations. README capabilities are included where their source was not sampled; those subsystem paths use the existing enclosing source directory.

Main entry points: [`src/main.js`](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js) (Service orchestrator), [`desktop/main.cjs`](https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/main.cjs) (Desktop lifecycle), [`src/server.js`](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/server.js) (Local API server), [`src/backend.js`](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/backend.js) (Completion backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_desktop_main["Desktop lifecycle<br/>[main.cjs]"]
  node_preload["IPC bridge<br/>[preload.cjs]"]
  node_renderer["Control panel<br/>[renderer.js]"]
  node_activity["Activity display<br/>[activity.cjs]"]
end

subgraph group_orchestration["Service orchestration"]
  node_service["Service orchestrator<br/>[main.js]"]
  node_probe["Model probing<br/>[probe.js]"]
  node_model_status["Model capabilities<br/>[model-status.js]"]
  node_status["Runtime status<br/>[main.js]"]
end

subgraph group_gateway["Model gateway"]
  node_server["Local API server<br/>[server.js]"]
  node_protocol["Request protocol<br/>[protocol.js]"]
  node_backend["Completion backend<br/>[backend.js]"]
  node_handoff["Tool handoff<br/>[handoff.js]"]
  node_repair["Format repair<br/>[repair.js]"]
  node_reasoning["Reasoning mapping<br/>[reasoning.js]"]
end

subgraph group_integrations["Runtime and integrations"]
  node_runtime["Runtime manager<br/>[runtime.js]"]
  node_platform["Platform support<br/>[platform.js]"]
  node_sync["WorkBuddy config sync<br/>[sync.js]"]
  node_workbuddy_config["Config discovery"]
  node_proxy["System proxy<br/>[system-proxy.js]"]
  node_config_store[("Local settings<br/>[main.js]")]
end

node_user(("User"))
node_workbuddy["WorkBuddy"]
node_opencode["OpenCode runtime"]
node_npm["Official npm"]

node_user -->|"uses"| node_desktop_main
node_desktop_main -->|"loads panel"| node_renderer
node_renderer -->|"requests actions"| node_preload
node_preload -->|"invokes IPC"| node_desktop_main
node_desktop_main -->|"starts service"| node_service
node_desktop_main -->|"reads status"| node_status
node_desktop_main -->|"sends admin requests"| node_server
node_desktop_main -->|"formats activity"| node_activity
node_service -->|"finds and starts"| node_runtime
node_runtime -->|"selects package"| node_platform
node_runtime -.->|"downloads runtime"| node_npm
node_runtime -->|"starts isolated server"| node_opencode
node_service -->|"creates API"| node_server
node_service -->|"starts detection"| node_probe
node_service -->|"syncs published models"| node_sync
node_service -->|"resolves config"| node_workbuddy_config
node_service -->|"configures proxy"| node_proxy
node_service -->|"updates"| node_status
node_service -->|"reads and writes"| node_config_store
node_server -->|"validates requests"| node_protocol
node_server -->|"completes chat"| node_backend
node_server -->|"dispatches probe"| node_probe
node_server -->|"dispatches admin actions"| node_service
node_server -->|"serves chat API"| node_workbuddy
node_workbuddy -->|"sends chat requests"| node_server
node_protocol -->|"maps effort"| node_reasoning
node_backend -->|"requests completions and events"| node_opencode
node_backend -->|"validates tool actions"| node_handoff
node_backend -->|"repairs failed output"| node_repair
node_backend -->|"returns tool proposals"| node_workbuddy
node_probe -->|"checks models"| node_opencode
node_probe -->|"records capabilities"| node_model_status
node_service -->|"publishes model state"| node_model_status
node_sync -->|"uses config path"| node_workbuddy_config
node_sync -->|"writes model entries"| node_workbuddy
node_workbuddy -->|"executes proposed tools"| node_handoff
node_service -->|"reads model catalog"| node_opencode
node_service -->|"records request activity"| node_status
node_status -->|"supplies activity state"| node_desktop_main
node_renderer -->|"requests config selection"| node_workbuddy_config

click node_desktop_main "https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/main.cjs"
click node_preload "https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/preload.cjs"
click node_renderer "https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/renderer.js"
click node_activity "https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/activity.cjs"
click node_service "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js"
click node_runtime "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/runtime.js"
click node_platform "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/platform.js"
click node_server "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/server.js"
click node_protocol "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/protocol.js"
click node_backend "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/backend.js"
click node_handoff "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/handoff.js"
click node_repair "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/repair.js"
click node_probe "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/probe.js"
click node_model_status "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/model-status.js"
click node_reasoning "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/reasoning.js"
click node_sync "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/sync.js"
click node_workbuddy_config "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/workbuddy-config.js"
click node_proxy "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/system-proxy.js"
click node_status "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js"
click node_config_store "https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.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_desktop_main,node_preload,node_renderer,node_activity,node_user toneBlue
class node_service,node_probe,node_model_status,node_status toneAmber
class node_server,node_protocol,node_backend,node_handoff,node_repair,node_reasoning toneMint
class node_runtime,node_platform,node_sync,node_workbuddy_config,node_proxy,node_config_store toneRose
class node_workbuddy,node_opencode,node_npm toneIndigo
```

## Components

### Desktop interface

- [Desktop lifecycle](https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/main.cjs): `desktop/main.cjs`
- [IPC bridge](https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/preload.cjs): `desktop/preload.cjs`
- [Control panel](https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/renderer.js): `desktop/renderer.js`
- [Activity display](https://github.com/louchi1984-coder/ow-bridge/blob/main/desktop/activity.cjs): `desktop/activity.cjs`

### Service orchestration

- [Service orchestrator](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js): `src/main.js`
- [Model probing](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/probe.js): `src/probe.js`
- [Model capabilities](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/model-status.js): `src/model-status.js`
- [Runtime status](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js): `src/main.js`

### Model gateway

- [Local API server](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/server.js): `src/server.js`
- [Request protocol](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/protocol.js): `src/protocol.js`
- [Completion backend](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/backend.js): `src/backend.js`
- [Tool handoff](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/handoff.js): `src/handoff.js`
- [Format repair](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/repair.js): `src/repair.js`
- [Reasoning mapping](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/reasoning.js): `src/reasoning.js`

### Runtime and integrations

- [Runtime manager](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/runtime.js): `src/runtime.js`
- [Platform support](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/platform.js): `src/platform.js`
- [WorkBuddy config sync](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/sync.js): `src/sync.js`
- [Config discovery](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/workbuddy-config.js): `src/workbuddy-config.js`
- [System proxy](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/system-proxy.js): `src/system-proxy.js`
- [Local settings](https://github.com/louchi1984-coder/ow-bridge/blob/main/src/main.js): `src/main.js`

### Other components

- **User**
- **WorkBuddy**
- **OpenCode runtime**
- **Official npm**

## Connections

- User → Desktop lifecycle: uses
- Desktop lifecycle → Control panel: loads panel
- Control panel → IPC bridge: requests actions
- IPC bridge → Desktop lifecycle: invokes IPC
- Desktop lifecycle → Service orchestrator: starts service
- Desktop lifecycle → Runtime status: reads status
- Desktop lifecycle → Local API server: sends admin requests
- Desktop lifecycle → Activity display: formats activity
- Service orchestrator → Runtime manager: finds and starts
- Runtime manager → Platform support: selects package
- Runtime manager → Official npm: downloads runtime
- Runtime manager → OpenCode runtime: starts isolated server
- Service orchestrator → Local API server: creates API
- Service orchestrator → Model probing: starts detection
- Service orchestrator → WorkBuddy config sync: syncs published models
- Service orchestrator → Config discovery: resolves config
- Service orchestrator → System proxy: configures proxy
- Service orchestrator → Runtime status: updates
- Service orchestrator → Local settings: reads and writes
- Local API server → Request protocol: validates requests
- Local API server → Completion backend: completes chat
- Local API server → Model probing: dispatches probe
- Local API server → Service orchestrator: dispatches admin actions
- Local API server → WorkBuddy: serves chat API
- WorkBuddy → Local API server: sends chat requests
- Request protocol → Reasoning mapping: maps effort
- Completion backend → OpenCode runtime: requests completions and events
- Completion backend → Tool handoff: validates tool actions
- Completion backend → Format repair: repairs failed output
- Completion backend → WorkBuddy: returns tool proposals
- Model probing → OpenCode runtime: checks models
- Model probing → Model capabilities: records capabilities
- Service orchestrator → Model capabilities: publishes model state
- WorkBuddy config sync → Config discovery: uses config path
- WorkBuddy config sync → WorkBuddy: writes model entries
- WorkBuddy → Tool handoff: executes proposed tools
- Service orchestrator → OpenCode runtime: reads model catalog
- Service orchestrator → Runtime status: records request activity
- Runtime status → Desktop lifecycle: supplies activity state
- Control panel → Config discovery: requests config selection