# patrikbures/gamesync architecture

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

- Interactive diagram: https://gitdiagram.com/patrikbures/gamesync
- Repository: https://github.com/patrikbures/gamesync

## Overview

Gamesync is a game-save synchronization CLI backed by a server. The intended user workflow is to configure the client, create or select a repository and branch, then sync local save files through the server; the server organizes snapshots and deduplicated chunks. The tree also shows administration for users, roles, and permissions. The README warns that the main branch is undergoing a rewrite, and the available excerpts do not show the sync implementation or most service wiring, so uncertain internal calls are omitted.

Main entry points: [`internal/ogen/oas_handlers_gen.go`](https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_handlers_gen.go) (HTTP handlers), [`internal/server/dbm/db.go`](https://github.com/patrikbures/gamesync/blob/main/internal/server/dbm/db.go) (PostgreSQL state), [`internal/client/syncer/syncer.go`](https://github.com/patrikbures/gamesync/blob/main/internal/client/syncer/syncer.go) (Sync engine), [`internal/server/service/api_chunks.go`](https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_chunks.go) (Chunk API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflow"]
  node_cli["CLI entry<br/>[root.go]"]
  node_commands["Sync commands<br/>[sync.go]"]
  node_syncer["Sync engine<br/>[syncer.go]"]
  node_file_scan["Local file scan<br/>[all_files.go]"]
  node_client_api["Generated API client<br/>[oas_client_gen.go]"]
end

subgraph group_server["Server API"]
  node_server["Gamesync server<br/>[serve.go]"]
  node_router["HTTP router<br/>[oas_router_gen.go]"]
  node_handlers["HTTP handlers"]
  node_repo_service["Repo and branch API<br/>[api_repos.go]"]
  node_snapshot_service["Snapshot API<br/>[api_snapshots.go]"]
  node_chunk_service["Chunk API<br/>[api_chunks.go]"]
  node_identity_service["Identity and roles<br/>[api_users.go]"]
end

subgraph group_state["State and access"]
  node_auth["Authentication<br/>[authz.go]"]
  node_permissions["Permission rules<br/>[permissions.go]"]
  node_db[("PostgreSQL state<br/>[db.go]")]
  node_chunk_store["Chunk storage<br/>[storage.go]"]
end

node_user(("Game-save user"))
node_local_saves["Save files"]
node_postgres[("PostgreSQL")]
node_storage_backend[("Storage backend")]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"invokes"| node_syncer
node_syncer -->|"scans saves"| node_file_scan
node_file_scan -->|"reads files"| node_local_saves
node_syncer -->|"uses API"| node_client_api
node_client_api -->|"HTTP requests"| node_server
node_server -->|"serves HTTP"| node_router
node_router -->|"dispatches"| node_handlers
node_handlers -->|"handles repo calls"| node_repo_service
node_handlers -->|"handles snapshot calls"| node_snapshot_service
node_handlers -->|"handles chunk calls"| node_chunk_service
node_handlers -->|"handles identity calls"| node_identity_service
node_handlers -->|"middleware"| node_auth
node_auth -->|"checks access"| node_permissions
node_repo_service -->|"state access"| node_db
node_snapshot_service -->|"state access"| node_db
node_chunk_service -->|"metadata access"| node_db
node_chunk_service -->|"stores chunks"| node_chunk_store
node_identity_service -->|"state access"| node_db
node_db -->|"reads and writes"| node_postgres
node_chunk_store -->|"stores data"| node_storage_backend

click node_cli "https://github.com/patrikbures/gamesync/blob/main/cmd/gamesync/root.go"
click node_commands "https://github.com/patrikbures/gamesync/blob/main/internal/client/cmd/sync/sync.go"
click node_syncer "https://github.com/patrikbures/gamesync/blob/main/internal/client/syncer/syncer.go"
click node_file_scan "https://github.com/patrikbures/gamesync/blob/main/internal/client/util/all_files.go"
click node_client_api "https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_client_gen.go"
click node_server "https://github.com/patrikbures/gamesync/blob/main/cmd/gamesync-server/serve.go"
click node_router "https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_router_gen.go"
click node_handlers "https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_handlers_gen.go"
click node_repo_service "https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_repos.go"
click node_snapshot_service "https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_snapshots.go"
click node_chunk_service "https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_chunks.go"
click node_identity_service "https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_users.go"
click node_auth "https://github.com/patrikbures/gamesync/blob/main/internal/server/middleware/authz.go"
click node_permissions "https://github.com/patrikbures/gamesync/blob/main/internal/server/permissions/permissions.go"
click node_db "https://github.com/patrikbures/gamesync/blob/main/internal/server/dbm/db.go"
click node_chunk_store "https://github.com/patrikbures/gamesync/blob/main/internal/server/storage/storage.go"

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_commands,node_syncer,node_file_scan,node_client_api,node_user toneBlue
class node_server,node_router,node_handlers,node_repo_service,node_snapshot_service,node_chunk_service,node_identity_service,node_postgres,node_storage_backend toneAmber
class node_auth,node_permissions,node_db,node_chunk_store toneMint
class node_local_saves toneIndigo
```

## Components

### Client workflow

- [CLI entry](https://github.com/patrikbures/gamesync/blob/main/cmd/gamesync/root.go): `cmd/gamesync/root.go`
- [Sync commands](https://github.com/patrikbures/gamesync/blob/main/internal/client/cmd/sync/sync.go): `internal/client/cmd/sync/sync.go`
- [Sync engine](https://github.com/patrikbures/gamesync/blob/main/internal/client/syncer/syncer.go): `internal/client/syncer/syncer.go`
- [Local file scan](https://github.com/patrikbures/gamesync/blob/main/internal/client/util/all_files.go): `internal/client/util/all_files.go`
- [Generated API client](https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_client_gen.go): `internal/ogen/oas_client_gen.go`

### Server API

- [Gamesync server](https://github.com/patrikbures/gamesync/blob/main/cmd/gamesync-server/serve.go): `cmd/gamesync-server/serve.go`
- [HTTP router](https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_router_gen.go): `internal/ogen/oas_router_gen.go`
- [HTTP handlers](https://github.com/patrikbures/gamesync/blob/main/internal/ogen/oas_handlers_gen.go): `internal/ogen/oas_handlers_gen.go`
- [Repo and branch API](https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_repos.go): `internal/server/service/api_repos.go`
- [Snapshot API](https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_snapshots.go): `internal/server/service/api_snapshots.go`
- [Chunk API](https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_chunks.go): `internal/server/service/api_chunks.go`
- [Identity and roles](https://github.com/patrikbures/gamesync/blob/main/internal/server/service/api_users.go): `internal/server/service/api_users.go`

### State and access

- [Authentication](https://github.com/patrikbures/gamesync/blob/main/internal/server/middleware/authz.go): `internal/server/middleware/authz.go`
- [Permission rules](https://github.com/patrikbures/gamesync/blob/main/internal/server/permissions/permissions.go): `internal/server/permissions/permissions.go`
- [PostgreSQL state](https://github.com/patrikbures/gamesync/blob/main/internal/server/dbm/db.go): `internal/server/dbm/db.go`
- [Chunk storage](https://github.com/patrikbures/gamesync/blob/main/internal/server/storage/storage.go): `internal/server/storage/storage.go`

### Other components

- **Game-save user**
- **Save files**
- **PostgreSQL**
- **Storage backend**

## Connections

- Game-save user → CLI entry: runs
- CLI entry → Sync commands: dispatches
- Sync commands → Sync engine: invokes
- Sync engine → Local file scan: scans saves
- Local file scan → Save files: reads files
- Sync engine → Generated API client: uses API
- Generated API client → Gamesync server: HTTP requests
- Gamesync server → HTTP router: serves HTTP
- HTTP router → HTTP handlers: dispatches
- HTTP handlers → Repo and branch API: handles repo calls
- HTTP handlers → Snapshot API: handles snapshot calls
- HTTP handlers → Chunk API: handles chunk calls
- HTTP handlers → Identity and roles: handles identity calls
- HTTP handlers → Authentication: middleware
- Authentication → Permission rules: checks access
- Repo and branch API → PostgreSQL state: state access
- Snapshot API → PostgreSQL state: state access
- Chunk API → PostgreSQL state: metadata access
- Chunk API → Chunk storage: stores chunks
- Identity and roles → PostgreSQL state: state access
- PostgreSQL state → PostgreSQL: reads and writes
- Chunk storage → Storage backend: stores data