The Core Architecture Stack

Nube is implemented as a single-binary Go application utilizing the following technical layer architecture.

Layer 0: Crypto-Primitives & Identity

  • Hash Function: BLAKE3. Standard for Nube Content Identifiers (CIDs).

  • Encryption: XChaCha20-Poly1305 AEAD.

  • Identity: Ed25519 cryptographic keypairs for self-sovereign peer identification.

  • Traceability: Implements [FUNC-CORE-INTEGRITY] and [FUNC-SWARM-IDENTITY].

  • Identifier: [TECH-CRYPTO]

Layer 1: Content-Addressable Storage (CAS)

  • Chunking: FastCDC (Content-Defined Chunking). Cuts files into variable-sized chunks based on content boundaries.

  • Addressing: Content addressed by Blake3-hashed CIDs.

  • Integrity Validation: Every chunk is verified against its hash during ingestion.

  • Traceability: Implements [FUNC-CORE-DEDUPLICATION] and [FUNC-CORE-INTEGRITY].

  • Identifier: [TECH-BLOCKSTORE]

Layer 2: The Merkle Directed Acyclic Graph (DAG)

  • Serialization: Protocol Buffers (Protobuf).

  • Structure: Directories and files are represented as recursive Merkle DAG trees.

  • DOS Hardening: Node width limits (4096 links max) and node size limits (2MB max).

  • Traceability: Implements [FUNC-CORE-INTEGRITY].

  • Identifier: [TECH-MERKLE-DAG]

Layer 3: Metadata & Key-Value Persistence

  • Type: Delta-State Observed-Remove Set (OR-Set) Conflict-Free Replicated Data Types (CRDTs).

  • Persistence Store: BadgerDB for local personal deployments; configured for transactional safety.

  • Traceability: Implements [FUNC-SYNC-FABRIC] and [FUNC-DYNAMIC-SHARING].

  • Identifier: [TECH-METADATA-CRDT]

Layer 4: Transport Protocol & Discovery

  • Stack: libp2p over UDP/QUIC.

  • Discovery: Local mDNS broadcasts and global Kademlia DHT peer routing tables.

  • Messaging: Length-delimited Protobuf streams with a 2MB maximum limit.

  • Traceability: Implements [FUNC-P2P-DISCOVERY] and [FUNC-SYNC-FABRIC].

  • Identifier: [TECH-TRANSPORT]

Layer 5: Virtual Filesystem (FUSE)

  • FUSE Mount: Go FUSE API mapping filesystem syscalls (read, write, mkdir, rename, unlink) to Blockstore CAS and CRDT updates.

  • Traceability: Implements [FUNC-FUSE-MOUNT].

  • Identifier: [TECH-NATIVE-FUSE]

Layer 6: React Web Client & Local Server

  • Architecture: Local HTTP REST API served by the Go binary, communicating with a built Vite/React client using Lucide-React and TailwindCSS.

  • State Reactivity: Server-Sent Events (SSE) stream browser updates.

  • Traceability: Implements [FUNC-WUI-BROWSER].

  • Identifier: [TECH-WUI-DESKTOP]

Layer 7: Dynamic Share & Swarming Engine

  • Live Share Registry: Ephemeral key generation, signed DHT pointer records.

  • PubSub Live Sync: libp2p PubSub gossip network for live directory updates.

  • Swarming: Concurrently fetch block chunks from multiple DHT-resolved peers with configurable limits.

  • Quota Safety: Pre-flight space checks using system statfs calls.

  • Traceability: Implements [FUNC-DYNAMIC-SHARING], [FUNC-SWARM-SEEDING], and [FUNC-SWARM-SYNC].

  • Identifier: [TECH-SWARM-ENGINE]