Skip to content

Core concepts ​

Six ideas. Everything else in Notesflow follows from them.

1. A block is the unit of everything ​

A page is an ordered tree of blocks: paragraphs, headings, list items, quotes, code blocks, callouts, tables, images. Each block has a stable identity that survives being edited, indented, reordered, moved to another page, exported and imported again.

That identity is why the rest works. Provenance, comments, block references, declared dates and history all attach to a block, and none of them break when the block moves.

2. The op log is canonical ​

Every edit appends an op to a log: create, update, move, delete — attributed to an account and stamped with a wall-clock time. The current state of a page is what you get by replaying its ops.

Nothing is overwritten. Restoring an old revision appends the ops that put the old content back rather than erasing what came after, so the record of what happened stays intact.

This is the inversion at the centre of the product. Most tools store documents and try to reconstruct history by diffing them; Notesflow stores the history and projects the documents. That is why the timeline costs a query rather than a crawl.

3. Two dates, and they are different questions ​

Where it livesWhat it saysWho decides
Writtenthe op logwhen this was writtenthe server's clock, derived
Filed underthe pagewhich day this page is the journal forthe author, once per page
Placed onthe blockwhich day this item appears underthe author, per block

The first is derived, never asserted. The other two are stated by a person, and neither can move the first. Declaring where something belongs never rewrites when it was written — which is what keeps "what did I actually do in March" answerable.

A block carrying a placed date appears under both days in the timeline, and each row says which axis put it there.

4. Markdown is a projection ​

Markdown is what blocks become, not what they are. Every block type declares which fidelity tier it exports at:

  • T1 — lossless round-trip through pure CommonMark.
  • T2 — lossless via widely-supported extensions (GFM tables, task lists).
  • T3 — degrades to readable Markdown plus an HTML-comment sidecar carrying the structured part. A reader that ignores the comment sees the words and loses the extra.

The tier table is generated from the block registry, so it cannot drift from what the code actually does. Export, the clipboard and import all go through one serialiser, and CI fails the build if a second one appears.

5. Pages live in a tree, and access flows down it ​

A workspace has a page tree. A role says what you may do to the workspace and what you may open by default; a grant on a page says what you may do there, and it applies to everything underneath. Nearest statement to the page wins.

The four levels are none, read, comment and write, and they mean what they say — comment is also the level that can propose a change without being able to make one. See roles and permissions.

6. A workspace is a boundary, not a folder ​

One deployment can hold many workspaces. Each has its own pages, history, search, attachments and admins, and the separation is enforced by the database's own row-level security rather than by a WHERE clause somebody has to remember writing.

One account, one sign-in, a role per workspace, and a switcher when you belong to more than one. See workspaces.

How they fit together ​

   you type
      │
      ▼
   blocks  ──────────────►  Markdown        (a projection, tiered)
      │                          │
      │                          ▼
      │                     .md files  ──►  git   (an export target)
      ▼
    op log  ──────────────►  timeline        (a query, by wall time)
      │                     history          (revisions, restore by appending)
      │                     provenance       (who wrote this block, and when)
      ▼
    permissions              one rule, asked everywhere

Blocks and the op log are canonical. Markdown is a projection. Git is a target.