Core Concepts

Heaper is built around a few fundamental ideas. Understanding these will help you get the most out of the app.

Blocks

Everything in Heaper is a block. Notes, files, images, folders, tags — they're all blocks. This uniform structure means any block can link to any other block, and every block supports the same operations (tagging, mentioning, filtering, etc.).

what blocks can be:

• Text Note — A note or page you create and write in - Title or content is optional write down what you need
• File — An image, video, PDF, or any other file
• Folder — A collection of other blocks but you can add context for MOCs (Maps of Content) describing what is in the folder.
• Tag / Mention — Links between blocks, tags for hierarchical organization and mentions for a network of content linked together as your knowledge graph.

Heaps

A heap is your top-level workspace/vault — a collection of blocks. You can have multiple heaps for different projects, areas of your life, or teams. They do not share blocks with othe heaps. this lets you separate your data into different workspaces and keep them isolated from each other.

Heaps can be:

• Local-only — Stored entirely on your device
• Cloud-synced — Synced to heaper.de
• self-hosted — Synced to your own server

See Managing Heaps for details on creating and configuring heaps.

Tags & Mentions

Blocks are connected through relations:

• Tags create a parent-child hierarchy. When you tag block B with tag A, B becomes a child of A. Think of tags as folders that a block can belong to multiple of. The block inherits the tags of the parent allowing for nested tags.
• Mentions create bidirectional links. Mentioning block B in block A creates a backlink visible from both sides.

Tags and mentions are the primary way to organize and navigate your content. See Tagging & Selection for how to apply them.

Local-First Architecture

Heaper follows a local-first design:

1. All your data lives on your device first
2. Changes are made locally and are available instantly, even offline
3. When a network connection is available, changes sync in the background
4. Conflicts are resolved automatically using CRDTs (see What is a CRDT?)

This means Heaper works without an internet connection. Your data is always accessible, and sync happens transparently when you're back online.

Servers vs clients

Heaper can be used with or without a server. with a server your data is synced. acting as the central hub for your data. This allows your clients to just keep previews and metadata and load the full content when needed. This is the recommended way to use Heaper, it allows you to offload the storage of your data to a server and you can use Heaper on multiple devices sharing data across all of them and having a central backup on your NAS or the cloud.

• Server — the server organzies your files in normal folders so you can always access them even without heaper installed. Metadata and notes are stored in a postgres database that you also can fully access yourself if you want the extra control and export options of everything heaper saves. Notes and Metadata are stored this way as filesystems are not capable or combining the concept of files, folders and notes into a single unit which would break the useablitity of the files
• Client — the client is your interface for interacting with your data. it allows you to create, edit, and delete blocks and view your data in a visual way. It is supposed to be the general purpose way to use Heaper for any kind of function. clients store the synced data differently to be space and performance efficient, files are stored in folders including their thumbnials but arent browseable on the client without heaper as only metadata or a thumbnail could be stored and is seamlessly merged in the heaper interface with the downloaded content.

See Self-hosting for details on how to self-host Heaper.

File Scanning

On selfhosted setups you can map a volume to an existing folder on your server, Heaper scans the filesystem and creates blocks for each file and folder. Thumbnails are generated automatically. The original files stay where they are. This is the fastest way to get large amounts of files into heaper.

See File Scanning & Importing for details.