From 7410cebac5532dd60289dd59abcac3c30564381e Mon Sep 17 00:00:00 2001 From: "Evgeny @ SimpleX Chat" <259188159+evgeny-simplex@users.noreply.github.com> Date: Sat, 14 Mar 2026 15:35:53 +0000 Subject: [PATCH] update agent diagram --- spec/agent.md | 52 +++++++ spec/diagrams/agent.svg | 330 +++++++++++++++++++++++----------------- 2 files changed, 239 insertions(+), 143 deletions(-) diff --git a/spec/agent.md b/spec/agent.md index f77ccd4a4..a6f944260 100644 --- a/spec/agent.md +++ b/spec/agent.md @@ -131,3 +131,55 @@ sequenceDiagram SMP->>AB: MSG (HELLO) AB->>B: CON (connected) ``` + +### File delivery flow (XFTP) + +```mermaid +sequenceDiagram + participant SA as Sender App + + box Sender Agent + participant S as xftpSnd workers + participant SS as Store + end + + participant XFTP as XFTP Routers + participant SMP as SMP Router + + box Receiver Agent + participant RS as Store + participant R as xftpRcv workers + end + + participant RA as Receiver App + + SA->>S: xftpSendFile(file) + S->>S: encrypt file
(XSalsa20-Poly1305, random key + nonce) + S->>S: split into chunks
(fixed sizes: 64KB - 4MB) + S->>SS: store SndFile + chunks + + loop each chunk + S->>XFTP: FNEW (create data packet) + XFTP->>S: sender ID + recipient IDs + S->>XFTP: FPUT (upload encrypted chunk) + end + + S->>S: assemble FileDescription
(chunk locations, replicas,
encryption key + nonce) + S->>SA: SFDONE
(sender + recipient descriptions) + + Note over SA,RA: recipient description sent as
SMP message (encrypted, via double ratchet) + + SA->>SMP: description in A_MSG + SMP->>RA: description in MSG + + RA->>R: xftpReceiveFile(description) + R->>RS: store RcvFile + chunks + + loop each chunk (parallel per server) + R->>XFTP: FGET (per-recipient auth key) + XFTP->>R: encrypted chunk stream + end + + R->>R: stream chunks through
stateful decrypt (key + nonce),
verify auth tag at end + R->>RA: RFDONE (decrypted file path) +``` diff --git a/spec/diagrams/agent.svg b/spec/diagrams/agent.svg index 4b7bf802c..9ec32bf31 100644 --- a/spec/diagrams/agent.svg +++ b/spec/diagrams/agent.svg @@ -1,4 +1,4 @@ - + @@ -8,195 +8,239 @@ markerWidth="6" markerHeight="6" orient="auto-start-reverse"> + + + - - + - Application + Application - - API arrows (down) ===== --> + + + + + + - subQ + subQ - - + + + + sendMessage, createConnection + joinConnection, subscribe... + + + + xftpSendFile + xftpReceiveFile... + + + + registerNtfToken + toggleConnectionNtfs... + + + + + - main threads (raceAny_: any exit tears down all) + SMP - - + - subscriber - (reads msgQ) + subscriber + (reads msgQ) - - ntfSubQ - + + delivery + (per send queue) + + + + asyncCmd + (per connection) + + + + smpSub + (per session) + + + + XFTP + + + + xftpRcv + (per server + local) + + + + xftpSnd + (per server + local) + + + + xftpDel + (per server) + + + + NTF + + + + ntfSupervisor + (reads ntfSubQ) + + + + ntfWorkers + (per NTF server) + + + + ntfSMP + (per SMP server) + + + + ntfTknDel + (per NTF server) + + + + ntfSubQ - - ntfSubQ (ICQDelete) ===== --> + + ntfSubQ (queue rotation) + + + + ntfSMP uses smpClients + + + - ntfSupervisor - (reads ntfSubQ) + cleanupManager - - - cleanupManager - (periodic cleanup) + logServersStats - - - logServersStats - (periodic stats) + shared singletons (all green run in raceAny_) - - - worker pools (on-demand, one per queue/connection/server) + + + Store + (SQLite / Postgres) - - - delivery - (per send queue) + + Operation State + (5-op suspension cascade) - - asyncCmd - (per connection) - - - smpSub - (per session) - - - - xftpRcv - (per server) - - - xftpSnd - (per server) - - - xftpDel - (per server) - - - - ntfSMP - (per SMP server) - - - ntfWorkers - (per NTF server) - - - ntfTknDel - (per NTF server) - - - - ntf workers (dispatched by ntfSupervisor) - - - - - - - + - store + store - - - Store - (SQLite / Postgres) - - - currentSubs - (TSessionSubs) - - - Operation State - (5-op suspension cascade) - - - - protocol client pools (lazy singleton per router) - - + - smpClients - (TMap SMPTransportSession) + smpClients + (TMap SMPTransportSession) - - xftpClients - (TMap XFTPTransportSession) + xftpClients + (TMap XFTPTransportSession) - - ntfClients - (TMap NtfTransportSession) + ntfClients + (TMap NtfTransportSession) - - SMP Routers - + SMP Routers + - XFTP Routers - XFTP Routers + - NTF Routers - NTF Routers + - - msgQ + msgQ - - - on-demand worker + on-demand worker - - singleton thread + singleton thread - - storage / state + storage / state - - external connection + external connection - - Solid arrows: TBQueue connections. Dashed: store access / dispatch. Workers connect to protocol clients in their column. + + API entry point + + + cross-protocol + + + Solid arrows: TBQueue flow. Dashed grey: store access. Dashed red: cross-protocol link. Workers use clients in their column.