# zaygal/zaycomm architecture

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

- Interactive diagram: https://gitdiagram.com/zaygal/zaycomm
- Repository: https://github.com/zaygal/zaycomm

## Overview

#### Purpose and Entry Surface
Zaycomm is a TypeScript reference implementation of a secure, decentralized, delay-tolerant mesh messaging protocol. It is protocol infrastructure rather than a web application: messages remain end-to-end encrypted while moving across untrusted relays and intermittent transports. No executable entry point is visible in the tree; the public integration surface is likely the exported modules under `src/`, with package behavior defined by `package.json`.

#### Identity and Cryptographic Sessions
Long-lived identity material, device identity operations, and verification live in `src/identity/identity.ts` and `src/crypto/keys.ts`. Session establishment and ongoing forward-secret messaging are separated into `src/crypto/handshake.ts` and `src/crypto/ratchet.ts`. This boundary is security-critical: endpoints own private keys and ratchet state; relays should only handle opaque envelopes.

#### Message Construction and Content Types
Application payloads are represented by `src/message/message.ts`, with file-oriented payload/chunk handling in `src/message/file.ts`. These feed encrypted session payloads and can support extensible types such as broadcast. `src/broadcast/broadcast.ts` is the distinct broadcast path, likely applying different dissemination semantics from ordinary destination-directed messages.

#### Envelope and Fragmentation Boundary
`src/envelope/envelope.ts` defines the transportable protocol unit: relay-visible routing/control metadata plus a sealed payload for the recipient. `src/envelope/fragment.ts` splits and reassembles envelopes for constrained links. This is the key boundary between routing/transport behavior and cryptographic confidentiality: relays validate, deduplicate, forward, or queue envelopes without decrypting content.

#### Routing and Store-Carry-Forward
`src/routing/routing.ts` selects forwarding behavior across direct, multi-hop, and disconnected contacts. It should use message identifiers, TTL/freshness, relay knowledge, and bounded replication to avoid loops and uncontrolled flooding. When no suitable next hop exists, control passes to `src/storage/store.ts`, which persists local state and encrypted relay queues until contact, expiry, acknowledgment, or eviction.

#### Transport Abstraction
`src/transport/transport.ts` is the pluggable link boundary. Transports discover reachable peers and exchange bounded opaque frames; higher layers should not depend on BLE, Wi-Fi, Internet, radio, or physical-carry specifics. This permits gateway/synchronization behavior without requiring central infrastructure and makes a new transport adapter an additive change rather than a protocol rewrite.

#### Primary Control Flow and Trust Boundaries
Outbound flow is: construct message (`src/message/message.ts`) → establish/use crypto session (`src/crypto/handshake.ts`, `src/crypto/ratchet.ts`) → seal into envelope (`src/envelope/envelope.ts`) → fragment if required (`src/envelope/fragment.ts`) → choose next hop (`src/routing/routing.ts`) → transmit (`src/transport/transport.ts`) or queue (`src/storage/store.ts`). At relay nodes, only envelope, routing, transport, and queued ciphertext are processed. At the destination, fragments are reassembled, the envelope is decrypted/authenticated through session state, and the payload is delivered to message or broadcast handling.

#### Runtime and External Dependencies
The codebase is Node/TypeScript-oriented, indicated by `package.json` and `package-lock.json`; no deployed service, database, browser runtime, or mandatory external infrastructure is present in the repository tree. Internet-connected peers are conceptually optional gateways, not protocol authorities. Shared low-level behavior is centralized in `src/util.ts`.

