# saivijayragav/binarysync architecture

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

## Overview

BinarySync versions and synchronizes large binary files by content-defined, SHA-256-addressed chunks. The principal workflow is: the CLI chunks a file, checks which chunks are missing, uploads only those, and commits a version manifest; downloads request a manifest diff and reuse cached chunks. Repository membership and role checks govern access, while metadata and chunk bytes are stored separately. The README documents these capabilities; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`binarysync-client/src/main/java/com/binarysync/client/ApiClient.java`](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ApiClient.java) (HTTP client), [`binarysync-client/src/main/java/com/binarysync/client/commands`](https://github.com/saivijayragav/binarysync/tree/main/binarysync-client/src/main/java/com/binarysync/client/commands) (CLI commands), [`binarysync-server/src/main/java/com/binarysync/service/RepositoryService.java`](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/RepositoryService.java) (Repository access), [`binarysync-server/src/main/java/com/binarysync/repository`](https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/repository) (Metadata repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["CLI client"]
  node_cli["CLI commands"]
  node_api_client["HTTP client<br/>[ApiClient.java]"]
  node_config["Client config<br/>[ConfigManager.java]"]
end

subgraph group_sync["Chunk sync"]
  node_chunker["CDC chunker"]
  node_cache[("Chunk cache")]
  node_sync_state[("Sync state")]
  node_cache_cleaner["Cache cleanup<br/>[CacheCleaner.java]"]
end

subgraph group_server["Server API"]
  node_auth_api["Auth endpoints"]
  node_repo_api["Repository endpoints"]
  node_file_api["File endpoints"]
  node_chunk_api["Chunk endpoints"]
  node_sync_api["Delta sync endpoint"]
  node_repository_service["Repository access"]
  node_sync_service["Version and manifest<br/>[SyncService.java]"]
  node_storage_service["Chunk storage service"]
  node_auth["JWT security"]
end

subgraph group_persistence["Persistence"]
  node_metadata[("Metadata repositories")]
  node_entities["Version metadata"]
end

node_user(("CLI user"))
node_s3[("AWS S3")]

node_user -->|"runs commands"| node_cli
node_cli -->|"makes requests"| node_api_client
node_cli -->|"chunks files"| node_chunker
node_cli -->|"checks or stores"| node_cache
node_cli -->|"reads or saves"| node_sync_state
node_cli -->|"cleans cache"| node_cache_cleaner
node_api_client -->|"uses credentials"| node_config
node_api_client -->|"calls auth"| node_auth_api
node_api_client -->|"manages repositories"| node_repo_api
node_api_client -->|"uploads and lists"| node_file_api
node_api_client -->|"transfers chunks"| node_chunk_api
node_api_client -->|"requests delta"| node_sync_api
node_auth_api -->|"reads or writes"| node_metadata
node_repo_api -->|"delegates operations"| node_repository_service
node_repository_service -->|"reads or writes"| node_metadata
node_repository_service -->|"manages records"| node_entities
node_file_api -->|"delegates file actions"| node_sync_service
node_file_api -->|"checks access"| node_repository_service
node_sync_api -->|"checks access"| node_repository_service
node_sync_api -->|"reads manifest"| node_metadata
node_chunk_api -->|"transfers chunk data"| node_storage_service
node_sync_service -->|"reads or writes"| node_metadata
node_sync_service -->|"updates version records"| node_entities
node_storage_service -->|"reads and writes chunks"| node_s3

click node_cli "https://github.com/saivijayragav/binarysync/tree/main/binarysync-client/src/main/java/com/binarysync/client/commands"
click node_api_client "https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ApiClient.java"
click node_config "https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ConfigManager.java"
click node_chunker "https://github.com/saivijayragav/binarysync/blob/main/binarysync-core/src/main/java/com/binarysync/service/ContentDefinedChunker.java"
click node_cache "https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ChunkCacheManager.java"
click node_sync_state "https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/SyncStateManager.java"
click node_cache_cleaner "https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/CacheCleaner.java"
click node_auth_api "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/AuthController.java"
click node_repo_api "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/RepositoryController.java"
click node_file_api "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/FileController.java"
click node_chunk_api "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/ChunkController.java"
click node_sync_api "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/SyncController.java"
click node_repository_service "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/RepositoryService.java"
click node_sync_service "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/SyncService.java"
click node_storage_service "https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/StorageService.java"
click node_metadata "https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/repository"
click node_entities "https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/model"
click node_auth "https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/security"

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_api_client,node_config,node_user toneBlue
class node_chunker,node_cache,node_sync_state,node_cache_cleaner,node_s3 toneAmber
class node_auth_api,node_repo_api,node_file_api,node_chunk_api,node_sync_api,node_repository_service,node_sync_service,node_storage_service,node_auth toneMint
class node_metadata,node_entities toneRose
```

## Components

### CLI client

- [CLI commands](https://github.com/saivijayragav/binarysync/tree/main/binarysync-client/src/main/java/com/binarysync/client/commands): `binarysync-client/src/main/java/com/binarysync/client/commands`
- [HTTP client](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ApiClient.java): `binarysync-client/src/main/java/com/binarysync/client/ApiClient.java`
- [Client config](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ConfigManager.java): `binarysync-client/src/main/java/com/binarysync/client/ConfigManager.java`

### Chunk sync

- [CDC chunker](https://github.com/saivijayragav/binarysync/blob/main/binarysync-core/src/main/java/com/binarysync/service/ContentDefinedChunker.java): `binarysync-core/src/main/java/com/binarysync/service/ContentDefinedChunker.java`
- [Chunk cache](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/ChunkCacheManager.java): `binarysync-client/src/main/java/com/binarysync/client/ChunkCacheManager.java`
- [Sync state](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/SyncStateManager.java): `binarysync-client/src/main/java/com/binarysync/client/SyncStateManager.java`
- [Cache cleanup](https://github.com/saivijayragav/binarysync/blob/main/binarysync-client/src/main/java/com/binarysync/client/CacheCleaner.java): `binarysync-client/src/main/java/com/binarysync/client/CacheCleaner.java`

### Server API

- [Auth endpoints](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/AuthController.java): `binarysync-server/src/main/java/com/binarysync/controller/AuthController.java`
- [Repository endpoints](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/RepositoryController.java): `binarysync-server/src/main/java/com/binarysync/controller/RepositoryController.java`
- [File endpoints](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/FileController.java): `binarysync-server/src/main/java/com/binarysync/controller/FileController.java`
- [Chunk endpoints](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/ChunkController.java): `binarysync-server/src/main/java/com/binarysync/controller/ChunkController.java`
- [Delta sync endpoint](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/controller/SyncController.java): `binarysync-server/src/main/java/com/binarysync/controller/SyncController.java`
- [Repository access](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/RepositoryService.java): `binarysync-server/src/main/java/com/binarysync/service/RepositoryService.java`
- [Version and manifest](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/SyncService.java): `binarysync-server/src/main/java/com/binarysync/service/SyncService.java`
- [Chunk storage service](https://github.com/saivijayragav/binarysync/blob/main/binarysync-server/src/main/java/com/binarysync/service/StorageService.java): `binarysync-server/src/main/java/com/binarysync/service/StorageService.java`
- [JWT security](https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/security): `binarysync-server/src/main/java/com/binarysync/security`

### Persistence

- [Metadata repositories](https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/repository): `binarysync-server/src/main/java/com/binarysync/repository`
- [Version metadata](https://github.com/saivijayragav/binarysync/tree/main/binarysync-server/src/main/java/com/binarysync/model): `binarysync-server/src/main/java/com/binarysync/model`

### Other components

- **CLI user**
- **AWS S3**

## Connections

- CLI user → CLI commands: runs commands
- CLI commands → HTTP client: makes requests
- CLI commands → CDC chunker: chunks files
- CLI commands → Chunk cache: checks or stores
- CLI commands → Sync state: reads or saves
- CLI commands → Cache cleanup: cleans cache
- HTTP client → Client config: uses credentials
- HTTP client → Auth endpoints: calls auth
- HTTP client → Repository endpoints: manages repositories
- HTTP client → File endpoints: uploads and lists
- HTTP client → Chunk endpoints: transfers chunks
- HTTP client → Delta sync endpoint: requests delta
- Auth endpoints → Metadata repositories: reads or writes
- Repository endpoints → Repository access: delegates operations
- Repository access → Metadata repositories: reads or writes
- Repository access → Version metadata: manages records
- File endpoints → Version and manifest: delegates file actions
- File endpoints → Repository access: checks access
- Delta sync endpoint → Repository access: checks access
- Delta sync endpoint → Metadata repositories: reads manifest
- Chunk endpoints → Chunk storage service: transfers chunk data
- Version and manifest → Metadata repositories: reads or writes
- Version and manifest → Version metadata: updates version records
- Chunk storage service → AWS S3: reads and writes chunks