# t3nsor27/file-sync architecture

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

- Interactive diagram: https://gitdiagram.com/t3nsor27/file-sync
- Repository: https://github.com/t3nsor27/file-sync

## Overview

file-sync is a terminal-based LAN peer-to-peer synchronizer. The main workflow is: choose a peer, exchange filesystem trees, compare them, then pull the peer’s changes and show transfer progress. Tree construction and hashing, diffing, sync operation handling, and filesystem updates are distinct stages. Peer owns connection lifecycle; Session implements asynchronous packet transport, while wire provides binary primitives. The README documents the broader sync protocol; sampled excerpts do not show all handler wiring, so uncertain call paths are omitted.

Main entry points: [`main.cpp`](https://github.com/t3nsor27/file-sync/blob/main/main.cpp) (TUI and sync), [`src/peer.cpp`](https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp) (Session transport), [`src/fstree.cpp`](https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp) (Directory tree), [`src/wire.cpp`](https://github.com/t3nsor27/file-sync/blob/main/src/wire.cpp) (Binary primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["UI and orchestration"]
  node_main["TUI and sync<br/>[main.cpp]"]
  node_apply["Sync apply<br/>[main.cpp]"]
  node_progress["Transfer progress<br/>[main.cpp]"]
end

subgraph group_tree["Filesystem model"]
  node_tree["Directory tree<br/>[fstree.cpp]"]
  node_hash["SHA-256 hashing<br/>[fstree.cpp]"]
  node_diff["Tree diff<br/>[fstree.cpp]"]
  node_serialize["Tree serialization<br/>[fstree.cpp]"]
end

subgraph group_network["Peer networking"]
  node_peer["Peer lifecycle<br/>[peer.cpp]"]
  node_session["Session transport<br/>[peer.cpp]"]
end

subgraph group_protocol["Wire protocol"]
  node_packet["Packet framing<br/>[peer.cpp]"]
  node_wire["Binary primitives<br/>[wire.cpp]"]
end

node_user(("Operator"))
node_localfs["Local directory"]
node_remote(("Remote peer"))

node_user -->|"selects peer"| node_main
node_main -->|"starts listener"| node_peer
node_main -->|"requests connection"| node_peer
node_peer -->|"connects TCP"| node_remote
node_remote -->|"opens TCP"| node_peer
node_peer -->|"creates session"| node_session
node_main -->|"builds local tree"| node_tree
node_tree -->|"reads directory"| node_localfs
node_tree -->|"hashes files"| node_hash
node_main -->|"exchanges trees"| node_session
node_session -->|"serializes trees"| node_serialize
node_session -->|"frames messages"| node_packet
node_packet -->|"encodes fields"| node_wire
node_session -->|"sends and receives"| node_remote
node_main -->|"compares trees"| node_diff
node_main -->|"requests sync"| node_session
node_main -->|"handles sync packets"| node_apply
node_apply -->|"creates and deletes"| node_localfs
node_apply -->|"receives file data"| node_session
node_main -->|"updates status"| node_progress
node_main -->|"sends sync operations"| node_session

click node_main "https://github.com/t3nsor27/file-sync/blob/main/main.cpp"
click node_peer "https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp"
click node_session "https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp"
click node_tree "https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp"
click node_hash "https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp"
click node_diff "https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp"
click node_serialize "https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp"
click node_apply "https://github.com/t3nsor27/file-sync/blob/main/main.cpp"
click node_progress "https://github.com/t3nsor27/file-sync/blob/main/main.cpp"
click node_packet "https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp"
click node_wire "https://github.com/t3nsor27/file-sync/blob/main/src/wire.cpp"

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_main,node_apply,node_progress toneBlue
class node_tree,node_hash,node_diff,node_serialize toneAmber
class node_peer,node_session toneMint
class node_packet,node_wire toneRose
class node_user,node_localfs,node_remote toneIndigo
```

## Components

### UI and orchestration

- [TUI and sync](https://github.com/t3nsor27/file-sync/blob/main/main.cpp): `main.cpp`
- [Sync apply](https://github.com/t3nsor27/file-sync/blob/main/main.cpp): `main.cpp`
- [Transfer progress](https://github.com/t3nsor27/file-sync/blob/main/main.cpp): `main.cpp`

### Filesystem model

- [Directory tree](https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp): `src/fstree.cpp`
- [SHA-256 hashing](https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp): `src/fstree.cpp`
- [Tree diff](https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp): `src/fstree.cpp`
- [Tree serialization](https://github.com/t3nsor27/file-sync/blob/main/src/fstree.cpp): `src/fstree.cpp`

### Peer networking

- [Peer lifecycle](https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp): `src/peer.cpp`
- [Session transport](https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp): `src/peer.cpp`

### Wire protocol

- [Packet framing](https://github.com/t3nsor27/file-sync/blob/main/src/peer.cpp): `src/peer.cpp`
- [Binary primitives](https://github.com/t3nsor27/file-sync/blob/main/src/wire.cpp): `src/wire.cpp`

### Other components

- **Operator**
- **Local directory**
- **Remote peer**

## Connections

- Operator → TUI and sync: selects peer
- TUI and sync → Peer lifecycle: starts listener
- TUI and sync → Peer lifecycle: requests connection
- Peer lifecycle → Remote peer: connects TCP
- Remote peer → Peer lifecycle: opens TCP
- Peer lifecycle → Session transport: creates session
- TUI and sync → Directory tree: builds local tree
- Directory tree → Local directory: reads directory
- Directory tree → SHA-256 hashing: hashes files
- TUI and sync → Session transport: exchanges trees
- Session transport → Tree serialization: serializes trees
- Session transport → Packet framing: frames messages
- Packet framing → Binary primitives: encodes fields
- Session transport → Remote peer: sends and receives
- TUI and sync → Tree diff: compares trees
- TUI and sync → Session transport: requests sync
- TUI and sync → Sync apply: handles sync packets
- Sync apply → Local directory: creates and deletes
- Sync apply → Session transport: receives file data
- TUI and sync → Transfer progress: updates status
- TUI and sync → Session transport: sends sync operations