# johash-dev/branch-sync architecture

> Architecture diagram of the GitHub repository johash-dev/branch-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johash-dev/branch-sync
- Repository: https://github.com/johash-dev/branch-sync

## Overview

Branch Sync Workbench is a local web-and-CLI tool for adapting changes between separately structured source and target repositories. Users bind a pair, scan changes, review assessed porting decisions, create and approve a scoped plan, implement in a target worktree, validate and independently review it, then record integration evidence. The server coordinates provider-backed jobs and the engine owns Git operations, workflow state, and persistence. README documents these capabilities; several internal links below are limited to the sampled imports and excerpts.

Main entry points: [`packages/server/src/app.ts`](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/app.ts) (HTTP API), [`packages/engine/src/workflow.ts`](https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/workflow.ts) (Sync workflow), [`packages/server/src/providers.ts`](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/providers.ts) (Agent providers), [`packages/server/src/setup.ts`](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/setup.ts) (Pair setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_ui["Web workflows<br/>[GapPage.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_cli["CLI commands<br/>[cli.ts]"]
end

subgraph group_coordination["Server coordination"]
  node_server["HTTP API<br/>[app.ts]"]
  node_jobs["Job tracking<br/>[jobs.ts]"]
  node_analysis["Change analysis<br/>[analysis.ts]"]
  node_setup["Pair setup<br/>[setup.ts]"]
end

subgraph group_sync_engine["Sync engine"]
  node_workflow["Sync workflow<br/>[workflow.ts]"]
  node_git_ops["Git operations<br/>[git.ts]"]
  node_schemas["Domain schemas<br/>[schema.ts]"]
end

subgraph group_integrations["Providers and records"]
  node_provider_dispatch["Agent providers<br/>[providers.ts]"]
  node_agent_json["Agent response parsing<br/>[agent-json.ts]"]
  node_cursor_auth["Cursor authentication<br/>[cursor-auth.ts]"]
  node_pair_records[("Shared pair records")]
  node_workbench_records[("Run and workflow records<br/>[store.ts]")]
end

node_user(("Workbench user"))
node_repositories[("Source and target repos")]
node_ai_tools["Coding-agent tools"]

node_user -->|"uses"| node_web_ui
node_user -->|"runs commands"| node_cli
node_web_ui -->|"requests data"| node_web_api
node_web_api -->|"calls API"| node_server
node_cli -->|"uses running server"| node_server
node_server -->|"registers setup"| node_setup
node_server -.->|"tracks jobs"| node_jobs
node_server -->|"invokes analysis"| node_analysis
node_analysis -->|"parses replies"| node_agent_json
node_server -->|"runs agent"| node_provider_dispatch
node_provider_dispatch -->|"resolves Cursor"| node_cursor_auth
node_provider_dispatch -->|"extracts JSON"| node_agent_json
node_provider_dispatch -->|"invokes tool"| node_ai_tools
node_server -.->|"coordinates sync"| node_workflow
node_workflow -->|"calls Git"| node_git_ops
node_workflow -->|"persists workflow"| node_workbench_records
node_workflow -->|"scans and edits"| node_repositories
node_setup -->|"uses pair configs"| node_pair_records
node_setup -->|"saves bindings"| node_workbench_records
node_workbench_records -->|"reads shared records"| node_pair_records
node_workflow -.->|"validates records"| node_schemas
node_user -->|"selects checkouts"| node_repositories

click node_web_ui "https://github.com/johash-dev/branch-sync/blob/main/packages/web/src/GapPage.tsx"
click node_web_api "https://github.com/johash-dev/branch-sync/blob/main/packages/web/src/api.ts"
click node_cli "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/cli.ts"
click node_server "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/app.ts"
click node_jobs "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/jobs.ts"
click node_analysis "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/analysis.ts"
click node_setup "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/setup.ts"
click node_workflow "https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/workflow.ts"
click node_git_ops "https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/git.ts"
click node_schemas "https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/schema.ts"
click node_provider_dispatch "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/providers.ts"
click node_agent_json "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/agent-json.ts"
click node_cursor_auth "https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/cursor-auth.ts"
click node_pair_records "https://github.com/johash-dev/branch-sync/tree/main/data/pairs"
click node_workbench_records "https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/store.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_web_ui,node_web_api,node_cli,node_user toneBlue
class node_server,node_jobs,node_analysis,node_setup,node_repositories toneAmber
class node_workflow,node_git_ops,node_schemas toneMint
class node_provider_dispatch,node_agent_json,node_cursor_auth,node_pair_records,node_workbench_records toneRose
class node_ai_tools toneIndigo
```

## Components

### User experience

- [Web workflows](https://github.com/johash-dev/branch-sync/blob/main/packages/web/src/GapPage.tsx): `packages/web/src/GapPage.tsx`
- [API client](https://github.com/johash-dev/branch-sync/blob/main/packages/web/src/api.ts): `packages/web/src/api.ts`
- [CLI commands](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/cli.ts): `packages/server/src/cli.ts`

### Server coordination

- [HTTP API](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/app.ts): `packages/server/src/app.ts`
- [Job tracking](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/jobs.ts): `packages/server/src/jobs.ts`
- [Change analysis](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/analysis.ts): `packages/server/src/analysis.ts`
- [Pair setup](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/setup.ts): `packages/server/src/setup.ts`

### Sync engine

- [Sync workflow](https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/workflow.ts): `packages/engine/src/workflow.ts`
- [Git operations](https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/git.ts): `packages/engine/src/git.ts`
- [Domain schemas](https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/schema.ts): `packages/engine/src/schema.ts`

### Providers and records

- [Agent providers](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/providers.ts): `packages/server/src/providers.ts`
- [Agent response parsing](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/agent-json.ts): `packages/server/src/agent-json.ts`
- [Cursor authentication](https://github.com/johash-dev/branch-sync/blob/main/packages/server/src/cursor-auth.ts): `packages/server/src/cursor-auth.ts`
- [Shared pair records](https://github.com/johash-dev/branch-sync/tree/main/data/pairs): `data/pairs`
- [Run and workflow records](https://github.com/johash-dev/branch-sync/blob/main/packages/engine/src/store.ts): `packages/engine/src/store.ts`

### Other components

- **Workbench user**
- **Source and target repos**
- **Coding-agent tools**

## Connections

- Workbench user → Web workflows: uses (evidence: `README.md`)
- Workbench user → CLI commands: runs commands (evidence: `README.md`)
- Web workflows → API client: requests data (evidence: `packages/web/src/GapPage.tsx`)
- API client → HTTP API: calls API (evidence: `packages/web/src/api.ts`)
- CLI commands → HTTP API: uses running server (evidence: `README.md`)
- HTTP API → Pair setup: registers setup (evidence: `packages/server/src/app.ts`)
- HTTP API → Job tracking: tracks jobs (evidence: `packages/server/src/app.ts`)
- HTTP API → Change analysis: invokes analysis (evidence: `packages/server/src/app.ts`)
- Change analysis → Agent response parsing: parses replies (evidence: `packages/server/src/analysis.ts`)
- HTTP API → Agent providers: runs agent (evidence: `packages/server/src/app.ts`)
- Agent providers → Cursor authentication: resolves Cursor (evidence: `packages/server/src/providers.ts`)
- Agent providers → Agent response parsing: extracts JSON (evidence: `packages/server/src/providers.ts`)
- Agent providers → Coding-agent tools: invokes tool (evidence: `README.md`)
- HTTP API → Sync workflow: coordinates sync
- Sync workflow → Git operations: calls Git (evidence: `packages/engine/src/workflow.ts`)
- Sync workflow → Run and workflow records: persists workflow (evidence: `packages/engine/src/workflow.ts`)
- Sync workflow → Source and target repos: scans and edits (evidence: `README.md`)
- Pair setup → Shared pair records: uses pair configs (evidence: `README.md`)
- Pair setup → Run and workflow records: saves bindings (evidence: `README.md`)
- Run and workflow records → Shared pair records: reads shared records (evidence: `packages/engine/src/store.ts`)
- Sync workflow → Domain schemas: validates records (evidence: `packages/engine/src/workflow.ts`)
- Workbench user → Source and target repos: selects checkouts (evidence: `README.md`)
