# Basic Concepts

Wildland is a protocol for managing storage infrastructure for keeping user files. This section introduces the basic concepts related to Wildland.

# Wildand CoreX

Wildland CoreX is a core library that aims to provide a cross-platform toolbox for developing software utilizing the Wildland protocol.

# Wildland CoreX as a platform

Wildland CoreX consists of several specialized modules, providing low level Wildland abstractions. While those modules could be directly used to build applications on top of Wildland - and this can be used to implement different use cases on top of Wildland - it is envisioned that more high level APIs can be provided in order to enable easier implementation of specific use cases. It is convenient to be able to see a collection of such APIs as a client software facing module on the abstract level, or as a Wildland SDK on the concrete level.

You can find a dedicated document discussing abstract Wildland client architecture.

To track our work on the client software which is planned to implement some of Wildland's use cases, see the Wildland Cargo (opens new window) project. Wildland CoreX provides a dedicated client software facing module for Cargo development -- CargoLib.

# Containers (for keeping data)

The Data Container is a fundamental concept in Wildland. It roughly resembles a familiar notion of a folder or volume in traditional operating systems (although they can also represent a single file).

A container stores user data. This data is physically stored on one or more storage backends, allowing replication if needed, potentially on heterogeneous storage infrastructure.

This means that containers constitute basic units which can be managed by Wildland in terms of storage management, sharing, replication, and addressing.

Each container claims one or more paths within the user's forest (see below), which tells us at which mount points it is to be exposed to the user. This means that an individual container can be exposed under more than one path within the filesystem, e.g. /photos/My Special Event and /timeline/2022/03/13.

See Container for more information.

# Forest (a namespace for containers)

All containers belonging to one user are part of a so-called forest of that user. Users are internally represented by cryptographic key pairs, but higher-level modules may expose more familiar abstractions of users, e.g. as email addresses.

This means a forest represents a namespace identified by a unique Forest ID. Every container can belong to one, and only one forest. All the paths the container claims are to be interpreted within that forest.

A forest manifest defines a list of trusted pubkeys (called signers) which are authorized to create and modify containers.

# Users and Keys

The new Wildland Core has no notion of a user (as in: a human operator). Instead, it only operates on lists of keypairs, which are expected to be worked out by a specific client software facing module (i.e. CargoLib), which can e.g. maintain associations between keypairs and, say, email addresses. This allows for flexible applications and simplifies the core architecture and implementation.

Also, it is expected that the actual private keys are stored within a local secure storage (LSS) module. The LSS module might further make use of standards or well known key store implementations, such as Open PGP, YubiKey or Ledger Wallet, to actually store and use the key material. As such, the concrete implementation of LSS may be either provided as part of client software facing module (i.e. CargoLib) or be injected by a client application.

# Machinery (cloud-hosted forest automation)

Forests require various kind of automation to run in the background. A prime example is the syncing service which is tasked with ensuring that all storage backends connected to any given container are in sync.

See Machinery for more information.

# Forest Directories and Bridges

A Forest Directory, which is itself typically implemented as a Wildland Forest, is a directory of other Wildland forests, facilitating discovery and addressing of containers which are being shared from other user's forests. See Forest discovery and addressing.