# ir-interactive-studios/syncforge architecture

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

- Interactive diagram: https://gitdiagram.com/ir-interactive-studios/syncforge
- Repository: https://github.com/ir-interactive-studios/syncforge

## Overview

SyncForge coordinates developers working in isolated Git worktrees: developers create workspaces, observers report Git-derived activity to a coordinator, and the coordinator exposes presence, tasks, focus, and overlap warnings. The broader product adds checkpoints and guarded integration, local hunk/symbol analysis, remote collaboration, optional Docker execution and consent-gated AI conflict advice, plus diagnostics. The coordinator is the main orchestration layer. Some subsystem links reflect README capabilities because their implementations were not excerpted; those links are dashed where runtime wiring is unverified.

Main entry points: [`apps/coordinator/src/server.ts`](https://github.com/ir-interactive-studios/syncforge/blob/main/apps/coordinator/src/server.ts) (Coordinator service), [`packages/storage/src/store.ts`](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/storage/src/store.ts) (SQLite project state), [`packages/agent/src/observer.ts`](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/agent/src/observer.ts) (Workspace observer), [`packages/git/src/git.ts`](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/git/src/git.ts) (Git operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user["Developer workflow"]
  node_cli["CLI commands<br/>[index.ts]"]
  node_observer["Workspace observer<br/>[observer.ts]"]
end

subgraph group_coord["Coordination"]
  node_coordinator["Coordinator service<br/>[server.ts]"]
  node_protocol["Command protocol<br/>[index.ts]"]
end

subgraph group_gitflow["Git collaboration"]
  node_workspace["Worktree management<br/>[workspaces.ts]"]
  node_git["Git operations<br/>[git.ts]"]
  node_checkpoint["Checkpoints<br/>[checkpoints.ts]"]
  node_integration["Integration workflow<br/>[integration.ts]"]
end

subgraph group_analysis["Change analysis"]
  node_conflicts["Conflict classification<br/>[conflicts.ts]"]
  node_hunks["Hunk analysis<br/>[hunks.ts]"]
  node_symbols["Symbol analysis<br/>[symbols.ts]"]
  node_aiadvisor["AI conflict advice<br/>[advisor.ts]"]
  node_aicontext["Candidate context<br/>[context.ts]"]
  node_aiprovider["AI provider<br/>[provider.ts]"]
end

subgraph group_support["Runtime and state"]
  node_runtime["Docker workspace runtime"]
  node_store[("SQLite project state<br/>[store.ts]")]
  node_paths["Path safety<br/>[paths.ts]"]
  node_project["Project setup<br/>[project.ts]"]
  node_logger["Structured logging<br/>[logger.ts]"]
end

node_developer(("Developer"))
node_gitremote[("Shared Git remote")]
node_docker["Docker engine"]
node_aiendpoint["AI endpoint"]

node_developer -->|"runs commands"| node_cli
node_cli -->|"creates worktrees"| node_workspace
node_cli -->|"starts observer"| node_observer
node_observer -->|"reads Git activity"| node_git
node_observer -->|"reports activity"| node_coordinator
node_observer -->|"updates activity"| node_store
node_observer -->|"validates messages"| node_protocol
node_coordinator -->|"handles commands"| node_protocol
node_coordinator -->|"adds workspaces"| node_workspace
node_coordinator -->|"creates checkpoints"| node_checkpoint
node_coordinator -->|"orchestrates integration"| node_integration
node_coordinator -->|"requests analysis"| node_hunks
node_coordinator -->|"requests analysis"| node_symbols
node_coordinator -->|"classifies overlap"| node_conflicts
node_coordinator -->|"manages runtime"| node_runtime
node_coordinator -->|"reads and writes"| node_store
node_workspace -->|"creates worktrees"| node_git
node_workspace -->|"registers workspace"| node_store
node_checkpoint -->|"records commits"| node_git
node_checkpoint -->|"stores history"| node_store
node_integration -->|"merges candidates"| node_git
node_integration -->|"stores operations"| node_store
node_hunks -->|"reads diffs"| node_git
node_hunks -->|"provides hunk results"| node_symbols
node_coordinator -->|"requests advice"| node_aiadvisor
node_aiadvisor -->|"builds context"| node_aicontext
node_aiadvisor -->|"requests completion"| node_aiprovider
node_aicontext -->|"checks candidate"| node_git
node_aicontext -->|"reads operation"| node_store
node_aiprovider -->|"sends request"| node_aiendpoint
node_runtime -->|"runs containers"| node_docker
node_runtime -->|"uses workspace state"| node_store
node_cli -->|"initializes project"| node_project
node_project -->|"inspects repository"| node_git
node_project -->|"initializes state"| node_store
node_cli -.->|"pairs remote clone"| node_gitremote
node_coordinator -.->|"supports remote collaboration"| node_gitremote
node_coordinator -->|"writes structured logs"| node_logger
node_observer -->|"normalizes activity paths"| node_paths
node_hunks -->|"validates paths"| node_paths
node_aicontext -->|"restricts source paths"| node_paths

click node_cli "https://github.com/ir-interactive-studios/syncforge/blob/main/apps/cli/src/index.ts"
click node_observer "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/agent/src/observer.ts"
click node_coordinator "https://github.com/ir-interactive-studios/syncforge/blob/main/apps/coordinator/src/server.ts"
click node_protocol "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/protocol/src/index.ts"
click node_workspace "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/git/src/workspaces.ts"
click node_git "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/git/src/git.ts"
click node_checkpoint "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/checkpoints.ts"
click node_integration "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/integration.ts"
click node_conflicts "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/conflicts.ts"
click node_hunks "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/hunks.ts"
click node_symbols "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/symbols.ts"
click node_aiadvisor "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/advisor.ts"
click node_aicontext "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/context.ts"
click node_aiprovider "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/provider.ts"
click node_runtime "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/runtime/src/workspace-runtime.ts"
click node_store "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/storage/src/store.ts"
click node_paths "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/paths.ts"
click node_project "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/project.ts"
click node_logger "https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/logger.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_cli,node_observer toneBlue
class node_coordinator,node_protocol,node_gitremote toneAmber
class node_workspace,node_git,node_checkpoint,node_integration toneMint
class node_conflicts,node_hunks,node_symbols,node_aiadvisor,node_aicontext,node_aiprovider toneRose
class node_runtime,node_store,node_paths,node_project,node_logger,node_developer,node_docker,node_aiendpoint toneIndigo
```

## Components

### Developer workflow

- [CLI commands](https://github.com/ir-interactive-studios/syncforge/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [Workspace observer](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/agent/src/observer.ts): `packages/agent/src/observer.ts`

### Coordination

- [Coordinator service](https://github.com/ir-interactive-studios/syncforge/blob/main/apps/coordinator/src/server.ts): `apps/coordinator/src/server.ts`
- [Command protocol](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/protocol/src/index.ts): `packages/protocol/src/index.ts`

### Git collaboration

- [Worktree management](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/git/src/workspaces.ts): `packages/git/src/workspaces.ts`
- [Git operations](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/git/src/git.ts): `packages/git/src/git.ts`
- [Checkpoints](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/checkpoints.ts): `packages/core/src/checkpoints.ts`
- [Integration workflow](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/integration.ts): `packages/core/src/integration.ts`

### Change analysis

- [Conflict classification](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/conflicts.ts): `packages/core/src/conflicts.ts`
- [Hunk analysis](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/hunks.ts): `packages/core/src/hunks.ts`
- [Symbol analysis](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/symbols.ts): `packages/core/src/symbols.ts`
- [AI conflict advice](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/advisor.ts): `packages/ai/src/advisor.ts`
- [Candidate context](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/context.ts): `packages/ai/src/context.ts`
- [AI provider](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/ai/src/provider.ts): `packages/ai/src/provider.ts`

### Runtime and state

- [Docker workspace runtime](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/runtime/src/workspace-runtime.ts): `packages/runtime/src/workspace-runtime.ts`
- [SQLite project state](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/storage/src/store.ts): `packages/storage/src/store.ts`
- [Path safety](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/paths.ts): `packages/core/src/paths.ts`
- [Project setup](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/project.ts): `packages/core/src/project.ts`
- [Structured logging](https://github.com/ir-interactive-studios/syncforge/blob/main/packages/core/src/logger.ts): `packages/core/src/logger.ts`

### Other components

- **Developer**
- **Shared Git remote**
- **Docker engine**
- **AI endpoint**

## Connections

- Developer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Worktree management: creates worktrees (evidence: `apps/cli/src/index.ts`)
- CLI commands → Workspace observer: starts observer (evidence: `apps/cli/src/index.ts`)
- Workspace observer → Git operations: reads Git activity (evidence: `packages/agent/src/observer.ts`)
- Workspace observer → Coordinator service: reports activity (evidence: `README.md`)
- Workspace observer → SQLite project state: updates activity (evidence: `packages/agent/src/observer.ts`)
- Workspace observer → Command protocol: validates messages (evidence: `packages/agent/src/observer.ts`)
- Coordinator service → Command protocol: handles commands (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Worktree management: adds workspaces (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Checkpoints: creates checkpoints (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Integration workflow: orchestrates integration (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Hunk analysis: requests analysis (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Symbol analysis: requests analysis (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Conflict classification: classifies overlap (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → Docker workspace runtime: manages runtime (evidence: `apps/coordinator/src/server.ts`)
- Coordinator service → SQLite project state: reads and writes (evidence: `apps/coordinator/src/server.ts`)
- Worktree management → Git operations: creates worktrees (evidence: `packages/git/src/workspaces.ts`)
- Worktree management → SQLite project state: registers workspace (evidence: `packages/git/src/workspaces.ts`)
- Checkpoints → Git operations: records commits (evidence: `packages/core/src/checkpoints.ts`)
- Checkpoints → SQLite project state: stores history (evidence: `packages/core/src/checkpoints.ts`)
- Integration workflow → Git operations: merges candidates (evidence: `packages/core/src/integration.ts`)
- Integration workflow → SQLite project state: stores operations (evidence: `packages/core/src/integration.ts`)
- Hunk analysis → Git operations: reads diffs (evidence: `packages/core/src/hunks.ts`)
- Hunk analysis → Symbol analysis: provides hunk results (evidence: `packages/core/src/symbols.ts`)
- Coordinator service → AI conflict advice: requests advice (evidence: `apps/coordinator/src/server.ts`)
- AI conflict advice → Candidate context: builds context (evidence: `packages/ai/src/advisor.ts`)
- AI conflict advice → AI provider: requests completion (evidence: `packages/ai/src/advisor.ts`)
- Candidate context → Git operations: checks candidate (evidence: `packages/ai/src/context.ts`)
- Candidate context → SQLite project state: reads operation (evidence: `packages/ai/src/context.ts`)
- AI provider → AI endpoint: sends request (evidence: `packages/ai/src/provider.ts`)
- Docker workspace runtime → Docker engine: runs containers (evidence: `packages/runtime/src/workspace-runtime.ts`)
- Docker workspace runtime → SQLite project state: uses workspace state (evidence: `packages/runtime/src/workspace-runtime.ts`)
- CLI commands → Project setup: initializes project (evidence: `apps/cli/src/index.ts`)
- Project setup → Git operations: inspects repository (evidence: `packages/core/src/project.ts`)
- Project setup → SQLite project state: initializes state (evidence: `packages/core/src/project.ts`)
- CLI commands → Shared Git remote: pairs remote clone (evidence: `README.md`)
- Coordinator service → Shared Git remote: supports remote collaboration (evidence: `README.md`)
- Coordinator service → Structured logging: writes structured logs (evidence: `apps/coordinator/src/server.ts`)
- Workspace observer → Path safety: normalizes activity paths (evidence: `packages/agent/src/observer.ts`)
- Hunk analysis → Path safety: validates paths (evidence: `packages/core/src/hunks.ts`)
- Candidate context → Path safety: restricts source paths (evidence: `packages/ai/src/context.ts`)
