# amonkm/mercator-sync architecture

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

- Interactive diagram: https://gitdiagram.com/amonkm/mercator-sync
- Repository: https://github.com/amonkm/mercator-sync

## Overview

mercator-sync has two product workflows: a modular virtualization-to-Mercator orchestrator and a separate Grist processing-register sync. The first selects enabled sources, collects clusters and VMs, enriches and maps them, then upserts Mercator objects; the second refreshes application mappings and transforms processed Grist sheets into Mercator records. Edges follow shown calls/imports or README descriptions. Some orchestration details and configuration wiring are unsampled, so uncertain links are omitted.

Main entry points: [`sync.py`](https://github.com/amonkm/mercator-sync/blob/main/sync.py) (Sync orchestrator), [`connectors/__init__.py`](https://github.com/amonkm/mercator-sync/blob/main/connectors/__init__.py) (Connector registry), [`Registre-sync/registre_sync.py`](https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/registre_sync.py) (Registry orchestrator), [`connectors/vcenter.py`](https://github.com/amonkm/mercator-sync/blob/main/connectors/vcenter.py) (vCenter connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_virtualization["Virtualization sync"]
  node_sync["Sync orchestrator<br/>[sync.py]"]
  node_source_config["Source configuration<br/>[sources.yaml]"]
end

subgraph group_connectors["Source connectors"]
  node_connector_registry["Connector registry<br/>[__init__.py]"]
  node_connector_base["Connector interface<br/>[base.py]"]
  node_config_types["Config types<br/>[config_types.py]"]
  node_vcenter["vCenter connector<br/>[vcenter.py]"]
  node_xoa["XOA connector<br/>[xoa.py]"]
  node_proxmox["Proxmox connector<br/>[proxmox.py]"]
end

subgraph group_registry["Grist registry sync"]
  node_registry_orchestrator["Registry orchestrator<br/>[registre_sync.py]"]
  node_grist_client["Grist client<br/>[grist_client.py]"]
  node_transform["Payload transform<br/>[transform.py]"]
  node_grist_template["Registry template"]
end

subgraph group_mercator["Mercator integration"]
  node_mercator_client["Mercator client<br/>[sync.py]"]
end

node_operator(("Operator"))
node_vcenter_service(("vCenter"))
node_xoa_service(("XOA"))
node_proxmox_service(("Proxmox"))
node_grist_service(("Grist"))
node_mercator_service(("Mercator"))

node_operator -->|"runs"| node_sync
node_operator -->|"runs"| node_registry_orchestrator
node_sync -->|"loads"| node_source_config
node_sync -->|"selects connector"| node_connector_registry
node_connector_registry -->|"registers"| node_vcenter
node_connector_registry -->|"registers"| node_xoa
node_connector_registry -->|"registers"| node_proxmox
node_vcenter -->|"inherits"| node_connector_base
node_xoa -->|"inherits"| node_connector_base
node_proxmox -->|"inherits"| node_connector_base
node_connector_base -->|"uses types"| node_config_types
node_sync -->|"fetches and maps"| node_vcenter
node_sync -->|"fetches and maps"| node_xoa
node_sync -->|"fetches and maps"| node_proxmox
node_vcenter -->|"calls API"| node_vcenter_service
node_xoa -->|"calls API"| node_xoa_service
node_proxmox -->|"calls API"| node_proxmox_service
node_sync -->|"upserts objects"| node_mercator_client
node_mercator_client -->|"calls API"| node_mercator_service
node_registry_orchestrator -->|"reads and maps"| node_grist_client
node_registry_orchestrator -->|"builds payloads"| node_transform
node_registry_orchestrator -->|"indexes and upserts"| node_mercator_client
node_grist_client -->|"reads and writes"| node_grist_service
node_grist_client -->|"reads applications"| node_mercator_client
node_transform -->|"uses types"| node_config_types
node_grist_service -->|"imports template"| node_grist_template

click node_sync "https://github.com/amonkm/mercator-sync/blob/main/sync.py"
click node_source_config "https://github.com/amonkm/mercator-sync/blob/main/config/sources.yaml"
click node_connector_registry "https://github.com/amonkm/mercator-sync/blob/main/connectors/__init__.py"
click node_connector_base "https://github.com/amonkm/mercator-sync/blob/main/connectors/base.py"
click node_config_types "https://github.com/amonkm/mercator-sync/blob/main/connectors/config_types.py"
click node_vcenter "https://github.com/amonkm/mercator-sync/blob/main/connectors/vcenter.py"
click node_xoa "https://github.com/amonkm/mercator-sync/blob/main/connectors/xoa.py"
click node_proxmox "https://github.com/amonkm/mercator-sync/blob/main/connectors/proxmox.py"
click node_registry_orchestrator "https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/registre_sync.py"
click node_grist_client "https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/grist_client.py"
click node_transform "https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/transform.py"
click node_grist_template "https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/Registres-Protection-des-Donnees-template.grist"
click node_mercator_client "https://github.com/amonkm/mercator-sync/blob/main/sync.py"

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_sync,node_source_config toneBlue
class node_connector_registry,node_connector_base,node_config_types,node_vcenter,node_xoa,node_proxmox toneAmber
class node_registry_orchestrator,node_grist_client,node_transform,node_grist_template toneMint
class node_mercator_client toneRose
class node_operator,node_vcenter_service,node_xoa_service,node_proxmox_service,node_grist_service,node_mercator_service toneIndigo
```

## Components

### Virtualization sync

- [Sync orchestrator](https://github.com/amonkm/mercator-sync/blob/main/sync.py): `sync.py`
- [Source configuration](https://github.com/amonkm/mercator-sync/blob/main/config/sources.yaml): `config/sources.yaml`

### Source connectors

- [Connector registry](https://github.com/amonkm/mercator-sync/blob/main/connectors/__init__.py): `connectors/__init__.py`
- [Connector interface](https://github.com/amonkm/mercator-sync/blob/main/connectors/base.py): `connectors/base.py`
- [Config types](https://github.com/amonkm/mercator-sync/blob/main/connectors/config_types.py): `connectors/config_types.py`
- [vCenter connector](https://github.com/amonkm/mercator-sync/blob/main/connectors/vcenter.py): `connectors/vcenter.py`
- [XOA connector](https://github.com/amonkm/mercator-sync/blob/main/connectors/xoa.py): `connectors/xoa.py`
- [Proxmox connector](https://github.com/amonkm/mercator-sync/blob/main/connectors/proxmox.py): `connectors/proxmox.py`

### Grist registry sync

- [Registry orchestrator](https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/registre_sync.py): `Registre-sync/registre_sync.py`
- [Grist client](https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/grist_client.py): `Registre-sync/grist_client.py`
- [Payload transform](https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/transform.py): `Registre-sync/transform.py`
- [Registry template](https://github.com/amonkm/mercator-sync/blob/main/Registre-sync/Registres-Protection-des-Donnees-template.grist): `Registre-sync/Registres-Protection-des-Donnees-template.grist`

### Mercator integration

- [Mercator client](https://github.com/amonkm/mercator-sync/blob/main/sync.py): `sync.py`

### Other components

- **Operator**
- **vCenter**
- **XOA**
- **Proxmox**
- **Grist**
- **Mercator**

## Connections

- Operator → Sync orchestrator: runs (evidence: `README.md`)
- Operator → Registry orchestrator: runs (evidence: `README.md`)
- Sync orchestrator → Source configuration: loads (evidence: `README.md`)
- Sync orchestrator → Connector registry: selects connector (evidence: `sync.py`)
- Connector registry → vCenter connector: registers (evidence: `connectors/__init__.py`)
- Connector registry → XOA connector: registers (evidence: `connectors/__init__.py`)
- Connector registry → Proxmox connector: registers (evidence: `connectors/__init__.py`)
- vCenter connector → Connector interface: inherits (evidence: `connectors/vcenter.py`)
- XOA connector → Connector interface: inherits (evidence: `connectors/xoa.py`)
- Proxmox connector → Connector interface: inherits (evidence: `connectors/proxmox.py`)
- Connector interface → Config types: uses types (evidence: `connectors/base.py`)
- Sync orchestrator → vCenter connector: fetches and maps (evidence: `sync.py`)
- Sync orchestrator → XOA connector: fetches and maps (evidence: `sync.py`)
- Sync orchestrator → Proxmox connector: fetches and maps (evidence: `sync.py`)
- vCenter connector → vCenter: calls API (evidence: `connectors/vcenter.py`)
- XOA connector → XOA: calls API (evidence: `connectors/xoa.py`)
- Proxmox connector → Proxmox: calls API (evidence: `connectors/proxmox.py`)
- Sync orchestrator → Mercator client: upserts objects (evidence: `sync.py`)
- Mercator client → Mercator: calls API (evidence: `sync.py`)
- Registry orchestrator → Grist client: reads and maps (evidence: `Registre-sync/registre_sync.py`)
- Registry orchestrator → Payload transform: builds payloads (evidence: `Registre-sync/registre_sync.py`)
- Registry orchestrator → Mercator client: indexes and upserts (evidence: `Registre-sync/registre_sync.py`)
- Grist client → Grist: reads and writes (evidence: `Registre-sync/grist_client.py`)
- Grist client → Mercator client: reads applications (evidence: `Registre-sync/grist_client.py`)
- Payload transform → Config types: uses types (evidence: `Registre-sync/transform.py`)
- Grist → Registry template: imports template (evidence: `README.md`)
