# toplcm/linkx architecture

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

## Overview

LinkX is a Windows–Android companion app for nearby device pairing and cross-device productivity. Users discover a phone on the local network, pair over Bluetooth after comparing a six-digit code, then use Bluetooth for notifications, clipboard and media control, and an encrypted LAN channel for files and album transfers. The map includes both platform shells and shared session, security, transport and transfer layers. README statements support the shared-core and channel relationships; sampled excerpts and the source index provide additional wiring evidence, while unsampled feature internals are shown only at their documented subsystem level.

Main entry points: [`Crates/session/src/engine.rs`](https://github.com/toplcm/linkx/blob/main/Crates/session/src/engine.rs) (Session engine), [`Platforms/Windows/src/app.rs`](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/app.rs) (Windows app), [`Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt`](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt) (Android runtime), [`Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt`](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt) (Android app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Platform clients"]
  node_windows["Windows app<br/>[app.rs]"]
  node_windows_ui["Windows UI<br/>[window.rs]"]
  node_android_ui["Android app<br/>[MainActivity.kt]"]
  node_android_runtime["Android runtime<br/>[LinkxRuntime.kt]"]
  node_windows_state["Windows shared state<br/>[state.rs]"]
end

subgraph group_session["Pairing and session"]
  node_session_engine["Session engine<br/>[engine.rs]"]
end

subgraph group_transport["Transport"]
  node_android_ble["Android BLE service"]
  node_discovery["LAN discovery<br/>[discovery.rs]"]
  node_lan_transport["LAN transport<br/>[stream.rs]"]
  node_ble_central["Windows BLE<br/>[ble_central.rs]"]
end

subgraph group_security["Security and protocol"]
  node_crypto_identity["Device identity<br/>[identity.rs]"]
  node_crypto_noise["Noise handshake<br/>[noise_resolver.rs]"]
  node_crypto_cipher["Frame encryption<br/>[cipher.rs]"]
  node_replay["Replay protection<br/>[replay.rs]"]
  node_protocol["Message protocol<br/>[envelope.rs]"]
end

subgraph group_features["Product features"]
  node_android_notifications["Notification sync<br/>[NlsService.kt]"]
  node_android_features["Android feature controls<br/>[Features.kt]"]
  node_windows_features["Windows feature controls<br/>[features.rs]"]
end

subgraph group_transfer["File and album transfer"]
  node_transfer_engine["Transfer tasks<br/>[task.rs]"]
  node_transfer_chunks["Chunk handling<br/>[chunk.rs]"]
  node_storage[("Local storage<br/>[lib.rs]")]
end

node_user(("User"))

node_user -->|"uses"| node_windows_ui
node_user -->|"uses"| node_android_ui
node_windows_ui -->|"commands"| node_windows
node_windows -->|"updates"| node_windows_state
node_windows -->|"drives BLE"| node_ble_central
node_android_ui -->|"starts"| node_android_runtime
node_android_ui -->|"starts"| node_android_ble
node_android_ble -->|"initializes"| node_android_runtime
node_android_ble -->|"relays BLE"| node_session_engine
node_windows -->|"drives session"| node_session_engine
node_windows -->|"discovers peers"| node_discovery
node_windows -->|"opens LAN channel"| node_lan_transport
node_discovery -->|"locates peers"| node_lan_transport
node_session_engine -->|"encodes messages"| node_protocol
node_session_engine -->|"handshakes"| node_crypto_noise
node_session_engine -->|"encrypts frames"| node_crypto_cipher
node_session_engine -->|"checks identity"| node_crypto_identity
node_session_engine -->|"uses replay window"| node_replay
node_session_engine -->|"routes file messages"| node_transfer_engine
node_transfer_engine -->|"handles chunks"| node_transfer_chunks
node_transfer_engine -.->|"persists data"| node_storage
node_android_runtime -->|"forwards notifications"| node_android_notifications
node_android_runtime -->|"checks features"| node_android_features
node_windows -->|"checks features"| node_windows_features
node_windows -->|"transfers files"| node_lan_transport
node_android_runtime -->|"calls native core"| node_session_engine

click node_windows "https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/app.rs"
click node_windows_ui "https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/window.rs"
click node_android_ui "https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt"
click node_android_runtime "https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt"
click node_android_ble "https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/BlePeripheralService.kt"
click node_session_engine "https://github.com/toplcm/linkx/blob/main/Crates/session/src/engine.rs"
click node_discovery "https://github.com/toplcm/linkx/blob/main/Crates/lan/src/discovery.rs"
click node_lan_transport "https://github.com/toplcm/linkx/blob/main/Crates/lan/src/stream.rs"
click node_ble_central "https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/ble_central.rs"
click node_crypto_identity "https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/identity.rs"
click node_crypto_noise "https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/noise_resolver.rs"
click node_crypto_cipher "https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/cipher.rs"
click node_replay "https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/replay.rs"
click node_protocol "https://github.com/toplcm/linkx/blob/main/Crates/protocol/src/envelope.rs"
click node_transfer_engine "https://github.com/toplcm/linkx/blob/main/Crates/transfer/src/task.rs"
click node_transfer_chunks "https://github.com/toplcm/linkx/blob/main/Crates/transfer/src/chunk.rs"
click node_storage "https://github.com/toplcm/linkx/blob/main/Crates/storage/src/lib.rs"
click node_android_notifications "https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/NlsService.kt"
click node_android_features "https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/Features.kt"
click node_windows_features "https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/features.rs"
click node_windows_state "https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/state.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_windows,node_windows_ui,node_android_ui,node_android_runtime,node_windows_state,node_user toneBlue
class node_session_engine toneAmber
class node_android_ble,node_discovery,node_lan_transport,node_ble_central toneMint
class node_crypto_identity,node_crypto_noise,node_crypto_cipher,node_replay,node_protocol toneRose
class node_android_notifications,node_android_features,node_windows_features toneIndigo
class node_transfer_engine,node_transfer_chunks,node_storage toneTeal
```

## Components

### Platform clients

- [Windows app](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/app.rs): `Platforms/Windows/src/app.rs`
- [Windows UI](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/window.rs): `Platforms/Windows/src/window.rs`
- [Android app](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt): `Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt`
- [Android runtime](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt): `Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt`
- [Windows shared state](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/state.rs): `Platforms/Windows/src/state.rs`

### Pairing and session

- [Session engine](https://github.com/toplcm/linkx/blob/main/Crates/session/src/engine.rs): `Crates/session/src/engine.rs`

### Transport

- [Android BLE service](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/BlePeripheralService.kt): `Platforms/Android/app/src/main/java/com/linkx/app/BlePeripheralService.kt`
- [LAN discovery](https://github.com/toplcm/linkx/blob/main/Crates/lan/src/discovery.rs): `Crates/lan/src/discovery.rs`
- [LAN transport](https://github.com/toplcm/linkx/blob/main/Crates/lan/src/stream.rs): `Crates/lan/src/stream.rs`
- [Windows BLE](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/ble_central.rs): `Platforms/Windows/src/ble_central.rs`

### Security and protocol

- [Device identity](https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/identity.rs): `Crates/crypto/src/identity.rs`
- [Noise handshake](https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/noise_resolver.rs): `Crates/crypto/src/noise_resolver.rs`
- [Frame encryption](https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/cipher.rs): `Crates/crypto/src/cipher.rs`
- [Replay protection](https://github.com/toplcm/linkx/blob/main/Crates/crypto/src/replay.rs): `Crates/crypto/src/replay.rs`
- [Message protocol](https://github.com/toplcm/linkx/blob/main/Crates/protocol/src/envelope.rs): `Crates/protocol/src/envelope.rs`

### Product features

- [Notification sync](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/NlsService.kt): `Platforms/Android/app/src/main/java/com/linkx/app/NlsService.kt`
- [Android feature controls](https://github.com/toplcm/linkx/blob/main/Platforms/Android/app/src/main/java/com/linkx/app/Features.kt): `Platforms/Android/app/src/main/java/com/linkx/app/Features.kt`
- [Windows feature controls](https://github.com/toplcm/linkx/blob/main/Platforms/Windows/src/features.rs): `Platforms/Windows/src/features.rs`

### File and album transfer

- [Transfer tasks](https://github.com/toplcm/linkx/blob/main/Crates/transfer/src/task.rs): `Crates/transfer/src/task.rs`
- [Chunk handling](https://github.com/toplcm/linkx/blob/main/Crates/transfer/src/chunk.rs): `Crates/transfer/src/chunk.rs`
- [Local storage](https://github.com/toplcm/linkx/blob/main/Crates/storage/src/lib.rs): `Crates/storage/src/lib.rs`

### Other components

- **User**

## Connections

- User → Windows UI: uses (evidence: `README.md`)
- User → Android app: uses (evidence: `README.md`)
- Windows UI → Windows app: commands (evidence: `Platforms/Windows/src/window.rs`)
- Windows app → Windows shared state: updates (evidence: `Platforms/Windows/src/app.rs`)
- Windows app → Windows BLE: drives BLE (evidence: `Platforms/Windows/src/app.rs`)
- Android app → Android runtime: starts (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt`)
- Android app → Android BLE service: starts (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/MainActivity.kt`)
- Android BLE service → Android runtime: initializes (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/BlePeripheralService.kt`)
- Android BLE service → Session engine: relays BLE (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/BlePeripheralService.kt`)
- Windows app → Session engine: drives session (evidence: `Platforms/Windows/src/app.rs`)
- Windows app → LAN discovery: discovers peers (evidence: `README.md`)
- Windows app → LAN transport: opens LAN channel (evidence: `Platforms/Windows/src/app.rs`)
- LAN discovery → LAN transport: locates peers (evidence: `Crates/lan/src/stream.rs`)
- Session engine → Message protocol: encodes messages (evidence: `Crates/session/src/engine.rs`)
- Session engine → Noise handshake: handshakes (evidence: `Crates/session/src/engine.rs`)
- Session engine → Frame encryption: encrypts frames (evidence: `README.md`)
- Session engine → Device identity: checks identity (evidence: `Crates/session/src/engine.rs`)
- Session engine → Replay protection: uses replay window (evidence: `README.md`)
- Session engine → Transfer tasks: routes file messages (evidence: `Crates/session/src/engine.rs`)
- Transfer tasks → Chunk handling: handles chunks (evidence: `Crates/transfer/src/task.rs`)
- Transfer tasks → Local storage: persists data
- Android runtime → Notification sync: forwards notifications (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/NlsService.kt`)
- Android runtime → Android feature controls: checks features (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt`)
- Windows app → Windows feature controls: checks features (evidence: `Platforms/Windows/src/app.rs`)
- Windows app → LAN transport: transfers files (evidence: `README.md`)
- Android runtime → Session engine: calls native core (evidence: `Platforms/Android/app/src/main/java/com/linkx/app/LinkxRuntime.kt`)
