# walshdsouza/shadow-sync architecture

> Architecture diagram of the GitHub repository walshdsouza/shadow-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/walshdsouza/shadow-sync
- Repository: https://github.com/walshdsouza/shadow-sync

## Overview

Env-Sync is a CLI for creating or joining rooms and synchronizing each teammate’s local `.env` file. The main workflow is: save room credentials, derive a shared key locally, watch local edits, encrypt and send updates through a WebSocket relay, then decrypt and apply remote state with timestamp and empty-overwrite protections. The relay forwards encrypted messages between room members. The README describes the zero-trust and conflict-resolution capabilities; the graph also includes the direct `start` workflow. Relationships are limited to the shown source and documented architecture.

Main entry points: [`src/sync.js`](https://github.com/walshdsouza/shadow-sync/blob/main/src/sync.js) (Sync Coordinator), [`src/cli.js`](https://github.com/walshdsouza/shadow-sync/blob/main/src/cli.js) (CLI Commands), [`server/server.js`](https://github.com/walshdsouza/shadow-sync/blob/main/server/server.js) (WebSocket Relay), [`src/watcher.js`](https://github.com/walshdsouza/shadow-sync/blob/main/src/watcher.js) (File Watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Room Setup"]
  node_cli["CLI Commands<br/>[cli.js]"]
  node_config["Room Config<br/>[config.js]"]
  node_key["Key Derivation<br/>[crypto.js]"]
end

subgraph group_client["Sync Client"]
  node_sync["Sync Coordinator<br/>[sync.js]"]
  node_watcher["File Watcher<br/>[watcher.js]"]
  node_network["WebSocket Client<br/>[NetworkManager.js]"]
  node_crypto["Payload Crypto<br/>[crypto.js]"]
end

subgraph group_state["Local State"]
  node_state_manager["State Manager<br/>[StateManager.js]"]
  node_env_file["Local .env"]
end

subgraph group_relay["Room Relay"]
  node_relay_server["WebSocket Relay<br/>[server.js]"]
end

node_developer(("Developer"))
node_room_peers(("Room Peers"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"saves or loads"| node_config
node_cli -->|"derives key"| node_key
node_cli -->|"starts sync"| node_sync
node_sync -->|"reads and evaluates"| node_state_manager
node_state_manager -->|"reads and writes"| node_env_file
node_sync -->|"starts watching"| node_watcher
node_watcher -->|"reports edits"| node_sync
node_sync -->|"encrypts and decrypts"| node_crypto
node_sync -->|"sends and receives"| node_network
node_network -->|"connects to relay"| node_relay_server
node_relay_server -->|"forwards room messages"| node_room_peers
node_room_peers -->|"sends room messages"| node_relay_server

click node_cli "https://github.com/walshdsouza/shadow-sync/blob/main/src/cli.js"
click node_config "https://github.com/walshdsouza/shadow-sync/blob/main/src/config.js"
click node_key "https://github.com/walshdsouza/shadow-sync/blob/main/src/crypto.js"
click node_sync "https://github.com/walshdsouza/shadow-sync/blob/main/src/sync.js"
click node_watcher "https://github.com/walshdsouza/shadow-sync/blob/main/src/watcher.js"
click node_network "https://github.com/walshdsouza/shadow-sync/blob/main/src/NetworkManager.js"
click node_crypto "https://github.com/walshdsouza/shadow-sync/blob/main/src/crypto.js"
click node_state_manager "https://github.com/walshdsouza/shadow-sync/blob/main/src/StateManager.js"
click node_relay_server "https://github.com/walshdsouza/shadow-sync/blob/main/server/server.js"

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_config,node_key toneBlue
class node_sync,node_watcher,node_network,node_crypto toneAmber
class node_state_manager,node_env_file toneMint
class node_relay_server toneRose
class node_developer,node_room_peers toneIndigo
```

## Components

### Room Setup

- [CLI Commands](https://github.com/walshdsouza/shadow-sync/blob/main/src/cli.js): `src/cli.js`
- [Room Config](https://github.com/walshdsouza/shadow-sync/blob/main/src/config.js): `src/config.js`
- [Key Derivation](https://github.com/walshdsouza/shadow-sync/blob/main/src/crypto.js): `src/crypto.js`

### Sync Client

- [Sync Coordinator](https://github.com/walshdsouza/shadow-sync/blob/main/src/sync.js): `src/sync.js`
- [File Watcher](https://github.com/walshdsouza/shadow-sync/blob/main/src/watcher.js): `src/watcher.js`
- [WebSocket Client](https://github.com/walshdsouza/shadow-sync/blob/main/src/NetworkManager.js): `src/NetworkManager.js`
- [Payload Crypto](https://github.com/walshdsouza/shadow-sync/blob/main/src/crypto.js): `src/crypto.js`

### Local State

- [State Manager](https://github.com/walshdsouza/shadow-sync/blob/main/src/StateManager.js): `src/StateManager.js`
- **Local .env**

### Room Relay

- [WebSocket Relay](https://github.com/walshdsouza/shadow-sync/blob/main/server/server.js): `server/server.js`

### Other components

- **Developer**
- **Room Peers**

## Connections

- Developer → CLI Commands: runs commands (evidence: `README.md`)
- CLI Commands → Room Config: saves or loads (evidence: `src/cli.js`)
- CLI Commands → Key Derivation: derives key (evidence: `src/cli.js`)
- CLI Commands → Sync Coordinator: starts sync (evidence: `src/cli.js`)
- Sync Coordinator → State Manager: reads and evaluates (evidence: `src/sync.js`)
- State Manager → Local .env: reads and writes (evidence: `src/StateManager.js`)
- Sync Coordinator → File Watcher: starts watching (evidence: `src/sync.js`)
- File Watcher → Sync Coordinator: reports edits (evidence: `src/sync.js`)
- Sync Coordinator → Payload Crypto: encrypts and decrypts (evidence: `src/sync.js`)
- Sync Coordinator → WebSocket Client: sends and receives (evidence: `src/sync.js`)
- WebSocket Client → WebSocket Relay: connects to relay (evidence: `README.md`)
- WebSocket Relay → Room Peers: forwards room messages (evidence: `server/server.js`)
- Room Peers → WebSocket Relay: sends room messages (evidence: `server/server.js`)
