# beefyandtheducks/saveshare architecture

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

## Overview

SaveShare is a desktop client and WebSocket server for registering, cataloguing, and synchronizing local save files with cloud saves. Users connect and authenticate, browse saves, then register or download saves, check them out, exchange full files or manifest-based deltas, and release checkouts. The client’s sync service coordinates catalog and local-save state; the server authenticates connections and dispatches protocol messages to save operations. The tree and sampled files support these main responsibilities, but unsampled service and handler wiring is shown only where paths and dispatch behavior are evident.

Main entry points: [`Client/Networking/ServerSession.cs`](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/ServerSession.cs) (Client session), [`Client/Services/SaveSyncService.cs`](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveSyncService.cs) (Save synchronization), [`Server/MessageHandlers/V1/MessageHandler.cs`](https://github.com/beefyandtheducks/saveshare/blob/main/Server/MessageHandlers/V1/MessageHandler.cs) (Message dispatch), [`Client/Services/SaveCatalogService.cs`](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveCatalogService.cs) (Save catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop client"]
  node_client_ui["Client UI"]
  node_viewmodel["Main view model"]
  node_auth["Authentication"]
  node_catalog["Save catalog"]
  node_sync["Save synchronization<br/>[SaveSyncService.cs]"]
end

subgraph group_network["Protocol transport"]
  node_client_session["Client session<br/>[ServerSession.cs]"]
  node_connection["Connection manager"]
  node_transport["WebSocket transport"]
  node_codec["JSON message codec"]
end

subgraph group_shared["Shared save formats"]
  node_protocol["V1 message protocol<br/>[Protocol.cs]"]
  node_save_formats["Save manifests and packing<br/>[SavePacker.cs]"]
end

subgraph group_server["Server operations"]
  node_server["WebSocket endpoint"]
  node_dispatch["Message dispatch<br/>[MessageHandler.cs]"]
  node_auth_handlers["Sign-in handlers"]
  node_catalog_handlers["Save listing handlers"]
  node_checkout_handlers["Checkout handlers"]
  node_full_save_handlers["Full save handlers"]
  node_delta_handlers["Delta sync handlers"]
end

subgraph group_state["Persistent state"]
  node_save_registry["Save registry<br/>[SaveRegistry.cs]"]
  node_user_registry["User registry<br/>[UserRegistry.cs]"]
  node_local_store[("Local save store<br/>[LocalSaveStore.cs]")]
  node_user_store[("User store<br/>[UserStore.cs]")]
end

node_user(("Desktop user"))

node_user -->|"uses"| node_client_ui
node_viewmodel -->|"authenticates"| node_auth
node_viewmodel -->|"browses"| node_catalog
node_viewmodel -->|"synchronizes"| node_sync
node_auth -->|"signs in"| node_client_session
node_auth -->|"loads and saves"| node_user_store
node_catalog -->|"lists saves"| node_client_session
node_catalog -->|"loads local saves"| node_local_store
node_sync -->|"exchanges saves"| node_client_session
node_sync -->|"refreshes"| node_catalog
node_sync -->|"records local saves"| node_local_store
node_connection -->|"connects"| node_client_session
node_client_session -->|"transfers messages"| node_transport
node_client_session -->|"encodes messages"| node_codec
node_server -->|"dispatches messages"| node_dispatch
node_server -->|"authenticates via"| node_auth_handlers
node_dispatch -->|"dispatches"| node_catalog_handlers
node_dispatch -->|"dispatches"| node_checkout_handlers
node_dispatch -->|"dispatches"| node_full_save_handlers
node_dispatch -->|"dispatches"| node_delta_handlers
node_auth_handlers -->|"creates or loads"| node_user_registry
node_catalog_handlers -->|"reads save catalog"| node_save_registry
node_checkout_handlers -->|"updates checkout"| node_save_registry
node_full_save_handlers -->|"reads and updates"| node_save_registry
node_delta_handlers -->|"reads and updates"| node_save_registry
node_sync -->|"packs and applies deltas"| node_save_formats
node_full_save_handlers -->|"packs and applies"| node_save_formats
node_delta_handlers -->|"builds and applies deltas"| node_save_formats

click node_client_ui "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Views/MainWindow.axaml.cs"
click node_viewmodel "https://github.com/beefyandtheducks/saveshare/blob/main/Client/ViewModels/MainWindowViewModel.cs"
click node_auth "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/AuthenticationService.cs"
click node_catalog "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveCatalogService.cs"
click node_sync "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveSyncService.cs"
click node_client_session "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/ServerSession.cs"
click node_connection "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/ConnectionManager.cs"
click node_transport "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/WebSocketTransport.cs"
click node_codec "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/JsonMessageCodec.cs"
click node_protocol "https://github.com/beefyandtheducks/saveshare/blob/main/Common/Protocol/V1/Protocol.cs"
click node_save_formats "https://github.com/beefyandtheducks/saveshare/blob/main/Common/SavePacker.cs"
click node_server "https://github.com/beefyandtheducks/saveshare/blob/main/Server/ConnectionManagerV1.cs"
click node_dispatch "https://github.com/beefyandtheducks/saveshare/blob/main/Server/MessageHandlers/V1/MessageHandler.cs"
click node_auth_handlers "https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1"
click node_catalog_handlers "https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1"
click node_checkout_handlers "https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1"
click node_full_save_handlers "https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1"
click node_delta_handlers "https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1"
click node_save_registry "https://github.com/beefyandtheducks/saveshare/blob/main/Server/SaveRegistry.cs"
click node_user_registry "https://github.com/beefyandtheducks/saveshare/blob/main/Server/UserRegistry.cs"
click node_local_store "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Storage/LocalSaveStore.cs"
click node_user_store "https://github.com/beefyandtheducks/saveshare/blob/main/Client/Storage/UserStore.cs"

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_client_ui,node_viewmodel,node_auth,node_catalog,node_sync,node_user toneBlue
class node_client_session,node_connection,node_transport,node_codec toneAmber
class node_protocol,node_save_formats toneMint
class node_server,node_dispatch,node_auth_handlers,node_catalog_handlers,node_checkout_handlers,node_full_save_handlers,node_delta_handlers toneRose
class node_save_registry,node_user_registry,node_local_store,node_user_store toneIndigo
```

## Components

### Desktop client

- [Client UI](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Views/MainWindow.axaml.cs): `Client/Views/MainWindow.axaml.cs`
- [Main view model](https://github.com/beefyandtheducks/saveshare/blob/main/Client/ViewModels/MainWindowViewModel.cs): `Client/ViewModels/MainWindowViewModel.cs`
- [Authentication](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/AuthenticationService.cs): `Client/Services/AuthenticationService.cs`
- [Save catalog](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveCatalogService.cs): `Client/Services/SaveCatalogService.cs`
- [Save synchronization](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Services/SaveSyncService.cs): `Client/Services/SaveSyncService.cs`

### Protocol transport

- [Client session](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/ServerSession.cs): `Client/Networking/ServerSession.cs`
- [Connection manager](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/ConnectionManager.cs): `Client/Networking/ConnectionManager.cs`
- [WebSocket transport](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/WebSocketTransport.cs): `Client/Networking/WebSocketTransport.cs`
- [JSON message codec](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Networking/JsonMessageCodec.cs): `Client/Networking/JsonMessageCodec.cs`

### Shared save formats

- [V1 message protocol](https://github.com/beefyandtheducks/saveshare/blob/main/Common/Protocol/V1/Protocol.cs): `Common/Protocol/V1/Protocol.cs`
- [Save manifests and packing](https://github.com/beefyandtheducks/saveshare/blob/main/Common/SavePacker.cs): `Common/SavePacker.cs`

### Server operations

- [WebSocket endpoint](https://github.com/beefyandtheducks/saveshare/blob/main/Server/ConnectionManagerV1.cs): `Server/ConnectionManagerV1.cs`
- [Message dispatch](https://github.com/beefyandtheducks/saveshare/blob/main/Server/MessageHandlers/V1/MessageHandler.cs): `Server/MessageHandlers/V1/MessageHandler.cs`
- [Sign-in handlers](https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1): `Server/MessageHandlers/V1`
- [Save listing handlers](https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1): `Server/MessageHandlers/V1`
- [Checkout handlers](https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1): `Server/MessageHandlers/V1`
- [Full save handlers](https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1): `Server/MessageHandlers/V1`
- [Delta sync handlers](https://github.com/beefyandtheducks/saveshare/tree/main/Server/MessageHandlers/V1): `Server/MessageHandlers/V1`

### Persistent state

- [Save registry](https://github.com/beefyandtheducks/saveshare/blob/main/Server/SaveRegistry.cs): `Server/SaveRegistry.cs`
- [User registry](https://github.com/beefyandtheducks/saveshare/blob/main/Server/UserRegistry.cs): `Server/UserRegistry.cs`
- [Local save store](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Storage/LocalSaveStore.cs): `Client/Storage/LocalSaveStore.cs`
- [User store](https://github.com/beefyandtheducks/saveshare/blob/main/Client/Storage/UserStore.cs): `Client/Storage/UserStore.cs`

### Other components

- **Desktop user**

## Connections

- Desktop user → Client UI: uses
- Main view model → Authentication: authenticates
- Main view model → Save catalog: browses
- Main view model → Save synchronization: synchronizes
- Authentication → Client session: signs in
- Authentication → User store: loads and saves
- Save catalog → Client session: lists saves
- Save catalog → Local save store: loads local saves
- Save synchronization → Client session: exchanges saves
- Save synchronization → Save catalog: refreshes
- Save synchronization → Local save store: records local saves
- Connection manager → Client session: connects
- Client session → WebSocket transport: transfers messages
- Client session → JSON message codec: encodes messages
- WebSocket endpoint → Message dispatch: dispatches messages
- WebSocket endpoint → Sign-in handlers: authenticates via
- Message dispatch → Save listing handlers: dispatches
- Message dispatch → Checkout handlers: dispatches
- Message dispatch → Full save handlers: dispatches
- Message dispatch → Delta sync handlers: dispatches
- Sign-in handlers → User registry: creates or loads
- Save listing handlers → Save registry: reads save catalog
- Checkout handlers → Save registry: updates checkout
- Full save handlers → Save registry: reads and updates
- Delta sync handlers → Save registry: reads and updates
- Save synchronization → Save manifests and packing: packs and applies deltas
- Full save handlers → Save manifests and packing: packs and applies
- Delta sync handlers → Save manifests and packing: builds and applies deltas