# wnfs-wg/rs-wnfs architecture

> Architecture diagram of the GitHub repository wnfs-wg/rs-wnfs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wnfs-wg/rs-wnfs
- Repository: https://github.com/wnfs-wg/rs-wnfs

## Overview

##### Project Type and Purpose
- This is a multi‐crate Rust library (an open‐source tool) implementing the WebNative FileSystem (WNFS) spec.
- It provides both a native Rust API (crate “wnfs”) and WebAssembly bindings (“wnfs‐wasm”), plus related core libraries (“wnfs‐common”, “wnfs‐hamt”, “wnfs‐nameaccumulator”, “wnfs‐unixfs‐file”).
- It’s content‐addressable, versioned, supports private (encrypted) and public (unencrypted) filesystems, with pluggable BlockStore backends and collaborative editing.

##### High‐Level File/Crate Structure
Top-level crates and folders:
– wnfs            : main Rust crate exposing public/private FS APIs
– wnfs‐wasm       : wasm‐bindgen wrapper for browser/JS usage
– wnfs‐common     : shared traits & utilities (BlockStore trait, encoding, errors)
– wnfs‐hamt       : Hash Array Mapped Trie implementation for private forests
– wnfs‐nameaccumulator : name‐accumulator logic for proof generation
– wnfs‐unixfs‐file    : UnixFS file chunking & balanced‐tree builder
– wnfs‐bench      : benchmarking harness
– scripts, examples, tests, CI config

##### Core Architectural Components
- “BlockStore” trait (wnfs‐common) – abstract storage interface (in‐memory, IPFS, etc.)
- PublicDirectory / PublicFile (wnfs) – unencrypted filesystem tree, serializes to IPLD
- PrivateDirectory / PrivateFile (wnfs) – encrypted, stored inside a PrivateForest (HAMT)
- HamtForest (wnfs‐hamt) – HAMT‐based key→CID map for private FS nodes
- NameAccumulator (wnfs‐nameaccumulator) – per‐node naming & proof metadata
- UnixFsFileBuilder (wnfs‐unixfs‐file) – chunker, balanced tree, codecs for file contents
- Wasm glue (wnfs‐wasm) – binds PublicDirectory, PrivateDirectory, BlockStore to JS/TS

##### Relationships & Data Flow
– User code (Rust or JS) uses PublicDirectory / PrivateDirectory APIs.
– On write/mkdir: FS API calls into directory node modules, which:
- public: builds IPLD DAG nodes → BlockStore.put()
- private: encrypts data → HamtForest.insert(key, cid) → BlockStore.put()
– Directory ls/read: retrieves CIDs via HAMT or links, decodes from BlockStore.
– NameAccumulator tracks node names through edits for proof generation.
– UnixFS file operations use chunkers to split data, then store chunks in BlockStore.

##### Architectural Patterns & Principles
– Clean separation by crate: core traits (wnfs‐common) → data structures (hamt, nameacc) → high‐level API (wnfs) → language binding (wnfs‐wasm)
– Trait‐based abstractions (BlockStore, PrivateForest) for pluggable backends
– Content‐addressable design: CIDs as keys in HAMT and public links
– Functional, immutable‐style edits via Rc<…> wrappers for easy rollback & collaboration
– Modular UnixFS chunking and codecs for file content

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Traits Layer
    subgraph "Core Traits Layer"
        direction TB
        BS["BlockStore Trait"]:::coreTraits
    end

    %% Data Structures Layer
    subgraph "Data Structures Layer"
        direction TB
        HF["HamtForest"]:::dataStruct
        NA["NameAccumulator"]:::dataStruct
        UB["UnixFsFileBuilder"]:::dataStruct
    end

    %% API Layer
    subgraph "High-Level API (wnfs)"
        direction TB
        PD["PublicDirectory"]:::api
        PF["PublicFile"]:::api
        PrD["PrivateDirectory"]:::api
        PrF["PrivateFile"]:::api
    end

    %% Wasm Layer
    subgraph "WASM Bindings (wnfs-wasm)"
        direction TB
        WG["wasm-bindgen Glue"]:::wasm
        WPD["WASM PublicDirectory"]:::wasm
        WPF["WASM PublicFile"]:::wasm
        WPrD["WASM PrivateDirectory"]:::wasm
        WPrF["WASM PrivateFile"]:::wasm
        WBS["WASM BlockStore Stub"]:::wasm
    end

    %% External Dependencies
    Chrono["Chrono"]:::external
    Rand["rand"]:::external
    WasmBindGen["wasm-bindgen"]:::external
    IPLD["IPLD Graph"]:::external

    %% Dependencies
    PD -->|depends on| BS
    PF -->|depends on| BS
    PrD -->|depends on| HF
    PrD -->|depends on| BS
    PrF -->|depends on| HF
    PrF -->|depends on| BS
    HF -->|depends on| BS
    NA -->|depends on| BS
    UB -->|depends on| BS

    %% Crate Dependencies
    PD -->|depends on| NA
    PF -->|depends on| NA
    PD -->|depends on| HF
    PF -->|depends on| HF

    %% Layer Dependencies
    PD -->|depends on| UB
    PF -->|depends on| UB

    %% Wasm dependencies
    WG -->|depends on| PD
    WG -->|depends on| PrD
    WG -->|depends on| BS
    WG -->|depends on| NA

    WPD -->|wraps| PD
    WPF -->|wraps| PF
    WPrD -->|wraps| PrD
    WPrF -->|wraps| PrF
    WBS -->|implements| BS

    %% Data Flows
    PD -.->|dashed| BS
    PrD -.->|dashed| HF
    HF -.->|dashed| BS
    UB -.->|dashed| BS

    %% External to API
    Chrono --> PD
    Chrono --> PrD
    Rand --> PD
    Rand --> PrD
    WasmBindGen --> WG
    IPLD --> PD
    IPLD --> PF

    %% Click Events
    click BS "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-common/src/blockstore.rs"
    click PD "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs/src/public/directory.rs"
    click PF "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs/src/public/file.rs"
    click PrD "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs/src/private/directory.rs"
    click PrF "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs/src/private/file.rs"
    click HF "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-hamt/src/hamt.rs"
    click NA "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-nameaccumulator/src/lib.rs"
    click UB "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-unixfs-file/src/builder.rs"
    click WG "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/lib.rs"
    click WPD "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/fs/public/directory.rs"
    click WPF "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/fs/public/file.rs"
    click WPrD "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/fs/private/directory.rs"
    click WPrF "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/fs/private/file.rs"
    click WBS "https://github.com/wnfs-wg/rs-wnfs/blob/main/wnfs-wasm/src/fs/blockstore.rs"

    %% Styles
    classDef coreTraits fill:#ADD8E6,stroke:#000;
    classDef dataStruct fill:#90EE90,stroke:#000;
    classDef api fill:#FFA500,stroke:#000;
    classDef wasm fill:#DDA0DD,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
