# jamesyc/timecapsulesmb architecture

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

- Interactive diagram: https://gitdiagram.com/jamesyc/timecapsulesmb
- Repository: https://github.com/jamesyc/timecapsulesmb

## Overview

TimeCapsuleSMB installs and manages a Samba server on Apple Time Capsule devices so newer Macs can use their disks over SMB, including for Time Machine. The main workflow is to discover and configure a device, enable SSH, deploy Samba, and run a checkup; users can also activate, repair, flash a boot hook, maintain, or uninstall the installation. The repository contains both a macOS GUI and a Python CLI/API backed by shared device operations. Relationships among unsampled operation implementations are omitted; README-documented workflows and indexed imports support the links shown.

Main entry points: [`src/timecapsulesmb/app/ops`](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/app/ops) (Operation handlers), [`src/timecapsulesmb/deploy`](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/deploy) (Samba deployment), [`src/timecapsulesmb/transport/ssh.py`](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/transport/ssh.py) (SSH transport), [`macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBExecutable/main.swift`](https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBExecutable/main.swift) (macOS app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mac_ui["macOS app"]
  node_mac_app["macOS app<br/>[main.swift]"]
  node_device_profiles["Device profiles"]
  node_mac_workflows["Device workflows"]
  node_helper_backend["Helper backend"]
end

subgraph group_python_entry["Python interface"]
  node_cli["Command line<br/>[main.py]"]
  node_app_api["Operation API<br/>[service.py]"]
end

subgraph group_device_ops["Device operations"]
  node_operation_handlers["Operation handlers"]
  node_deployment["Samba deployment"]
  node_firmware_flash["Firmware flash<br/>[flash.py]"]
  node_device_maintenance["Device maintenance"]
end

subgraph group_diagnostics["Discovery and diagnostics"]
  node_discovery["Bonjour discovery"]
  node_checkup["Health checkup<br/>[doctor_steps.py]"]
  node_device_probes["Device probes"]
end

subgraph group_runtime["Shared runtime"]
  node_shared_config["Configuration and policy<br/>[config.py]"]
  node_networking["Network utilities<br/>[net.py]"]
  node_ssh_transport["SSH transport<br/>[ssh.py]"]
  node_device_storage["Remote storage<br/>[storage.py]"]
end

node_user(("Device administrator"))
node_time_capsule["Time Capsule"]
node_mac_client(("macOS SMB client"))

node_user -->|"manages device"| node_mac_app
node_mac_app -.->|"stores profiles"| node_device_profiles
node_mac_app -.->|"runs workflows"| node_mac_workflows
node_mac_workflows -.->|"requests operations"| node_helper_backend
node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches commands"| node_operation_handlers
node_app_api -->|"dispatches operations"| node_operation_handlers
node_user -->|"finds devices"| node_discovery
node_user -->|"installs Samba"| node_deployment
node_user -->|"checks installation"| node_checkup
node_user -->|"patches boot hook"| node_firmware_flash
node_user -->|"maintains device"| node_device_maintenance
node_operation_handlers -.->|"uses operation context"| node_app_api
node_operation_handlers -.->|"deploys files"| node_deployment
node_operation_handlers -.->|"runs flash workflow"| node_firmware_flash
node_operation_handlers -.->|"runs diagnostics"| node_checkup
node_operation_handlers -.->|"discovers devices"| node_discovery
node_operation_handlers -.->|"runs maintenance"| node_device_maintenance
node_deployment -->|"installs on"| node_time_capsule
node_firmware_flash -->|"patches firmware"| node_time_capsule
node_checkup -.->|"checks services"| node_time_capsule
node_deployment -.->|"uses SSH"| node_ssh_transport
node_device_maintenance -.->|"uses SSH"| node_ssh_transport
node_ssh_transport -->|"uses network utilities"| node_networking
node_device_storage -->|"uses SSH"| node_ssh_transport
node_device_probes -.->|"probes remotely"| node_time_capsule
node_shared_config -->|"uses network helpers"| node_networking
node_time_capsule -->|"serves SMB"| node_mac_client

click node_mac_app "https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBExecutable/main.swift"
click node_device_profiles "https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Profiles/DeviceProfile.swift"
click node_mac_workflows "https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Workflows/DeviceDashboardSession.swift"
click node_helper_backend "https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Backend/BackendClient.swift"
click node_cli "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/cli/main.py"
click node_app_api "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/app/service.py"
click node_operation_handlers "https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/app/ops"
click node_deployment "https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/deploy"
click node_firmware_flash "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/flash.py"
click node_device_maintenance "https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/services"
click node_discovery "https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/discovery"
click node_checkup "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/checks/doctor_steps.py"
click node_device_probes "https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/device"
click node_shared_config "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/core/config.py"
click node_networking "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/core/net.py"
click node_ssh_transport "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/transport/ssh.py"
click node_device_storage "https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/device/storage.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_mac_app,node_device_profiles,node_mac_workflows,node_helper_backend,node_mac_client toneBlue
class node_cli,node_app_api toneAmber
class node_operation_handlers,node_deployment,node_firmware_flash,node_device_maintenance toneMint
class node_discovery,node_checkup,node_device_probes toneRose
class node_shared_config,node_networking,node_ssh_transport,node_device_storage,node_user,node_time_capsule toneIndigo
```

## Components

### macOS app

- [macOS app](https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBExecutable/main.swift): `macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBExecutable/main.swift`
- [Device profiles](https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Profiles/DeviceProfile.swift): `macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Profiles/DeviceProfile.swift`
- [Device workflows](https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Workflows/DeviceDashboardSession.swift): `macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Workflows/DeviceDashboardSession.swift`
- [Helper backend](https://github.com/jamesyc/timecapsulesmb/blob/main/macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Backend/BackendClient.swift): `macos/TimeCapsuleSMB/Sources/TimeCapsuleSMBApp/Backend/BackendClient.swift`

### Python interface

- [Command line](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/cli/main.py): `src/timecapsulesmb/cli/main.py`
- [Operation API](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/app/service.py): `src/timecapsulesmb/app/service.py`

### Device operations

- [Operation handlers](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/app/ops): `src/timecapsulesmb/app/ops`
- [Samba deployment](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/deploy): `src/timecapsulesmb/deploy`
- [Firmware flash](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/flash.py): `src/timecapsulesmb/flash.py`
- [Device maintenance](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/services): `src/timecapsulesmb/services`

### Discovery and diagnostics

- [Bonjour discovery](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/discovery): `src/timecapsulesmb/discovery`
- [Health checkup](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/checks/doctor_steps.py): `src/timecapsulesmb/checks/doctor_steps.py`
- [Device probes](https://github.com/jamesyc/timecapsulesmb/tree/main/src/timecapsulesmb/device): `src/timecapsulesmb/device`

### Shared runtime

- [Configuration and policy](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/core/config.py): `src/timecapsulesmb/core/config.py`
- [Network utilities](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/core/net.py): `src/timecapsulesmb/core/net.py`
- [SSH transport](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/transport/ssh.py): `src/timecapsulesmb/transport/ssh.py`
- [Remote storage](https://github.com/jamesyc/timecapsulesmb/blob/main/src/timecapsulesmb/device/storage.py): `src/timecapsulesmb/device/storage.py`

### Other components

- **Device administrator**
- **Time Capsule**
- **macOS SMB client**

## Connections

- Device administrator → macOS app: manages device (evidence: `README.md`)
- macOS app → Device profiles: stores profiles
- macOS app → Device workflows: runs workflows
- Device workflows → Helper backend: requests operations
- Device administrator → Command line: runs commands (evidence: `README.md`)
- Command line → Operation handlers: dispatches commands (evidence: `src/timecapsulesmb/cli/main.py`)
- Operation API → Operation handlers: dispatches operations (evidence: `src/timecapsulesmb/app/service.py`)
- Device administrator → Bonjour discovery: finds devices (evidence: `README.md`)
- Device administrator → Samba deployment: installs Samba (evidence: `README.md`)
- Device administrator → Health checkup: checks installation (evidence: `README.md`)
- Device administrator → Firmware flash: patches boot hook (evidence: `README.md`)
- Device administrator → Device maintenance: maintains device (evidence: `README.md`)
- Operation handlers → Operation API: uses operation context (evidence: `src/timecapsulesmb/app/service.py`)
- Operation handlers → Samba deployment: deploys files
- Operation handlers → Firmware flash: runs flash workflow
- Operation handlers → Health checkup: runs diagnostics
- Operation handlers → Bonjour discovery: discovers devices
- Operation handlers → Device maintenance: runs maintenance (evidence: `src/timecapsulesmb/app/ops/__init__.py`)
- Samba deployment → Time Capsule: installs on (evidence: `README.md`)
- Firmware flash → Time Capsule: patches firmware (evidence: `README.md`)
- Health checkup → Time Capsule: checks services
- Samba deployment → SSH transport: uses SSH (evidence: `src/timecapsulesmb/deploy/migration.py`)
- Device maintenance → SSH transport: uses SSH (evidence: `src/timecapsulesmb/services/storage.py`)
- SSH transport → Network utilities: uses network utilities (evidence: `src/timecapsulesmb/transport/ssh.py`)
- Remote storage → SSH transport: uses SSH (evidence: `src/timecapsulesmb/device/storage.py`)
- Device probes → Time Capsule: probes remotely
- Configuration and policy → Network utilities: uses network helpers (evidence: `src/timecapsulesmb/core/config.py`)
- Time Capsule → macOS SMB client: serves SMB (evidence: `README.md`)