Main entry points: [`src/envelope/envelope.ts`](https://github.com/zaygal/zaycomm/blob/main/src/envelope/envelope.ts) (Sealed envelope), [`src/routing/routing.ts`](https://github.com/zaygal/zaycomm/blob/main/src/routing/routing.ts) (Forwarding policy), [`src/crypto/ratchet.ts`](https://github.com/zaygal/zaycomm/blob/main/src/crypto/ratchet.ts) (Forward-secret ratchet), [`src/envelope/fragment.ts`](https://github.com/zaygal/zaycomm/blob/main/src/envelope/fragment.ts) (Fragmentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_endpoint["Endpoint security"]
  node_identity["Device identity<br/>[identity.ts]"]
  node_keys["Key operations<br/>cryptography<br/>[keys.ts]"]
  node_handshake["Session handshake<br/>session setup<br/>[handshake.ts]"]
  node_ratchet["Forward-secret ratchet<br/>session crypto<br/>[ratchet.ts]"]
  node_destination(("Destination endpoint<br/>protocol role"))
end

subgraph group_payload["Payloads"]
  node_message["Application message<br/>payload model<br/>[message.ts]"]
  node_file["File payloads<br/>content chunks<br/>[file.ts]"]
  node_broadcast["Broadcast handling<br/>dissemination payload<br/>[broadcast.ts]"]
end

subgraph group_relay["Opaque relay pipeline"]
  node_envelope["Sealed envelope<br/>protocol unit<br/>[envelope.ts]"]
  node_fragment["Fragmentation<br/>frame adaptation<br/>[fragment.ts]"]
  node_routing["Forwarding policy<br/>routing<br/>[routing.ts]"]
  node_transport["Transport abstraction<br/>peer link interface<br/>[transport.ts]"]
  node_store[("Store-carry-forward<br/>encrypted queue<br/>[store.ts]")]
end

node_package["Package surface<br/>Node/TypeScript package<br/>[package.json]"]
node_util["Shared utilities<br/>common support<br/>[util.ts]"]

node_package -->|"exports"| node_identity
node_identity -->|"uses"| node_keys
node_keys -->|"establishes identity-backed session"| node_handshake
node_handshake -->|"initializes"| node_ratchet
node_message -->|"supports"| node_file
node_message -->|"payload to encrypt"| node_ratchet
node_file -->|"payload to encrypt"| node_ratchet
node_ratchet -->|"sealed payload"| node_envelope
node_broadcast -->|"dissemination envelope"| node_envelope
node_envelope -->|"split when needed"| node_fragment
node_fragment -->|"bounded frames"| node_routing
node_routing -->|"next-hop transmit"| node_transport
node_routing -->|"defer without contact"| node_store
node_store -.->|"retry on contact"| node_routing
node_transport -.->|"received frames"| node_fragment
node_fragment -.->|"reassembled envelope"| node_envelope
node_envelope -->|"authenticated sealed content"| node_destination
node_destination -.->|"decrypts via session state"| node_ratchet
node_destination -->|"delivers directed payload"| node_message
node_destination -->|"delivers broadcast payload"| node_broadcast
node_util -.->|"shared low-level support"| node_envelope
node_util -.->|"shared low-level support"| node_routing

click node_package "https://github.com/zaygal/zaycomm/blob/main/package.json"
click node_identity "https://github.com/zaygal/zaycomm/blob/main/src/identity/identity.ts"
click node_keys "https://github.com/zaygal/zaycomm/blob/main/src/crypto/keys.ts"
click node_handshake "https://github.com/zaygal/zaycomm/blob/main/src/crypto/handshake.ts"
click node_ratchet "https://github.com/zaygal/zaycomm/blob/main/src/crypto/ratchet.ts"
click node_message "https://github.com/zaygal/zaycomm/blob/main/src/message/message.ts"
click node_file "https://github.com/zaygal/zaycomm/blob/main/src/message/file.ts"
click node_broadcast "https://github.com/zaygal/zaycomm/blob/main/src/broadcast/broadcast.ts"
click node_envelope "https://github.com/zaygal/zaycomm/blob/main/src/envelope/envelope.ts"
click node_fragment "https://github.com/zaygal/zaycomm/blob/main/src/envelope/fragment.ts"
click node_routing "https://github.com/zaygal/zaycomm/blob/main/src/routing/routing.ts"
click node_transport "https://github.com/zaygal/zaycomm/blob/main/src/transport/transport.ts"
click node_store "https://github.com/zaygal/zaycomm/blob/main/src/storage/store.ts"
click node_util "https://github.com/zaygal/zaycomm/blob/main/src/util.ts"

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_identity,node_keys,node_handshake,node_ratchet,node_destination toneBlue
class node_message,node_file,node_broadcast toneAmber
class node_envelope,node_fragment,node_routing,node_transport,node_store toneMint
class node_package,node_util toneNeutral
```

## Components

### Endpoint security

Private identity and session state stay at endpoints.

- [Device identity](https://github.com/zaygal/zaycomm/blob/main/src/identity/identity.ts): identity · `src/identity/identity.ts`
- [Key operations](https://github.com/zaygal/zaycomm/blob/main/src/crypto/keys.ts): cryptography · `src/crypto/keys.ts`
- [Session handshake](https://github.com/zaygal/zaycomm/blob/main/src/crypto/handshake.ts): session setup · `src/crypto/handshake.ts`
- [Forward-secret ratchet](https://github.com/zaygal/zaycomm/blob/main/src/crypto/ratchet.ts): session crypto · Encrypts and authenticates ongoing session payloads. · `src/crypto/ratchet.ts`
- **Destination endpoint**: protocol role · Reassembles, authenticates, decrypts, and delivers payloads.

### Payloads

- [Application message](https://github.com/zaygal/zaycomm/blob/main/src/message/message.ts): payload model · `src/message/message.ts`
- [File payloads](https://github.com/zaygal/zaycomm/blob/main/src/message/file.ts): content chunks · `src/message/file.ts`
- [Broadcast handling](https://github.com/zaygal/zaycomm/blob/main/src/broadcast/broadcast.ts): dissemination payload · Uses semantics distinct from destination-directed delivery. · `src/broadcast/broadcast.ts`

### Opaque relay pipeline

Relays route and store sealed envelopes without decrypting them.

- [Sealed envelope](https://github.com/zaygal/zaycomm/blob/main/src/envelope/envelope.ts): protocol unit · Combines relay-visible metadata with recipient-only sealed content. · `src/envelope/envelope.ts`
- [Fragmentation](https://github.com/zaygal/zaycomm/blob/main/src/envelope/fragment.ts): frame adaptation · Splits and reassembles envelopes for constrained links. · `src/envelope/fragment.ts`
- [Forwarding policy](https://github.com/zaygal/zaycomm/blob/main/src/routing/routing.ts): routing · Selects direct, multi-hop, or deferred forwarding. · `src/routing/routing.ts`
- [Transport abstraction](https://github.com/zaygal/zaycomm/blob/main/src/transport/transport.ts): peer link interface · Exchanges bounded opaque frames over pluggable transports. · `src/transport/transport.ts`
- [Store-carry-forward](https://github.com/zaygal/zaycomm/blob/main/src/storage/store.ts): encrypted queue · Persists local state and queued ciphertext until delivery or eviction. · `src/storage/store.ts`

### Other components

- [Package surface](https://github.com/zaygal/zaycomm/blob/main/package.json): Node/TypeScript package · Defines package behavior and exported integration surface. · `package.json`
- [Shared utilities](https://github.com/zaygal/zaycomm/blob/main/src/util.ts): common support · `src/util.ts`

## Connections

- Package surface → Device identity: exports
- Device identity → Key operations: uses
- Key operations → Session handshake: establishes identity-backed session
- Session handshake → Forward-secret ratchet: initializes
- Application message → File payloads: supports
- Application message → Forward-secret ratchet: payload to encrypt
- File payloads → Forward-secret ratchet: payload to encrypt
- Forward-secret ratchet → Sealed envelope: sealed payload
- Broadcast handling → Sealed envelope: dissemination envelope
- Sealed envelope → Fragmentation: split when needed
- Fragmentation → Forwarding policy: bounded frames
- Forwarding policy → Transport abstraction: next-hop transmit
- Forwarding policy → Store-carry-forward: defer without contact
- Store-carry-forward → Forwarding policy: retry on contact
- Transport abstraction → Fragmentation: received frames
- Fragmentation → Sealed envelope: reassembled envelope
- Sealed envelope → Destination endpoint: authenticated sealed content
- Destination endpoint → Forward-secret ratchet: decrypts via session state
- Destination endpoint → Application message: delivers directed payload
- Destination endpoint → Broadcast handling: delivers broadcast payload
- Shared utilities → Sealed envelope: shared low-level support
- Shared utilities → Forwarding policy: shared low-level support