# ipfs/kubo architecture

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

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

## Overview

##### Project type and key purpose
- Kubo is a complete implementation of IPFS written in Go. It functions as a network node that implements content addressing, distributed file storage, peer-to-peer networking (via libp2p and the DHT), and provides both a CLI and an HTTP/RPC API for interacting with the node.
- The project is not just a simple library—it is a full-stack network service that integrates networking, API gateways, command handling, and storage subsystems.

##### File structure to find main modules/components
- CLI and Entry Points:
- The “cmd” directory (e.g., cmd/ipfs) contains the main entry point for starting the daemon and the CLI.
- Core Functionality:
- The “core” directory (with subfolders like core/commands, core/coreapi, core/corehttp, and core/node) embodies the primary business logic. This includes:
- Command parsing and execution.
- API implementations such as the core API and HTTP gateway.
- Network protocols and interfaces interacting with libp2p.
- Configuration and Initialization:
- The “config” and “repo” directories manage system-wide settings, datastore configuration, and repository management.
- Networking and Peer Communication:
- Directories like “p2p”, “core/node/libp2p”, and “routing” indicate networking layers including DHT, peer discovery, and routing protocols.
- Plugin Architecture:
- The “plugin” directory evidences a modular and extensible design, enabling support for additional functionality (such as alternative datastore implementations).
- Additional Functionality:
- Components related to UnixFS (“client/rpc/unixfs.go”, “core/coreiface/unixfs.go”), block handling (“blocks”), and mounting via Fuse (“fuse”) also exist.
- Testing and Integration:
- The “test” directory (with subfolders for unit, integration, and sharness tests) shows the emphasis on designing for reliability and verifying interactions between modules.

##### Out the high-level system components
a. Frontend Components:
- Command-Line Interface (CLI) that initiates commands and interacts with the HTTP API.
- WebUI (although maintained separately, it interfaces with the node via the API).
b. Backend/Daemon Components:
- IPFS Daemon: The running node that supports both command execution and background tasks.
- Core API Server: Implements the HTTP RPC API (located in core/corehttp) for remote procedure calls (e.g., to add files, query the network, etc.).
c. Networking & P2P Stack:
- libp2p-based networking layer handling DHT, peer discovery, and data routing.
- Bitswap engine for data trading between peers.
d. Data Storage & Repository Management:
- The datastore and file repository managed under “repo” that store the content-addressable files.
e. Plugins and Extensibility:
- The plugin system which allows alternative backend storage or custom protocols.
f. Auxiliary Services:
- Gateway HTTP server endpoints (for the /ipfs and /ipns routes).
- Diagnostic, logging, and monitoring (e.g., metrics in core/corehttp/metrics.go).

##### How these components interact
- The CLI sends commands to the daemon either directly or via the HTTP/RPC API.
- The daemon routes the command to core modules, which in turn interact with the underlying storage (repo), network (libp2p stack), and other subsystems.
- For web requests, the HTTP gateway accepts external requests, validates them, and translates them into internal core API calls.
- Plugins hook into these pathways to extend capabilities (e.g., to support new datastore types).

##### Architectural design patterns
- Layered Architecture: Separate presentation (CLI/API), business logic (core modules), and data storage (repo) layers.
- Modular Design: Each subsystem (networking, storage, command processing) exists in its own module or package.
- Plug-in extensibility: Use of dynamic loading to support various plugins.
- Clear separation between client-side logic (e.g., in “client/rpc”) and daemon/server-side code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Interfaces
    subgraph "Frontend Interfaces"
        CLI["CLI (Entry Point)"]:::external
        HTTP["HTTP API Gateway"]:::external
        WebUI["WebUI Interface"]:::external
    end

    %% Backend Daemon
    subgraph "Backend Service"
        Daemon["IPFS Daemon/Node"]:::backend
    end

    %% Internal Subsystems
    subgraph "Subsystems"
        Core["Core Services (Command Parsing & Core API)"]:::internal
        Networking["Libp2p Networking (DHT, Bitswap)"]:::networking
        Storage["Data Storage (Repo & Config)"]:::storage
        Plugins["Plugin Manager"]:::plugin
        UnixFS_Client["UnixFS Client Support"]:::auxiliary
        UnixFS_Core["UnixFS Core Support"]:::auxiliary
        Blocks["Block Handling"]:::auxiliary
        Fuse["Fuse Mounting Service"]:::auxiliary
    end

    %% Testing Module
    Testing["Testing & Integration"]:::testing

    %% Connections from Frontend to Backend
    CLI -->|"sendsCommand"| Daemon
    HTTP -->|"apiRequest"| Daemon
    WebUI -->|"viaAPI"| HTTP

    %% Internal routing from Daemon to core subsystems
    Daemon -->|"executes"| Core
    Core -->|"handlesNetwork"| Networking
    Core -->|"accessesStorage"| Storage
    Core -->|"invokesPlugin"| Plugins
    Core -->|"processesUnixFS"| UnixFS_Client
    Core -->|"processesUnixFS"| UnixFS_Core
    Core -->|"managesBlocks"| Blocks
    Core -->|"mountsFuse"| Fuse

    %% Testing interacts with the Daemon
    Testing ---|"validates"| Daemon

    %% Click Events for Component Mapping
    click CLI "https://github.com/ipfs/kubo/tree/master/cmd/ipfs"
    click Core "https://github.com/ipfs/kubo/tree/master/core"
    click Storage "https://github.com/ipfs/kubo/tree/master/repo"
    click Networking "https://github.com/ipfs/kubo/tree/master/core/node/libp2p"
    click Networking "https://github.com/ipfs/kubo/tree/master/p2p"
    click Plugins "https://github.com/ipfs/kubo/tree/master/plugin"
    click UnixFS_Client "https://github.com/ipfs/kubo/blob/master/client/rpc/unixfs.go"
    click UnixFS_Core "https://github.com/ipfs/kubo/blob/master/core/coreiface/unixfs.go"
    click Blocks "https://github.com/ipfs/kubo/tree/master/blocks"
    click Fuse "https://github.com/ipfs/kubo/tree/master/fuse"
    click Testing "https://github.com/ipfs/kubo/tree/master/test"

    %% Styles
    classDef external fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef backend fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef internal fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef networking fill:#AFEEEE,stroke:#20B2AA,stroke-width:2px;
    classDef storage fill:#FFFACD,stroke:#BDB76B,stroke-width:2px;
    classDef plugin fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef auxiliary fill:#FFE4E1,stroke:#CD5C5C,stroke-width:2px;
    classDef testing fill:#F0E68C,stroke:#BDB76B,stroke-width:2px;
```
