# kurobeats/coldsnake architecture

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

## Overview

ColdSnake is a headless Icedrive client for interactive remote operations and scheduled local-to-cloud backups. The main workflow is CLI configuration and pre-flight checks, incremental mirror planning, upload, verification, and optional pruning; separate commands support downloads/restores and account or file management. The graph follows the sampled CLI, mirror, client, and state code plus documented README capabilities. Some command internals were not sampled, so those capability links are documented rather than inferred from imports.

Main entry points: [`src/coldsnake/cli.py`](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/cli.py) (CLI commands), [`src/coldsnake/sync.py`](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py) (Mirror planner), [`src/coldsnake/client.py`](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py) (API client), [`src/coldsnake/state.py`](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/state.py) (Sync database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Command interface"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_preflight["Pre-flight checks<br/>[sync.py]"]
  node_reports["Reports and webhook<br/>[cli.py]"]
end

subgraph group_protocol["Icedrive access"]
  node_auth["Login and 2FA<br/>[client.py]"]
  node_client["API client<br/>[client.py]"]
  node_remote_files["Folder listing and changes<br/>[client.py]"]
  node_downloads["Download and resume<br/>[client.py]"]
  node_recovery["Trash and restore<br/>[client.py]"]
  node_history["Version history<br/>[client.py]"]
end

subgraph group_mirror["Backup workflow"]
  node_mirror["Mirror planner<br/>[sync.py]"]
  node_upload["Chunked upload<br/>[client.py]"]
  node_verify["Upload verification<br/>[sync.py]"]
  node_prune["Prune stale files<br/>[sync.py]"]
end

subgraph group_state["Persistent state"]
  node_syncdb[("Sync database<br/>[state.py]")]
  node_journal["Upload journal<br/>[state.py]"]
end

node_operator(("Operator"))
node_icedrive["Icedrive API"]
node_local["Local files"]
node_webhook_service["Webhook endpoint"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"checks sources"| node_preflight
node_cli -->|"runs mirrors"| node_mirror
node_cli -->|"builds client"| node_client
node_cli -->|"reports runs"| node_reports
node_cli -->|"uses state"| node_syncdb
node_mirror -->|"scans files"| node_local
node_mirror -->|"lists folders"| node_client
node_mirror -->|"reads and records"| node_syncdb
node_mirror -->|"uploads planned files"| node_upload
node_mirror -->|"verifies uploads"| node_verify
node_mirror -->|"optionally prunes"| node_prune
node_upload -.->|"resumes chunks"| node_journal
node_auth -->|"authenticates"| node_icedrive
node_client -->|"calls API"| node_icedrive
node_cli -->|"lists and edits"| node_remote_files
node_cli -->|"downloads files"| node_downloads
node_cli -->|"restores items"| node_recovery
node_cli -->|"shows versions"| node_history
node_reports -->|"posts events"| node_webhook_service

click node_cli "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/cli.py"
click node_preflight "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py"
click node_reports "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/cli.py"
click node_auth "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_client "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_remote_files "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_downloads "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_recovery "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_history "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_mirror "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py"
click node_upload "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py"
click node_verify "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py"
click node_prune "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py"
click node_syncdb "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/state.py"
click node_journal "https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/state.py"

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_preflight,node_reports toneBlue
class node_auth,node_client,node_remote_files,node_downloads,node_recovery,node_history toneAmber
class node_mirror,node_upload,node_verify,node_prune,node_icedrive,node_webhook_service toneMint
class node_syncdb,node_journal toneRose
class node_operator,node_local toneIndigo
```

## Components

### Command interface

- [CLI commands](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/cli.py): `src/coldsnake/cli.py`
- [Pre-flight checks](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py): `src/coldsnake/sync.py`
- [Reports and webhook](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/cli.py): `src/coldsnake/cli.py`

### Icedrive access

- [Login and 2FA](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [API client](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [Folder listing and changes](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [Download and resume](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [Trash and restore](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [Version history](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`

### Backup workflow

- [Mirror planner](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py): `src/coldsnake/sync.py`
- [Chunked upload](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/client.py): `src/coldsnake/client.py`
- [Upload verification](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py): `src/coldsnake/sync.py`
- [Prune stale files](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/sync.py): `src/coldsnake/sync.py`

### Persistent state

- [Sync database](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/state.py): `src/coldsnake/state.py`
- [Upload journal](https://github.com/kurobeats/coldsnake/blob/main/src/coldsnake/state.py): `src/coldsnake/state.py`

### Other components

- **Operator**
- **Icedrive API**
- **Local files**
- **Webhook endpoint**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Pre-flight checks: checks sources (evidence: `src/coldsnake/cli.py`)
- CLI commands → Mirror planner: runs mirrors (evidence: `src/coldsnake/cli.py`)
- CLI commands → API client: builds client (evidence: `src/coldsnake/cli.py`)
- CLI commands → Reports and webhook: reports runs (evidence: `src/coldsnake/cli.py`)
- CLI commands → Sync database: uses state (evidence: `src/coldsnake/cli.py`)
- Mirror planner → Local files: scans files (evidence: `src/coldsnake/sync.py`)
- Mirror planner → API client: lists folders (evidence: `src/coldsnake/sync.py`)
- Mirror planner → Sync database: reads and records (evidence: `src/coldsnake/sync.py`)
- Mirror planner → Chunked upload: uploads planned files (evidence: `README.md`)
- Mirror planner → Upload verification: verifies uploads (evidence: `src/coldsnake/sync.py`)
- Mirror planner → Prune stale files: optionally prunes (evidence: `src/coldsnake/sync.py`)
- Chunked upload → Upload journal: resumes chunks
- Login and 2FA → Icedrive API: authenticates (evidence: `README.md`)
- API client → Icedrive API: calls API (evidence: `README.md`)
- CLI commands → Folder listing and changes: lists and edits (evidence: `README.md`)
- CLI commands → Download and resume: downloads files (evidence: `README.md`)
- CLI commands → Trash and restore: restores items (evidence: `README.md`)
- CLI commands → Version history: shows versions (evidence: `README.md`)
- Reports and webhook → Webhook endpoint: posts events (evidence: `README.md`)
