# icloud-photos-downloader/icloud_photos_downloader architecture

> Architecture diagram of the GitHub repository icloud-photos-downloader/icloud_photos_downloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icloud-photos-downloader/icloud_photos_downloader
- Repository: https://github.com/icloud-photos-downloader/icloud_photos_downloader

## Overview

icloudpd is a command-line iCloud Photos downloader. The main workflow parses options, authenticates the account (including MFA), queries iCloud photo libraries, then downloads and names selected assets on local storage. Copy, sync, move, continuous watch, Live Photo/RAW handling, de-duplication, incremental selection, EXIF updates, and status reporting are additional product capabilities. Edges reflect the README and SOURCE INDEX references; unsampled modules are represented where documented, but their internal call paths are not inferred.

Main entry points: [`src/icloudpd/base.py`](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/base.py) (Download runner), [`src/pyicloud_ipd/services/photos.py`](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/services/photos.py) (Photo libraries and assets), [`src/icloudpd/download.py`](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/download.py) (Download selection), [`src/icloudpd/cli.py`](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/cli.py) (CLI options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI options<br/>[cli.py]"]
  node_config["User config<br/>[config.py]"]
  node_runner["Download runner<br/>[base.py]"]
end

subgraph group_icloud["iCloud access"]
  node_auth["Authentication and MFA<br/>[authentication.py]"]
  node_icloudclient["iCloud client<br/>[base.py]"]
  node_session["HTTP session<br/>[session.py]"]
  node_photos["Photo libraries and assets<br/>[photos.py]"]
  node_exceptions["API exceptions<br/>[exceptions.py]"]
end

subgraph group_assets["Asset processing"]
  node_download["Download selection<br/>[download.py]"]
  node_versions["Asset versions<br/>[asset_version.py]"]
  node_versiontypes["Version sizes<br/>[version_size.py]"]
  node_itemtypes["Asset types<br/>[item_type.py]"]
  node_policies["RAW and file policies<br/>[raw_policy.py]"]
  node_filematch["File matching<br/>[file_match.py]"]
  node_livepolicy["Live Photo naming"]
end

subgraph group_runtime["Local runtime"]
  node_autodelete["Sync and deletion<br/>[autodelete.py]"]
  node_metadata["EXIF metadata<br/>[exif_datetime.py]"]
  node_status["Status reporting<br/>[status.py]"]
  node_foundationjson["JSON utilities<br/>[json.py]"]
  node_strings["String utilities<br/>[string_utils.py]"]
  node_loglevel["Log levels<br/>[log_level.py]"]
  node_statusserver["Status server<br/>[__init__.py]"]
end

node_user(("CLI user"))
node_apple(("Apple iCloud"))
node_local[("Local photo files")]

node_user -->|"sets options"| node_cli
node_cli -->|"starts"| node_runner
node_cli -->|"configures"| node_config
node_runner -->|"authenticates"| node_auth
node_auth -->|"logs in"| node_icloudclient
node_icloudclient -->|"creates"| node_session
node_session -->|"sends requests"| node_apple
node_icloudclient -->|"provides library"| node_photos
node_runner -->|"runs downloads"| node_download
node_download -->|"selects assets"| node_photos
node_download -->|"uses versions"| node_versions
node_versions -->|"uses sizes"| node_versiontypes
node_photos -->|"classifies assets"| node_itemtypes
node_photos -->|"applies policy"| node_policies
node_photos -->|"uses sizes"| node_versiontypes
node_download -->|"handles errors"| node_exceptions
node_runner -->|"writes downloads"| node_local
node_runner -->|"syncs removals"| node_autodelete
node_runner -->|"updates EXIF"| node_metadata
node_runner -->|"updates status"| node_status
node_statusserver -->|"reads status"| node_status
node_photos -->|"matches files"| node_filematch
node_photos -->|"uses naming policy"| node_livepolicy
node_runner -->|"uses helpers"| node_strings
node_session -->|"uses JSON"| node_foundationjson

click node_cli "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/cli.py"
click node_config "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/config.py"
click node_runner "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/base.py"
click node_auth "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/authentication.py"
click node_icloudclient "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/base.py"
click node_session "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/session.py"
click node_photos "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/services/photos.py"
click node_exceptions "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/exceptions.py"
click node_download "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/download.py"
click node_versions "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/asset_version.py"
click node_versiontypes "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/version_size.py"
click node_itemtypes "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/item_type.py"
click node_policies "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/raw_policy.py"
click node_filematch "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/file_match.py"
click node_livepolicy "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/live_photo_mov_filename_policy.py"
click node_autodelete "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/autodelete.py"
click node_metadata "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/exif_datetime.py"
click node_status "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/status.py"
click node_foundationjson "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/foundation/json.py"
click node_strings "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/foundation/string_utils.py"
click node_loglevel "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/log_level.py"
click node_statusserver "https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/server/__init__.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_config,node_runner,node_user toneBlue
class node_auth,node_icloudclient,node_session,node_photos,node_exceptions,node_local toneAmber
class node_download,node_versions,node_versiontypes,node_itemtypes,node_policies,node_filematch,node_livepolicy toneMint
class node_autodelete,node_metadata,node_status,node_foundationjson,node_strings,node_loglevel,node_statusserver toneRose
class node_apple toneIndigo
```

## Components

### CLI and orchestration

- [CLI options](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/cli.py): `src/icloudpd/cli.py`
- [User config](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/config.py): `src/icloudpd/config.py`
- [Download runner](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/base.py): `src/icloudpd/base.py`

### iCloud access

- [Authentication and MFA](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/authentication.py): `src/icloudpd/authentication.py`
- [iCloud client](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/base.py): `src/pyicloud_ipd/base.py`
- [HTTP session](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/session.py): `src/pyicloud_ipd/session.py`
- [Photo libraries and assets](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/services/photos.py): `src/pyicloud_ipd/services/photos.py`
- [API exceptions](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/exceptions.py): `src/pyicloud_ipd/exceptions.py`

### Asset processing

- [Download selection](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/download.py): `src/icloudpd/download.py`
- [Asset versions](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/asset_version.py): `src/pyicloud_ipd/asset_version.py`
- [Version sizes](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/version_size.py): `src/pyicloud_ipd/version_size.py`
- [Asset types](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/item_type.py): `src/pyicloud_ipd/item_type.py`
- [RAW and file policies](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/raw_policy.py): `src/pyicloud_ipd/raw_policy.py`
- [File matching](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/file_match.py): `src/pyicloud_ipd/file_match.py`
- [Live Photo naming](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/pyicloud_ipd/live_photo_mov_filename_policy.py): `src/pyicloud_ipd/live_photo_mov_filename_policy.py`

### Local runtime

- [Sync and deletion](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/autodelete.py): `src/icloudpd/autodelete.py`
- [EXIF metadata](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/exif_datetime.py): `src/icloudpd/exif_datetime.py`
- [Status reporting](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/status.py): `src/icloudpd/status.py`
- [JSON utilities](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/foundation/json.py): `src/foundation/json.py`
- [String utilities](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/foundation/string_utils.py): `src/foundation/string_utils.py`
- [Log levels](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/log_level.py): `src/icloudpd/log_level.py`
- [Status server](https://github.com/icloud-photos-downloader/icloud_photos_downloader/blob/master/src/icloudpd/server/__init__.py): `src/icloudpd/server/__init__.py`

### Other components

- **CLI user**
- **Apple iCloud**
- **Local photo files**

## Connections

- CLI user → CLI options: sets options
- CLI options → Download runner: starts (evidence: `src/icloudpd/cli.py`)
- CLI options → User config: configures (evidence: `src/icloudpd/cli.py`)
- Download runner → Authentication and MFA: authenticates (evidence: `src/icloudpd/base.py`)
- Authentication and MFA → iCloud client: logs in (evidence: `src/icloudpd/authentication.py`)
- iCloud client → HTTP session: creates (evidence: `src/pyicloud_ipd/base.py`)
- HTTP session → Apple iCloud: sends requests (evidence: `src/pyicloud_ipd/session.py`)
- iCloud client → Photo libraries and assets: provides library (evidence: `src/pyicloud_ipd/base.py`)
- Download runner → Download selection: runs downloads (evidence: `src/icloudpd/base.py`)
- Download selection → Photo libraries and assets: selects assets (evidence: `src/icloudpd/download.py`)
- Download selection → Asset versions: uses versions (evidence: `src/icloudpd/download.py`)
- Asset versions → Version sizes: uses sizes (evidence: `src/pyicloud_ipd/asset_version.py`)
- Photo libraries and assets → Asset types: classifies assets (evidence: `src/pyicloud_ipd/services/photos.py`)
- Photo libraries and assets → RAW and file policies: applies policy (evidence: `src/pyicloud_ipd/services/photos.py`)
- Photo libraries and assets → Version sizes: uses sizes (evidence: `src/pyicloud_ipd/services/photos.py`)
- Download selection → API exceptions: handles errors (evidence: `src/icloudpd/download.py`)
- Download runner → Local photo files: writes downloads (evidence: `src/icloudpd/base.py`)
- Download runner → Sync and deletion: syncs removals (evidence: `src/icloudpd/base.py`)
- Download runner → EXIF metadata: updates EXIF (evidence: `src/icloudpd/base.py`)
- Download runner → Status reporting: updates status (evidence: `src/icloudpd/base.py`)
- Status server → Status reporting: reads status (evidence: `src/icloudpd/server/__init__.py`)
- Photo libraries and assets → File matching: matches files (evidence: `src/pyicloud_ipd/services/photos.py`)
- Photo libraries and assets → Live Photo naming: uses naming policy (evidence: `src/pyicloud_ipd/services/photos.py`)
- Download runner → String utilities: uses helpers (evidence: `src/icloudpd/base.py`)
- HTTP session → JSON utilities: uses JSON (evidence: `src/pyicloud_ipd/session.py`)
