# 260614 — Notion deep dive (closed block-database SaaS, attached only through its API)

Date: 2026-06-14

## What this is

A focused study of **Notion** — architecture and extension model — read through
shard-wiki's lens. Notion is the **closed, hosted, schema-rich** end of the spectrum and
the dive that stress-tests shard-wiki's hardest constraints (*graceful degradation*,
*no silent remote mutation*, *Markdown-first that must degrade*).

It contrasts sharply with its neighbours:
- vs **Roam** — both are block databases with per-block UUIDs, but Roam is a *client*
  DataScript DB reached only via an *in-app* JS API, while Notion is a *server* Postgres
  store reached via a real *external* REST API (no in-engine hosting needed, but
  rate-limited, eventually consistent, scoped by per-page grants).
- vs **Obsidian** — the mirror image of "file over app": Notion is **app over file**, a
  closed hosted store with no portable files.
- vs **XWiki** — both are structured wiki-as-app-platforms; Notion is the **apex of
  database-as-pages** (schema + relations + rollups + views) but closed and REST-only.

Distinctive material:
- **Data model** — everything is a **block** (UUID id, type, properties, ordered child
  `content`, single `parent`); pages are blocks, **database rows are pages with a
  schema**; Postgres-backed hosted SaaS
- **Databases** — typed properties, **relations** (bidirectional), **rollups**,
  **formulas**, and many **views** (table/board/calendar/gallery) of one row-set
- **Extension model** — **no in-app plugin runtime**; extension = **external REST API**
  integrations (+ webhooks since 2026), with ~3 rps rate limit, eventual consistency,
  recursive child fetch, payload caps, and **scoped/revocable per-page access grants**

## Contents

| Path | Role |
|------|------|
| `findings.md` | Block model, databases, page-model impedance, the API-only extension model, capability profile, scoped consent, INTENT mapping, UC seeds, architecture notes, sources |

## Status

Initial deep dive complete. Three new use cases promoted to `spec/UseCaseCatalog.md`
(UC-57 attach a closed external-API-only hosted shard with rate-limit/eventual-
consistency/scoped-grant constraints, UC-58 attach a typed database with schema +
relations + views without flattening, UC-59 lossy-aware translation with a fidelity
report); UC-31/34/36/39/50/51/52/54/56 enriched. Logged for `SHARD-WP-0002` (T14):
an **operational-envelope** capability section, **access-grant semantics**, a
**translation-fidelity** capability, and a three-way **attachment-mode taxonomy**
(file-store / in-engine-hosted / external-API-only).

**Key takeaways recorded:** Notion *enforces* "no silent remote mutation" via scoped,
revocable per-integration grants (ties the authz-in-core decision); it is the heaviest
**lossy-translation** case (proprietary blocks/rich-text, lossy Markdown export); and it
adds the **external-API-only** attachment mode (full write-through without in-engine
hosting, but bounded by rate limits and eventual consistency). **Boundary:** one
external-API candidate shard — best as projection/mirror/overlay/backup — not a
substrate and not the federation layer.
</content>