# dkyazzentwatwa/cypher-pn532 architecture

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

## Overview

CYPHER NFC is an ESP32-C3/PN532 handheld NFC field workstation, with Cardputer and Cypherbox Mini ports. Its primary workflow is to scan a tag, identify its type, perform a read, audit, write, or clone operation, and save or inspect artifacts on SD. Device controls include the local menu, USB CLI, BLE, and a browser-based AP; tag emulation and a safe Type 4 APDU lab are additional branches. Most firmware behavior is documented in the README but its source was not excerpted, so those relationships cite the README rather than implying source inspection.

Main entry points: [`cypher_pn532/cypher_pn532.ino`](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino) (Device menu), [`tools/cypher_pn532_cli.py`](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/tools/cypher_pn532_cli.py) (USB CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Device workflow"]
  node_device_ui["Device menu<br/>[cypher_pn532.ino]"]
  node_scan["Scan and detect<br/>[cypher_pn532.ino]"]
  node_read["Read and dump<br/>[cypher_pn532.ino]"]
  node_key_audit["Key audit<br/>[cypher_pn532.ino]"]
  node_clone_verify["Clone and verify<br/>[cypher_pn532.ino]"]
  node_write["NDEF writing<br/>[cypher_pn532.ino]"]
end

subgraph group_storage["SD artifacts"]
  node_sd_tools["SD file tools<br/>[cypher_pn532.ino]"]
  node_artifacts["Dump artifacts<br/>[cypher_pn532.ino]"]
  node_scan_log["Scan log<br/>[cypher_pn532.ino]"]
  node_sidecars["JSON sidecars<br/>[cypher_pn532.ino]"]
end

subgraph group_controls["Control surfaces"]
  node_web_control["Web control<br/>[cypher_pn532.ino]"]
  node_ble_control["BLE serial<br/>[cypher_pn532.ino]"]
  node_usb_cli["USB CLI"]
end

subgraph group_protocols["Tag protocols"]
  node_emulation["Tag emulation<br/>[cypher_pn532.ino]"]
  node_apdu_lab["APDU lab<br/>[cypher_pn532.ino]"]
end

node_operator(("Lab operator"))
node_tag(("NFC tag"))
node_serial_host(("USB host"))
node_browser(("Browser"))
node_ble_client(("BLE client"))
node_phone_reader(("Phone or reader"))

node_operator -->|"operates"| node_device_ui
node_device_ui -->|"starts scan"| node_scan
node_scan -->|"detects type"| node_tag
node_device_ui -->|"starts read"| node_read
node_device_ui -->|"starts audit"| node_key_audit
node_device_ui -->|"starts cloning"| node_clone_verify
node_device_ui -->|"starts write"| node_write
node_read -->|"reads data"| node_tag
node_key_audit -->|"tests keys"| node_tag
node_clone_verify -->|"writes or checks"| node_tag
node_write -->|"writes NDEF"| node_tag
node_read -->|"saves dumps"| node_artifacts
node_key_audit -->|"saves metadata"| node_sidecars
node_scan -->|"logs scans"| node_scan_log
node_write -->|"logs writes"| node_scan_log
node_operator -->|"uses"| node_web_control
node_browser -->|"controls"| node_web_control
node_web_control -->|"requests scan"| node_scan
node_web_control -->|"requests dump"| node_read
node_web_control -->|"requests audit"| node_key_audit
node_web_control -->|"requests write"| node_write
node_web_control -->|"requests clone"| node_clone_verify
node_web_control -->|"manages files"| node_sd_tools
node_operator -->|"uses"| node_ble_control
node_ble_client -->|"sends commands"| node_ble_control
node_serial_host -->|"runs commands"| node_usb_cli
node_usb_cli -->|"requests scan"| node_scan
node_usb_cli -->|"requests dump"| node_read
node_usb_cli -->|"requests audit"| node_key_audit
node_usb_cli -->|"requests write"| node_write
node_usb_cli -->|"requests verify"| node_clone_verify
node_usb_cli -->|"manages files"| node_sd_tools
node_usb_cli -->|"downloads files"| node_artifacts
node_device_ui -->|"starts emulation"| node_emulation
node_emulation -->|"serves tag"| node_phone_reader
node_device_ui -->|"opens lab"| node_apdu_lab
node_apdu_lab -->|"probes Type 4"| node_tag
node_sd_tools -->|"browses files"| node_artifacts

click node_device_ui "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_scan "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_read "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_key_audit "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_clone_verify "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_write "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_sd_tools "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_artifacts "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_scan_log "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_sidecars "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_web_control "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_ble_control "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_usb_cli "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/tools/cypher_pn532_cli.py"
click node_emulation "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"
click node_apdu_lab "https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino"

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_device_ui,node_scan,node_read,node_key_audit,node_clone_verify,node_write,node_browser,node_ble_client toneBlue
class node_sd_tools,node_artifacts,node_scan_log,node_sidecars toneAmber
class node_web_control,node_ble_control,node_usb_cli toneMint
class node_emulation,node_apdu_lab toneRose
class node_operator,node_tag,node_serial_host,node_phone_reader toneIndigo
```

## Components

### Device workflow

- [Device menu](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Scan and detect](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Read and dump](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Key audit](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Clone and verify](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [NDEF writing](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`

### SD artifacts

- [SD file tools](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Dump artifacts](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [Scan log](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [JSON sidecars](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`

### Control surfaces

- [Web control](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [BLE serial](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [USB CLI](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/tools/cypher_pn532_cli.py): `tools/cypher_pn532_cli.py`

### Tag protocols

- [Tag emulation](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`
- [APDU lab](https://github.com/dkyazzentwatwa/cypher-pn532/blob/main/cypher_pn532/cypher_pn532.ino): `cypher_pn532/cypher_pn532.ino`

### Other components

- **Lab operator**
- **NFC tag**
- **USB host**
- **Browser**
- **BLE client**
- **Phone or reader**

## Connections

- Lab operator → Device menu: operates (evidence: `README.md`)
- Device menu → Scan and detect: starts scan (evidence: `README.md`)
- Scan and detect → NFC tag: detects type (evidence: `README.md`)
- Device menu → Read and dump: starts read (evidence: `README.md`)
- Device menu → Key audit: starts audit (evidence: `README.md`)
- Device menu → Clone and verify: starts cloning (evidence: `README.md`)
- Device menu → NDEF writing: starts write (evidence: `README.md`)
- Read and dump → NFC tag: reads data (evidence: `README.md`)
- Key audit → NFC tag: tests keys (evidence: `README.md`)
- Clone and verify → NFC tag: writes or checks (evidence: `README.md`)
- NDEF writing → NFC tag: writes NDEF (evidence: `README.md`)
- Read and dump → Dump artifacts: saves dumps (evidence: `README.md`)
- Key audit → JSON sidecars: saves metadata (evidence: `README.md`)
- Scan and detect → Scan log: logs scans (evidence: `README.md`)
- NDEF writing → Scan log: logs writes (evidence: `README.md`)
- Lab operator → Web control: uses (evidence: `README.md`)
- Browser → Web control: controls (evidence: `README.md`)
- Web control → Scan and detect: requests scan (evidence: `README.md`)
- Web control → Read and dump: requests dump (evidence: `README.md`)
- Web control → Key audit: requests audit (evidence: `README.md`)
- Web control → NDEF writing: requests write (evidence: `README.md`)
- Web control → Clone and verify: requests clone (evidence: `README.md`)
- Web control → SD file tools: manages files (evidence: `README.md`)
- Lab operator → BLE serial: uses (evidence: `README.md`)
- BLE client → BLE serial: sends commands (evidence: `README.md`)
- USB host → USB CLI: runs commands (evidence: `README.md`)
- USB CLI → Scan and detect: requests scan (evidence: `README.md`)
- USB CLI → Read and dump: requests dump (evidence: `README.md`)
- USB CLI → Key audit: requests audit (evidence: `README.md`)
- USB CLI → NDEF writing: requests write (evidence: `README.md`)
- USB CLI → Clone and verify: requests verify (evidence: `README.md`)
- USB CLI → SD file tools: manages files (evidence: `README.md`)
- USB CLI → Dump artifacts: downloads files (evidence: `README.md`)
- Device menu → Tag emulation: starts emulation (evidence: `README.md`)
- Tag emulation → Phone or reader: serves tag (evidence: `README.md`)
- Device menu → APDU lab: opens lab (evidence: `README.md`)
- APDU lab → NFC tag: probes Type 4 (evidence: `README.md`)
- SD file tools → Dump artifacts: browses files (evidence: `README.md`)
