# yandex/mysync architecture

> Architecture diagram of the GitHub repository yandex/mysync, 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/yandex/mysync
- Repository: https://github.com/yandex/mysync

## Overview

MySync coordinates high availability for homogeneous MySQL clusters, using ZooKeeper for shared state and locks. The main workflow is to run the agent, monitor cluster health and replication, then coordinate failover or an operator-requested switchover; operators can also inspect hosts and control maintenance. The graph includes replication repair and replica optimization as distinct operational stages. Relationships are limited to README statements and source references shown in the supplied excerpts and index; some subsystem details are unsampled.

Main entry points: [`internal/app/app.go`](https://github.com/yandex/mysync/blob/master/internal/app/app.go) (Agent and workflow), [`internal/app/dcs/optimization.go`](https://github.com/yandex/mysync/blob/master/internal/app/dcs/optimization.go) (Optimization DCS adapter), [`internal/mysql/cluster.go`](https://github.com/yandex/mysync/blob/master/internal/mysql/cluster.go) (MySQL cluster), [`internal/app/app_dcs_impl.go`](https://github.com/yandex/mysync/blob/master/internal/app/app_dcs_impl.go) (DCS integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Operator interface"]
  node_agent["MySync agent<br/>[main.go]"]
  node_host_cli["Host commands<br/>[cli_host.go]"]
  node_switch_cli["Switch commands<br/>[cli_switch.go]"]
  node_maintenance_cli["Maintenance commands<br/>[maintenance.go]"]
  node_info_cli["Info commands<br/>[cli_info.go]"]
end

subgraph group_coordination["Cluster coordination"]
  node_app["Agent and workflow<br/>[app.go]"]
  node_app_dcs["Cluster state exchange<br/>[app_dcs.go]"]
  node_app_dcs_impl["DCS integration<br/>[app_dcs_impl.go]"]
  node_node_state["Node state model<br/>[node_state.go]"]
  node_configuration["Configuration<br/>[config.go]"]
end

subgraph group_replication["Replication management"]
  node_replication_workflows["Repair and switchover<br/>[replication.go]"]
  node_optimization["Replica optimization<br/>[controller.go]"]
  node_optimization_adapter["Optimization DCS adapter<br/>[optimization.go]"]
end

subgraph group_infrastructure["Cluster infrastructure"]
  node_mysql_cluster["MySQL cluster<br/>[cluster.go]"]
  node_mysql_node["MySQL node operations<br/>[node.go]"]
  node_mysql_replication["Replication operations<br/>[replication.go]"]
  node_zookeeper[("ZooKeeper DCS<br/>[zk.go]")]
end

node_operator(("Operator"))
node_zookeeper_service[("ZooKeeper")]
node_mysql_service[("MySQL cluster nodes")]

node_operator -->|"starts"| node_agent
node_agent -->|"creates and runs"| node_app
node_operator -->|"manages hosts"| node_host_cli
node_operator -->|"requests switch"| node_switch_cli
node_operator -->|"sets maintenance"| node_maintenance_cli
node_operator -.->|"requests status"| node_info_cli
node_host_cli -->|"manages hosts"| node_mysql_cluster
node_app -->|"uses settings"| node_configuration
node_app -->|"coordinates cluster"| node_mysql_cluster
node_app -->|"evaluates state"| node_node_state
node_app -->|"exchanges state"| node_app_dcs
node_app -->|"uses DCS integration"| node_app_dcs_impl
node_app -->|"coordinates repair"| node_replication_workflows
node_app -->|"controls optimization"| node_optimization
node_app_dcs -->|"uses state model"| node_node_state
node_app_dcs_impl -->|"uses DCS"| node_zookeeper
node_app_dcs_impl -->|"uses settings"| node_configuration
node_optimization -->|"reads optimization state"| node_optimization_adapter
node_optimization_adapter -->|"gets cluster nodes"| node_mysql_cluster
node_optimization_adapter -->|"reads node state"| node_node_state
node_optimization_adapter -->|"reads and writes DCS"| node_zookeeper
node_replication_workflows -->|"repairs replication"| node_mysql_node
node_replication_workflows -->|"enables optimization"| node_optimization
node_mysql_cluster -->|"manages nodes"| node_mysql_node
node_mysql_node -.->|"queries and controls"| node_mysql_service
node_mysql_replication -.->|"controls replication"| node_mysql_service
node_zookeeper -.->|"stores cluster state"| node_zookeeper_service

click node_agent "https://github.com/yandex/mysync/blob/master/cmd/mysync/main.go"
click node_host_cli "https://github.com/yandex/mysync/blob/master/internal/app/cli_host.go"
click node_switch_cli "https://github.com/yandex/mysync/blob/master/internal/app/cli_switch.go"
click node_maintenance_cli "https://github.com/yandex/mysync/blob/master/cmd/mysync/maintenance.go"
click node_info_cli "https://github.com/yandex/mysync/blob/master/internal/app/cli_info.go"
click node_app "https://github.com/yandex/mysync/blob/master/internal/app/app.go"
click node_app_dcs "https://github.com/yandex/mysync/blob/master/internal/app/app_dcs.go"
click node_app_dcs_impl "https://github.com/yandex/mysync/blob/master/internal/app/app_dcs_impl.go"
click node_node_state "https://github.com/yandex/mysync/blob/master/internal/app/node_state/node_state.go"
click node_configuration "https://github.com/yandex/mysync/blob/master/internal/config/config.go"
click node_replication_workflows "https://github.com/yandex/mysync/blob/master/internal/app/replication.go"
click node_optimization "https://github.com/yandex/mysync/blob/master/internal/app/optimization/controller.go"
click node_optimization_adapter "https://github.com/yandex/mysync/blob/master/internal/app/dcs/optimization.go"
click node_mysql_cluster "https://github.com/yandex/mysync/blob/master/internal/mysql/cluster.go"
click node_mysql_node "https://github.com/yandex/mysync/blob/master/internal/mysql/node.go"
click node_mysql_replication "https://github.com/yandex/mysync/blob/master/internal/mysql/replication.go"
click node_zookeeper "https://github.com/yandex/mysync/blob/master/internal/dcs/zk.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_agent,node_host_cli,node_switch_cli,node_maintenance_cli,node_info_cli toneBlue
class node_app,node_app_dcs,node_app_dcs_impl,node_node_state,node_configuration,node_zookeeper_service,node_mysql_service toneAmber
class node_replication_workflows,node_optimization,node_optimization_adapter toneMint
class node_mysql_cluster,node_mysql_node,node_mysql_replication,node_zookeeper toneRose
class node_operator toneIndigo
```

## Components

### Operator interface

- [MySync agent](https://github.com/yandex/mysync/blob/master/cmd/mysync/main.go): `cmd/mysync/main.go`
- [Host commands](https://github.com/yandex/mysync/blob/master/internal/app/cli_host.go): `internal/app/cli_host.go`
- [Switch commands](https://github.com/yandex/mysync/blob/master/internal/app/cli_switch.go): `internal/app/cli_switch.go`
- [Maintenance commands](https://github.com/yandex/mysync/blob/master/cmd/mysync/maintenance.go): `cmd/mysync/maintenance.go`
- [Info commands](https://github.com/yandex/mysync/blob/master/internal/app/cli_info.go): `internal/app/cli_info.go`

### Cluster coordination

- [Agent and workflow](https://github.com/yandex/mysync/blob/master/internal/app/app.go): `internal/app/app.go`
- [Cluster state exchange](https://github.com/yandex/mysync/blob/master/internal/app/app_dcs.go): `internal/app/app_dcs.go`
- [DCS integration](https://github.com/yandex/mysync/blob/master/internal/app/app_dcs_impl.go): `internal/app/app_dcs_impl.go`
- [Node state model](https://github.com/yandex/mysync/blob/master/internal/app/node_state/node_state.go): `internal/app/node_state/node_state.go`
- [Configuration](https://github.com/yandex/mysync/blob/master/internal/config/config.go): `internal/config/config.go`

### Replication management

- [Repair and switchover](https://github.com/yandex/mysync/blob/master/internal/app/replication.go): `internal/app/replication.go`
- [Replica optimization](https://github.com/yandex/mysync/blob/master/internal/app/optimization/controller.go): `internal/app/optimization/controller.go`
- [Optimization DCS adapter](https://github.com/yandex/mysync/blob/master/internal/app/dcs/optimization.go): `internal/app/dcs/optimization.go`

### Cluster infrastructure

- [MySQL cluster](https://github.com/yandex/mysync/blob/master/internal/mysql/cluster.go): `internal/mysql/cluster.go`
- [MySQL node operations](https://github.com/yandex/mysync/blob/master/internal/mysql/node.go): `internal/mysql/node.go`
- [Replication operations](https://github.com/yandex/mysync/blob/master/internal/mysql/replication.go): `internal/mysql/replication.go`
- [ZooKeeper DCS](https://github.com/yandex/mysync/blob/master/internal/dcs/zk.go): `internal/dcs/zk.go`

### Other components

- **Operator**
- **ZooKeeper**
- **MySQL cluster nodes**

## Connections

- Operator → MySync agent: starts (evidence: `cmd/mysync/main.go`)
- MySync agent → Agent and workflow: creates and runs (evidence: `cmd/mysync/main.go`)
- Operator → Host commands: manages hosts
- Operator → Switch commands: requests switch
- Operator → Maintenance commands: sets maintenance (evidence: `cmd/mysync/maintenance.go`)
- Operator → Info commands: requests status
- Host commands → MySQL cluster: manages hosts (evidence: `internal/app/cli_host.go`)
- Agent and workflow → Configuration: uses settings (evidence: `internal/app/app.go`)
- Agent and workflow → MySQL cluster: coordinates cluster (evidence: `internal/app/app.go`)
- Agent and workflow → Node state model: evaluates state (evidence: `internal/app/app.go`)
- Agent and workflow → Cluster state exchange: exchanges state (evidence: `internal/app/app.go`)
- Agent and workflow → DCS integration: uses DCS integration (evidence: `internal/app/app.go`)
- Agent and workflow → Repair and switchover: coordinates repair (evidence: `internal/app/app.go`)
- Agent and workflow → Replica optimization: controls optimization (evidence: `internal/app/app.go`)
- Cluster state exchange → Node state model: uses state model (evidence: `internal/app/app_dcs.go`)
- DCS integration → ZooKeeper DCS: uses DCS (evidence: `internal/app/app_dcs_impl.go`)
- DCS integration → Configuration: uses settings (evidence: `internal/app/app_dcs_impl.go`)
- Replica optimization → Optimization DCS adapter: reads optimization state (evidence: `internal/app/optimization/controller.go`)
- Optimization DCS adapter → MySQL cluster: gets cluster nodes (evidence: `internal/app/dcs/optimization.go`)
- Optimization DCS adapter → Node state model: reads node state (evidence: `internal/app/dcs/optimization.go`)
- Optimization DCS adapter → ZooKeeper DCS: reads and writes DCS (evidence: `internal/app/dcs/optimization.go`)
- Repair and switchover → MySQL node operations: repairs replication (evidence: `internal/app/replication.go`)
- Repair and switchover → Replica optimization: enables optimization (evidence: `internal/app/replication.go`)
- MySQL cluster → MySQL node operations: manages nodes (evidence: `internal/mysql/cluster.go`)
- MySQL node operations → MySQL cluster nodes: queries and controls
- Replication operations → MySQL cluster nodes: controls replication
- ZooKeeper DCS → ZooKeeper: stores cluster state
