# yueze/cardmic architecture

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

- Interactive diagram: https://gitdiagram.com/yueze/cardmic
- Repository: https://github.com/yueze/cardmic

## Overview

Cardmic turns a Cardputer into a microphone over USB or Wi-Fi. On-device, audio is captured and processed, then sent by USB Audio or as network packets; pairing protects wireless audio. On the computer, the receiver discovers the device, authenticates and orders packets, handles loss and buffering, and plays samples into a virtual loopback device that dictation apps select as a microphone. The desktop app adds device status, pairing, settings, and updates. The README documents these capabilities; some implementation links below rely on that documentation because the relevant source was not sampled.

Main entry points: [`client/engine/src/lib.rs`](https://github.com/yueze/cardmic/blob/main/client/engine/src/lib.rs) (Receiving engine), [`client/tray/src/app.rs`](https://github.com/yueze/cardmic/blob/main/client/tray/src/app.rs) (Menu and status), [`firmware/main/apps/app_cardmic/cardmic_net.c`](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_net.c) (Wi-Fi audio and discovery), [`firmware/main/apps/app_cardmic/app_cardmic.cpp`](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/app_cardmic.cpp) (Device settings and display)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Cardputer firmware"]
  node_capture["Audio capture and DSP<br/>[app_cardmic.cpp]"]
  node_device_ui["Device settings and display<br/>[app_cardmic.cpp]"]
end

subgraph group_transport["Audio transport"]
  node_usb["USB audio and talk key<br/>[cardmic_usb.c]"]
  node_wifi["Wi-Fi audio and discovery<br/>[cardmic_net.c]"]
  node_pairing["Pairing and encryption<br/>[cardmic_pair.c]"]
  node_protocol["Packet protocol<br/>[protocol.rs]"]
  node_pair_core["Key derivation<br/>[pairing.rs]"]
end

subgraph group_receiver["Desktop receiver"]
  node_engine["Receiving engine<br/>[lib.rs]"]
  node_network["Discovery targets<br/>[net.rs]"]
  node_drift["Buffer and drift control<br/>[drift.rs]"]
  node_spectrum["Audio visualization data<br/>[spectrum.rs]"]
  node_audio["Loopback playback<br/>[sink.rs]"]
end

subgraph group_desktop["Desktop experience"]
  node_tray["Menu and status<br/>[app.rs]"]
  node_devices["Device selection<br/>[devices.rs]"]
  node_settings["App settings<br/>[settings.rs]"]
  node_updates["Self-updater<br/>[update.rs]"]
  node_usb_monitor["USB pairing monitor<br/>[usb.rs]"]
end

node_user(("Cardputer user"))
node_dictation["Dictation app"]
node_loopback["Virtual audio device"]

node_user -->|"configures"| node_device_ui
node_capture -.->|"provides audio"| node_usb
node_capture -.->|"provides audio"| node_wifi
node_device_ui -.->|"sets pairing"| node_pairing
node_device_ui -->|"sets device name"| node_wifi
node_pairing -->|"secures stream"| node_wifi
node_usb -->|"sends talk key"| node_user
node_usb -->|"provides microphone"| node_dictation
node_wifi -->|"streams packets"| node_engine
node_engine -->|"gets targets"| node_network
node_engine -.->|"decodes packets"| node_protocol
node_engine -.->|"opens encrypted audio"| node_pair_core
node_engine -->|"controls buffering"| node_drift
node_engine -->|"reports spectrum"| node_spectrum
node_engine -->|"plays samples"| node_audio
node_audio -->|"outputs audio"| node_loopback
node_loopback -->|"feeds microphone"| node_dictation
node_tray -.->|"starts receiver"| node_engine
node_tray -->|"reads devices"| node_devices
node_tray -->|"reads settings"| node_settings
node_tray -->|"checks updates"| node_updates
node_tray -->|"monitors USB"| node_usb_monitor
node_usb_monitor -.->|"transfers pairing code"| node_pair_core

click node_capture "https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/app_cardmic.cpp"
click node_device_ui "https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/app_cardmic.cpp"
click node_usb "https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_usb.c"
click node_wifi "https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_net.c"
click node_pairing "https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_pair.c"
click node_protocol "https://github.com/yueze/cardmic/blob/main/client/core/src/protocol.rs"
click node_pair_core "https://github.com/yueze/cardmic/blob/main/client/core/src/pairing.rs"
click node_engine "https://github.com/yueze/cardmic/blob/main/client/engine/src/lib.rs"
click node_network "https://github.com/yueze/cardmic/blob/main/client/engine/src/net.rs"
click node_drift "https://github.com/yueze/cardmic/blob/main/client/engine/src/drift.rs"
click node_spectrum "https://github.com/yueze/cardmic/blob/main/client/engine/src/spectrum.rs"
click node_audio "https://github.com/yueze/cardmic/blob/main/client/audio/src/sink.rs"
click node_tray "https://github.com/yueze/cardmic/blob/main/client/tray/src/app.rs"
click node_devices "https://github.com/yueze/cardmic/blob/main/client/tray/src/devices.rs"
click node_settings "https://github.com/yueze/cardmic/blob/main/client/tray/src/settings.rs"
click node_updates "https://github.com/yueze/cardmic/blob/main/client/tray/src/update.rs"
click node_usb_monitor "https://github.com/yueze/cardmic/blob/main/client/tray/src/usb.rs"

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_capture,node_device_ui,node_user toneBlue
class node_usb,node_wifi,node_pairing,node_protocol,node_pair_core toneAmber
class node_engine,node_network,node_drift,node_spectrum,node_audio toneMint
class node_tray,node_devices,node_settings,node_updates,node_usb_monitor toneRose
class node_dictation,node_loopback toneIndigo
```

## Components

### Cardputer firmware

- [Audio capture and DSP](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/app_cardmic.cpp): `firmware/main/apps/app_cardmic/app_cardmic.cpp`
- [Device settings and display](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/app_cardmic.cpp): `firmware/main/apps/app_cardmic/app_cardmic.cpp`

### Audio transport

- [USB audio and talk key](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_usb.c): `firmware/main/apps/app_cardmic/cardmic_usb.c`
- [Wi-Fi audio and discovery](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_net.c): `firmware/main/apps/app_cardmic/cardmic_net.c`
- [Pairing and encryption](https://github.com/yueze/cardmic/blob/main/firmware/main/apps/app_cardmic/cardmic_pair.c): `firmware/main/apps/app_cardmic/cardmic_pair.c`
- [Packet protocol](https://github.com/yueze/cardmic/blob/main/client/core/src/protocol.rs): `client/core/src/protocol.rs`
- [Key derivation](https://github.com/yueze/cardmic/blob/main/client/core/src/pairing.rs): `client/core/src/pairing.rs`

### Desktop receiver

- [Receiving engine](https://github.com/yueze/cardmic/blob/main/client/engine/src/lib.rs): `client/engine/src/lib.rs`
- [Discovery targets](https://github.com/yueze/cardmic/blob/main/client/engine/src/net.rs): `client/engine/src/net.rs`
- [Buffer and drift control](https://github.com/yueze/cardmic/blob/main/client/engine/src/drift.rs): `client/engine/src/drift.rs`
- [Audio visualization data](https://github.com/yueze/cardmic/blob/main/client/engine/src/spectrum.rs): `client/engine/src/spectrum.rs`
- [Loopback playback](https://github.com/yueze/cardmic/blob/main/client/audio/src/sink.rs): `client/audio/src/sink.rs`

### Desktop experience

- [Menu and status](https://github.com/yueze/cardmic/blob/main/client/tray/src/app.rs): `client/tray/src/app.rs`
- [Device selection](https://github.com/yueze/cardmic/blob/main/client/tray/src/devices.rs): `client/tray/src/devices.rs`
- [App settings](https://github.com/yueze/cardmic/blob/main/client/tray/src/settings.rs): `client/tray/src/settings.rs`
- [Self-updater](https://github.com/yueze/cardmic/blob/main/client/tray/src/update.rs): `client/tray/src/update.rs`
- [USB pairing monitor](https://github.com/yueze/cardmic/blob/main/client/tray/src/usb.rs): `client/tray/src/usb.rs`

### Other components

- **Cardputer user**
- **Dictation app**
- **Virtual audio device**

## Connections

- Cardputer user → Device settings and display: configures
- Audio capture and DSP → USB audio and talk key: provides audio
- Audio capture and DSP → Wi-Fi audio and discovery: provides audio
- Device settings and display → Pairing and encryption: sets pairing
- Device settings and display → Wi-Fi audio and discovery: sets device name (evidence: `firmware/main/apps/app_cardmic/app_cardmic.cpp`)
- Pairing and encryption → Wi-Fi audio and discovery: secures stream
- USB audio and talk key → Cardputer user: sends talk key
- USB audio and talk key → Dictation app: provides microphone
- Wi-Fi audio and discovery → Receiving engine: streams packets
- Receiving engine → Discovery targets: gets targets (evidence: `client/engine/src/lib.rs`)
- Receiving engine → Packet protocol: decodes packets
- Receiving engine → Key derivation: opens encrypted audio
- Receiving engine → Buffer and drift control: controls buffering (evidence: `client/engine/src/lib.rs`)
- Receiving engine → Audio visualization data: reports spectrum (evidence: `client/engine/src/lib.rs`)
- Receiving engine → Loopback playback: plays samples (evidence: `client/engine/src/lib.rs`)
- Loopback playback → Virtual audio device: outputs audio (evidence: `client/audio/src/sink.rs`)
- Virtual audio device → Dictation app: feeds microphone
- Menu and status → Receiving engine: starts receiver
- Menu and status → Device selection: reads devices (evidence: `client/tray/src/app.rs`)
- Menu and status → App settings: reads settings (evidence: `client/tray/src/app.rs`)
- Menu and status → Self-updater: checks updates (evidence: `client/tray/src/app.rs`)
- Menu and status → USB pairing monitor: monitors USB (evidence: `client/tray/src/app.rs`)
- USB pairing monitor → Key derivation: transfers pairing code
