Architecture

UNC file sharing is structured around three actors:

  • hubs — catalog nodes
  • sharers — clients that publish file metadata and serve files
  • searchers — clients that query hubs and fetch files

A single machine can be more than one of these at the same time.

The core loop

  1. A client indexes a shared folder.
  2. Each file gets a content ID: sha256:<hex>.
  3. The client registers file metadata with a hub.
  4. Another client searches the hub.
  5. The hub returns matching files and known peer locations.
  6. The downloading client opens a Reticulum link to the uploading client's fetch destination.
  7. The file transfers directly between clients.

Hub layer

The hub exposes a Reticulum destination for catalog actions such as:

  • search
  • metadata lookup
  • file registration
  • presence update
  • peer listing
  • download redirect / fetch-location lookup

The hub stores catalog data in SQLite. It knows which peer claims to host which file, and which fetch destination should be dialed to retrieve it.

Fetch layer

File transfer is peer-to-peer. The downloading client connects to the uploading client's pubshare.fetch destination.

The transfer uses RNS.Link and RNS.Resource, letting Reticulum handle larger payload sequencing, integrity, and reassembly.

After the resource transfer completes, the downloading side verifies the received payload against the declared sha256:<hex> file ID before marking the transfer verified.

Local state

Clients keep their own SQLite state for:

  • local files
  • known peers
  • transfer jobs
  • search cache

The client and hub are separate processes with separate databases. They communicate over Reticulum links, not shared process memory.

Federation direction

Hub-to-hub catalog sync is moving toward a leaderless pull model using origin counters and version vectors.

The practical idea:

  • each hub is authoritative for its own writes
  • peer hubs pull deltas
  • catalogs converge over time
  • availability metadata may become stale under high-latency links, so it should be treated as a signal rather than absolute truth

This makes UNC a useful testbed for federated content-addressable catalogs over heterogeneous and delay-tolerant networks.