# ipfs/boxo architecture

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

- Interactive diagram: https://gitdiagram.com/ipfs/boxo
- Repository: https://github.com/ipfs/boxo

## Overview

##### Project type and purpose
- This is a monorepo for Boxo, an IPFS SDK in Go. It provides a suite of libraries (Bitswap, BlockService, Blockstore, IPLD, UnixFS, Routing, Gateway, IPNS, Pinning, etc.) plus CLI tools and examples to build IPFS-aware applications or reimplement IPFS features.

##### File structure
- Top-level packages represent major functional domains:
– network & exchange: bitswap, exchange, provider, routing
– storage & retrieval: blockservice, blockstore, datastore, filestore, fetcher
– content addressing & data models: ipld/merkledag, ipld/unixfs, chunker, verifcid
– naming & mutability: ipns, namesys, path
– utilities & supporting: keystore, mfs, files, tar, tracing, util
– façade & integration: gateway, cmd (boxo-migrate, deprecator), examples
- There are also internal packages for private helpers, tests, and build/deployment pipelines (.github/workflows).

##### README for additional insights
- The README emphasizes Boxo as a “component library” for IPFS in Go, powering Kubo.
- It lists major protocol components (DHT, Bitswap, Gateway, IPNS, etc.) that should be represented.

1. Application Layer (your custom app or CLI commands)
2. Boxo SDK façade
3. Core modules:
- Content Routing (namesys, routing/http, routing/offline)
- Data Transfer (bitswap + network interface)
- BlockService & Blockstore (blockservice ↔ blockstore ↔ datastore)
- IPLD + UnixFS (ipld/merkledag, ipld/unixfs, chunker)
- Naming (ipns)
- Pinning (pinning/pinner, pinning/remote)
- Provider & Reprovider (provider queue)
4. Gateway HTTP Layer (gateway, assets, handler)
5. CLI Tools (cmd/boxo-migrate, cmd/deprecator)
6. Examples (examples/*)
7. External Dependencies:
- IPFS network peers (DHT, Bitswap, HTTP Gateway)
- Underlying datastore (LevelDB, Badger, etc.)
- Clients or other Go modules

b. Relationships & interactions:
– App Layer → Boxo façade API calls
– Façade → Core modules by import/injection
– Content Retrieval: Façade → bitswap → network interface → remote peers → bitswap → blockservice → ipld → unixfs → application
– Content Storage: App → blockservice → blockstore → datastore
– Routing: Façade → routing/http or DHT module → peer discovery
– Naming: App → ipns → namesys → DHT
– Pinning: App → pinner → blockstore
– Gateway: HTTP requests → gateway handlers → blockservice + ipld/unixfs → HTTP responses
– CLI: uses Boxo libraries same as App

c. Architectural patterns/ principles:
– Modular plugin-like packages, each focused on one IPFS protocol or service
– Clear separation of concerns (transport vs. data vs. naming)
– Interfaces for offline vs. online implementations (exchange/interface, routing/interface)
– Dependency injection: network, datastore, tracing exporters

d. Key technologies/frameworks:
– Go modules + pkg structure
– Protobuf for message definitions (bitswap, ipld, ipns)
– HTTP for gateway and delegated routing
– gRPC-style interfaces (routing HTTP client)
– Testing harnesses & benchmarks

##### Detailed capture of essential elements
Layer 1: App / CLI / Examples
Layer 2: Boxo façade & CLI commands
Layer 3: Protocol modules (routing, bitswap, ipns, provider, pinning)
Layer 4: Data layers (blockservice, blockstore, datastore, ipld/unixfs)
Layer 5: External systems (IPFS peers, DHT, HTTP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Applications
    subgraph "Layer 1: Applications" 
        direction TB
        App["Custom Application"]:::frontend
        CLI1["CLI: boxo-migrate"]:::frontend
        CLI2["CLI: deprecator"]:::frontend
        Examples["Examples"]:::frontend
    end

    %% Layer 2: Facade
    subgraph "Layer 2: Boxo SDK Façade"
        direction TB
        BoxoFacade["Boxo SDK Facade"]:::facade
    end

    %% Layer 3: Protocol Modules
    subgraph "Layer 3: Protocol Modules"
        direction TB
        bitswap["Bitswap"]:::module
        routingHttp["Routing HTTP"]:::module
        routingOffline["Routing Offline"]:::module
        ipns["IPNS"]:::module
        namesys["Namesys"]:::module
        provider["Provider & Reprovider"]:::module
        exchangeOffline["Exchange Offline"]:::module
        pinner["Pinning: Pinner"]:::module
        pinnerRemote["Pinning: Remote"]:::module
        fetcher["Fetcher"]:::module
        chunker["Chunker"]:::module
        verifcid["Verifcid"]:::module
    end

    %% Layer 4: Data Layers
    subgraph "Layer 4: Data Layers"
        direction TB
        blockservice["BlockService"]:::data
        blockstore["Blockstore"]:::data
        datastore["Datastore"]:::data
        filestore["Filestore"]:::data
        merkledag["IPLD Merkle DAG"]:::data
        unixfs["IPLD UnixFS"]:::data
    end

    %% Layer 5: External Systems
    subgraph "Layer 5: External Systems"
        direction TB
        IPFSNetwork["IPFS Network Peers"]:::external
        DHT["DHT"]:::external
        HTTPGateway["HTTP Gateway Service"]:::external
        UnderlyingDS["Underlying Datastore"]:::external
    end

    %% Utilities/Internal
    subgraph "Internal Utilities"
        direction TB
        util["Util"]:::util
        tracing["Tracing"]:::util
        keystore["Keystore"]:::util
        mfs["MFS"]:::util
        files["Files"]:::util
        tar["Tar"]:::util
        path["Path Resolver"]:::util
        peering["Peering"]:::util
    end

    %% CLI & Examples to Facade
    App -->|uses| BoxoFacade
    CLI1 -->|uses| BoxoFacade
    CLI2 -->|uses| BoxoFacade
    Examples -->|uses| BoxoFacade

    %% Facade to Modules
    BoxoFacade --> bitswap
    BoxoFacade --> routingHttp
    BoxoFacade --> routingOffline
    BoxoFacade --> ipns
    BoxoFacade --> namesys
    BoxoFacade --> provider
    BoxoFacade --> exchangeOffline
    BoxoFacade --> pinner
    BoxoFacade --> pinnerRemote
    BoxoFacade --> fetcher
    BoxoFacade --> chunker
    BoxoFacade --> verifcid

    %% Data flows
    bitswap -->|fetches blocks| blockservice
    bitswap -->|sync| IPFSNetwork
    blockservice --> blockstore
    blockstore --> datastore
    blockstore --> filestore
    blockservice --> merkledag
    merkledag --> unixfs
    unixfs --> chunker

    %% Naming and Routing
    ipns --> namesys
    namesys --> DHT
    provider --> DHT
    exchangeOffline --> provider

    %% Pinning
    pinner --> blockstore
    pinnerRemote -->|remote API| blockstore

    %% Gateway
    HTTPGateway -->|HTTP requests| gatewayHandler["Gateway Handler"]:::module
    gatewayHandler --> blockservice
    gatewayHandler --> unixfs

    %% Utilities usage
    BoxoFacade --> util
    BoxoFacade --> tracing
    BoxoFacade --> keystore
    BoxoFacade --> mfs
    BoxoFacade --> files
    BoxoFacade --> tar
    BoxoFacade --> path
    BoxoFacade --> peering

    %% External datastore
    datastore --> UnderlyingDS

    %% Click Events
    click bitswap "https://github.com/ipfs/boxo/tree/main/bitswap/"
    click blockservice "https://github.com/ipfs/boxo/tree/main/blockservice/"
    click blockstore "https://github.com/ipfs/boxo/tree/main/blockstore/"
    click datastore "https://github.com/ipfs/boxo/tree/main/datastore/"
    click merkledag "https://github.com/ipfs/boxo/tree/main/ipld/merkledag/"
    click unixfs "https://github.com/ipfs/boxo/tree/main/ipld/unixfs/"
    click chunker "https://github.com/ipfs/boxo/tree/main/chunker/"
    click ipns "https://github.com/ipfs/boxo/tree/main/ipns/"
    click namesys "https://github.com/ipfs/boxo/tree/main/namesys/"
    click path "https://github.com/ipfs/boxo/tree/main/path/"
    click routingHttp "https://github.com/ipfs/boxo/tree/main/routing/http/"
    click routingOffline "https://github.com/ipfs/boxo/tree/main/routing/offline/"
    click provider "https://github.com/ipfs/boxo/tree/main/provider/"
    click exchangeOffline "https://github.com/ipfs/boxo/tree/main/exchange/offline/"
    click fetcher "https://github.com/ipfs/boxo/tree/main/fetcher/"
    click files "https://github.com/ipfs/boxo/tree/main/files/"
    click filestore "https://github.com/ipfs/boxo/tree/main/filestore/"
    click tar "https://github.com/ipfs/boxo/tree/main/tar/"
    click keystore "https://github.com/ipfs/boxo/tree/main/keystore/"
    click mfs "https://github.com/ipfs/boxo/tree/main/mfs/"
    click pinner "https://github.com/ipfs/boxo/tree/main/pinning/pinner/"
    click pinnerRemote "https://github.com/ipfs/boxo/tree/main/pinning/remote/"
    click peering "https://github.com/ipfs/boxo/tree/main/peering/"
    click gatewayHandler "https://github.com/ipfs/boxo/tree/main/gateway/"
    click tracing "https://github.com/ipfs/boxo/tree/main/tracing/"
    click util "https://github.com/ipfs/boxo/tree/main/util/"
    click verifcid "https://github.com/ipfs/boxo/tree/main/verifcid/"
    click CLI1 "https://github.com/ipfs/boxo/tree/main/cmd/boxo-migrate/"
    click CLI2 "https://github.com/ipfs/boxo/tree/main/cmd/deprecator/"
    click Examples "https://github.com/ipfs/boxo/tree/main/examples/"

    %% Styles
    classDef frontend fill:#FFDDAA,stroke:#333,stroke-width:1px
    classDef facade fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef module fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef data fill:#FFCCFF,stroke:#333,stroke-width:1px
    classDef external fill:#EEEECC,stroke:#333,stroke-width:1px
    classDef util fill:#FFF2CC,stroke:#333,stroke-width:1px
```
