# sheldonjoo/aircard-zh architecture

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

- Interactive diagram: https://gitdiagram.com/sheldonjoo/aircard-zh
- Repository: https://github.com/sheldonjoo/aircard-zh

## Overview

AirCard is a macOS app for customizing Apple Wallet card artwork and iPhone lock-screen passcode themes. The main workflows select or discover an iPhone and card, prepare artwork or a theme, then write assets to the device and refresh caches. The README also documents theme creation and editing, interactive previews, and bulk card updates. The excerpts show the backend and device-write mechanisms; wiring for some Swift UI actions and theme-creator operations is not fully sampled, so uncertain links are omitted.

Main entry points: [`aircard_backend.py`](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py) (Command Backend), [`apply_card_skin.py`](https://github.com/sheldonjoo/aircard-zh/blob/main/apply_card_skin.py) (Device File Writer), [`Sources/device_helper.m`](https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/device_helper.m) (Device Helper), [`AirCardApp.swift`](https://github.com/sheldonjoo/aircard-zh/blob/main/AirCardApp.swift) (AirCard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["macOS Interface"]
  node_app["AirCard UI<br/>[AirCardApp.swift]"]
  node_backend["Command Backend<br/>[aircard_backend.py]"]
end

subgraph group_wallet["Wallet Skins"]
  node_savedcards[("Saved Card Hashes<br/>[aircard.py]")]
  node_carddetect["Card Detection<br/>[aircard.py]"]
  node_imageprep["Image Preparation<br/>[aircard.py]"]
  node_assets["Asset Builder<br/>[card_assets.py]"]
  node_skinwrite["Skin Writer<br/>[aircard_backend.py]"]
  node_cache["Cache Invalidation<br/>[apply_card_skin.py]"]
end

subgraph group_themes["Passcode Themes"]
  node_themecreator["Theme Creator<br/>[AirCardApp.swift]"]
  node_themeparser["Theme Parser<br/>[aircard_backend.py]"]
  node_themeapply["Theme Writer<br/>[aircard_backend.py]"]
end

subgraph group_device["Device Access"]
  node_cardwrite["Device File Writer<br/>[apply_card_skin.py]"]
  node_airtraffic["AirTraffic Host<br/>[airtraffic_host.m]"]
  node_target["Airlift Target<br/>[airlift_target.h]"]
  node_devicehelper["Device Helper<br/>[device_helper.m]"]
end

node_user(("User"))
node_iphone(("iPhone"))
node_walletapp(("Apple Wallet"))

node_user -->|"uses"| node_app
node_app -->|"requests operations"| node_backend
node_app -->|"creates or edits"| node_themecreator
node_backend -->|"loads and saves"| node_savedcards
node_backend -->|"scans logs"| node_carddetect
node_carddetect -->|"streams syslog"| node_devicehelper
node_devicehelper -->|"reads logs"| node_iphone
node_backend -->|"prepares artwork"| node_imageprep
node_backend -->|"builds assets"| node_assets
node_backend -->|"writes card skin"| node_skinwrite
node_skinwrite -->|"writes files"| node_cardwrite
node_skinwrite -->|"invalidates caches"| node_cache
node_cache -->|"writes cache files"| node_cardwrite
node_backend -->|"parses theme"| node_themeparser
node_backend -->|"applies theme"| node_themeapply
node_themeapply -->|"writes theme files"| node_cardwrite
node_cardwrite -->|"dispatches writes"| node_airtraffic
node_cardwrite -->|"stages and finishes"| node_devicehelper
node_airtraffic -->|"transfers files"| node_iphone
node_devicehelper -->|"accesses device"| node_iphone
node_target -.->|"defines targets"| node_devicehelper
node_iphone -->|"displays updated skin"| node_walletapp

click node_app "https://github.com/sheldonjoo/aircard-zh/blob/main/AirCardApp.swift"
click node_backend "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py"
click node_savedcards "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py"
click node_carddetect "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py"
click node_imageprep "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py"
click node_assets "https://github.com/sheldonjoo/aircard-zh/blob/main/card_assets.py"
click node_skinwrite "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py"
click node_cache "https://github.com/sheldonjoo/aircard-zh/blob/main/apply_card_skin.py"
click node_themecreator "https://github.com/sheldonjoo/aircard-zh/blob/main/AirCardApp.swift"
click node_themeparser "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py"
click node_themeapply "https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py"
click node_cardwrite "https://github.com/sheldonjoo/aircard-zh/blob/main/apply_card_skin.py"
click node_airtraffic "https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/airtraffic_host.m"
click node_target "https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/airlift_target.h"
click node_devicehelper "https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/device_helper.m"

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_app,node_backend,node_user toneBlue
class node_savedcards,node_carddetect,node_imageprep,node_assets,node_skinwrite,node_cache toneAmber
class node_themecreator,node_themeparser,node_themeapply toneMint
class node_cardwrite,node_airtraffic,node_target,node_devicehelper toneRose
class node_iphone,node_walletapp toneIndigo
```

## Components

### macOS Interface

- [AirCard UI](https://github.com/sheldonjoo/aircard-zh/blob/main/AirCardApp.swift): `AirCardApp.swift`
- [Command Backend](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py): `aircard_backend.py`

### Wallet Skins

- [Saved Card Hashes](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py): `aircard.py`
- [Card Detection](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py): `aircard.py`
- [Image Preparation](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard.py): `aircard.py`
- [Asset Builder](https://github.com/sheldonjoo/aircard-zh/blob/main/card_assets.py): `card_assets.py`
- [Skin Writer](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py): `aircard_backend.py`
- [Cache Invalidation](https://github.com/sheldonjoo/aircard-zh/blob/main/apply_card_skin.py): `apply_card_skin.py`

### Passcode Themes

- [Theme Creator](https://github.com/sheldonjoo/aircard-zh/blob/main/AirCardApp.swift): `AirCardApp.swift`
- [Theme Parser](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py): `aircard_backend.py`
- [Theme Writer](https://github.com/sheldonjoo/aircard-zh/blob/main/aircard_backend.py): `aircard_backend.py`

### Device Access

- [Device File Writer](https://github.com/sheldonjoo/aircard-zh/blob/main/apply_card_skin.py): `apply_card_skin.py`
- [AirTraffic Host](https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/airtraffic_host.m): `Sources/airtraffic_host.m`
- [Airlift Target](https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/airlift_target.h): `Sources/airlift_target.h`
- [Device Helper](https://github.com/sheldonjoo/aircard-zh/blob/main/Sources/device_helper.m): `Sources/device_helper.m`

### Other components

- **User**
- **iPhone**
- **Apple Wallet**

## Connections

- User → AirCard UI: uses
- AirCard UI → Command Backend: requests operations
- AirCard UI → Theme Creator: creates or edits
- Command Backend → Saved Card Hashes: loads and saves
- Command Backend → Card Detection: scans logs
- Card Detection → Device Helper: streams syslog
- Device Helper → iPhone: reads logs
- Command Backend → Image Preparation: prepares artwork
- Command Backend → Asset Builder: builds assets
- Command Backend → Skin Writer: writes card skin
- Skin Writer → Device File Writer: writes files
- Skin Writer → Cache Invalidation: invalidates caches
- Cache Invalidation → Device File Writer: writes cache files
- Command Backend → Theme Parser: parses theme
- Command Backend → Theme Writer: applies theme
- Theme Writer → Device File Writer: writes theme files
- Device File Writer → AirTraffic Host: dispatches writes
- Device File Writer → Device Helper: stages and finishes
- AirTraffic Host → iPhone: transfers files
- Device Helper → iPhone: accesses device
- Airlift Target → Device Helper: defines targets
- iPhone → Apple Wallet: displays updated skin