# gburd/isync architecture

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

## Overview

mbsync is a command-line mailbox synchronizer, with isync retained as a compatibility wrapper. The principal workflow is to select channels and operations, open corresponding IMAP or Maildir mailboxes, reconcile message UIDs, flags and deletions, and persist per-pair synchronization state. The README also documents mailbox collections, partial mirrors, trashing, IMAP security and authentication capabilities, and disconnected operation. The excerpts show orchestration, synchronization, protocol and local-store responsibilities; some indirect driver and configuration wiring is not shown, so uncertain links are omitted or marked unverified.

Main entry points: [`src/main.c`](https://github.com/gburd/isync/blob/master/src/main.c) (mbsync orchestration), [`src/compat/main.c`](https://github.com/gburd/isync/blob/master/src/compat/main.c) (isync wrapper), [`src/sync.c`](https://github.com/gburd/isync/blob/master/src/sync.c) (Sync engine), [`src/drv_imap.c`](https://github.com/gburd/isync/blob/master/src/drv_imap.c) (IMAP driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_mbsync["mbsync orchestration<br/>[main.c]"]
  node_config["Channel configuration<br/>[config.c]"]
end

subgraph group_sync["Synchronization"]
  node_engine["Sync engine<br/>[sync.c]"]
  node_state[("Pair state and journal<br/>[sync.c]")]
end

subgraph group_stores["Mailbox stores"]
  node_imap["IMAP driver<br/>[drv_imap.c]"]
  node_maildir["Maildir driver<br/>[drv_maildir.c]"]
end

subgraph group_transport["IMAP transport"]
  node_socket["Socket and TLS<br/>[socket.c]"]
  node_runtime["Runtime utilities<br/>[util.c]"]
end

subgraph group_compat["Compatibility tools"]
  node_compatcli["isync wrapper<br/>[main.c]"]
  node_compatconfig["Legacy configuration<br/>[config.c]"]
  node_convert["Maildir conversion<br/>[convert.c]"]
  node_compatutil["Legacy utilities<br/>[util.c]"]
  node_mdconvert["State conversion tool<br/>[mdconvert.c]"]
end

node_cli(("CLI user"))
node_imapserver(("IMAP server"))
node_localmail[("Local Maildir")]

node_cli -->|"invokes"| node_mbsync
node_mbsync -->|"starts sync"| node_engine
node_mbsync -.->|"loads config"| node_config
node_engine -->|"writes state"| node_state
node_engine -.->|"uses store"| node_imap
node_engine -.->|"uses store"| node_maildir
node_imap -.->|"exchanges IMAP"| node_imapserver
node_maildir -.->|"reads and writes"| node_localmail
node_imap -.->|"uses transport"| node_socket
node_socket -.->|"connects securely"| node_imapserver
node_mbsync -.->|"executes wrapper target"| node_compatcli
node_compatcli -.->|"loads legacy config"| node_compatconfig
node_compatcli -->|"converts mailboxes"| node_convert
node_compatcli -->|"executes"| node_mbsync
node_convert -->|"reads and updates"| node_localmail
node_mdconvert -.->|"converts state"| node_state
node_compatcli -.->|"uses helpers"| node_compatutil
node_mbsync -.->|"uses utilities"| node_runtime

click node_mbsync "https://github.com/gburd/isync/blob/master/src/main.c"
click node_config "https://github.com/gburd/isync/blob/master/src/config.c"
click node_engine "https://github.com/gburd/isync/blob/master/src/sync.c"
click node_state "https://github.com/gburd/isync/blob/master/src/sync.c"
click node_imap "https://github.com/gburd/isync/blob/master/src/drv_imap.c"
click node_maildir "https://github.com/gburd/isync/blob/master/src/drv_maildir.c"
click node_socket "https://github.com/gburd/isync/blob/master/src/socket.c"
click node_runtime "https://github.com/gburd/isync/blob/master/src/util.c"
click node_compatcli "https://github.com/gburd/isync/blob/master/src/compat/main.c"
click node_compatconfig "https://github.com/gburd/isync/blob/master/src/compat/config.c"
click node_convert "https://github.com/gburd/isync/blob/master/src/compat/convert.c"
click node_compatutil "https://github.com/gburd/isync/blob/master/src/compat/util.c"
click node_mdconvert "https://github.com/gburd/isync/blob/master/src/mdconvert.c"

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_mbsync,node_config,node_cli toneBlue
class node_engine,node_state,node_localmail toneAmber
class node_imap,node_maildir,node_imapserver toneMint
class node_socket,node_runtime toneRose
class node_compatcli,node_compatconfig,node_convert,node_compatutil,node_mdconvert toneIndigo
```

## Components

### Entry and configuration

- [mbsync orchestration](https://github.com/gburd/isync/blob/master/src/main.c): `src/main.c`
- [Channel configuration](https://github.com/gburd/isync/blob/master/src/config.c): `src/config.c`

### Synchronization

- [Sync engine](https://github.com/gburd/isync/blob/master/src/sync.c): `src/sync.c`
- [Pair state and journal](https://github.com/gburd/isync/blob/master/src/sync.c): `src/sync.c`

### Mailbox stores

- [IMAP driver](https://github.com/gburd/isync/blob/master/src/drv_imap.c): `src/drv_imap.c`
- [Maildir driver](https://github.com/gburd/isync/blob/master/src/drv_maildir.c): `src/drv_maildir.c`

### IMAP transport

- [Socket and TLS](https://github.com/gburd/isync/blob/master/src/socket.c): `src/socket.c`
- [Runtime utilities](https://github.com/gburd/isync/blob/master/src/util.c): `src/util.c`

### Compatibility tools

- [isync wrapper](https://github.com/gburd/isync/blob/master/src/compat/main.c): `src/compat/main.c`
- [Legacy configuration](https://github.com/gburd/isync/blob/master/src/compat/config.c): `src/compat/config.c`
- [Maildir conversion](https://github.com/gburd/isync/blob/master/src/compat/convert.c): `src/compat/convert.c`
- [Legacy utilities](https://github.com/gburd/isync/blob/master/src/compat/util.c): `src/compat/util.c`
- [State conversion tool](https://github.com/gburd/isync/blob/master/src/mdconvert.c): `src/mdconvert.c`

### Other components

- **CLI user**
- **IMAP server**
- **Local Maildir**

## Connections

- CLI user → mbsync orchestration: invokes (evidence: `README`)
- mbsync orchestration → Sync engine: starts sync (evidence: `src/main.c`)
- mbsync orchestration → Channel configuration: loads config
- Sync engine → Pair state and journal: writes state (evidence: `src/sync.c`)
- Sync engine → IMAP driver: uses store
- Sync engine → Maildir driver: uses store
- IMAP driver → IMAP server: exchanges IMAP
- Maildir driver → Local Maildir: reads and writes
- IMAP driver → Socket and TLS: uses transport
- Socket and TLS → IMAP server: connects securely
- mbsync orchestration → isync wrapper: executes wrapper target
- isync wrapper → Legacy configuration: loads legacy config
- isync wrapper → Maildir conversion: converts mailboxes (evidence: `src/compat/main.c`)
- isync wrapper → mbsync orchestration: executes (evidence: `src/compat/main.c`)
- Maildir conversion → Local Maildir: reads and updates (evidence: `src/compat/convert.c`)
- State conversion tool → Pair state and journal: converts state
- isync wrapper → Legacy utilities: uses helpers
- mbsync orchestration → Runtime utilities: uses utilities
