dorfteich/docs/architecture/data-model.md

Data model

Authoritative once implemented in apps/api/prisma/schema.prisma; this document explains the entities and their intent. Naming below uses the English terms (pond = Teich).

Overview

erDiagram
    users ||--o{ user_identities : "logs in via"
    users ||--o{ sessions : has
    users ||--o{ ponds : "created"
    ponds ||--o{ pages : contains
    ponds ||--o{ labels : defines
    labels o|--o{ labels : "parent of"
    pages }o--o{ labels : "tagged with"
    pages ||--o{ page_versions : "has history"
    pages ||--|| page_content_cache : "derived text"
    pages ||--o{ page_links : "links to"
    pages ||--o{ attachments : has
    ponds ||--o{ attachments : owns
    users ||--o{ role_grants : "subject of"
    ponds ||--o{ role_grants : "scoped to"
    plugins ||--o{ pond_plugins : "activated in"
    ponds ||--o{ pond_plugins : activates
    pages ||--o{ comments : has
    users ||--o{ notifications : receives
    users ||--o{ watches : sets

Identity and access

users

Column	Notes
id (uuid)
username	unique, URL-safe
email	unique, stored verified/unverified with email_verified_at
display_name	shown at cursors, comments
locale	UI language (ADR 0012)
is_site_admin	boolean; Site Admin is a user flag, not a grant
status	active / disabled / pending_verification
created_at, last_login_at

user_identities (ADR 0007)

user_id, provider (password now; oidc:<issuer> later), subject, credential (Argon2id hash for password), unique on (provider, subject).

sessions

Opaque id (hashed), user_id, created_at, expires_at, last_seen_at, user-agent summary (for "active sessions" UI).

auth_tokens

Single-use tokens for e-mail verification and password reset: hashed token, purpose, expires_at, consumed_at.

role_grants — the permission table (see permissions.md)

Column	Notes
id
pond_id	every grant belongs to exactly one pond
subject_type	user / authenticated / public
subject_id	user id when subject_type = user, else null
role	pond_admin / editor / reader
scope_type	pond / label / page
scope_id	label id or page id when scoped, else null
effect	allow / deny
created_by, created_at	audit

Unique on (pond_id, subject_type, subject_id, role, scope_type, scope_id). pond_admin grants are only valid with scope_type = pond and subject_type = user.

Content

ponds

Column	Notes
id, slug (unique), name, description
type	personal (one per user, from self-signup) / shared
owner_id	creator; personal ponds: the user it belongs to
settings (jsonb)	fonts (ADR 0016), sidebar sort mode (alpha / created / manual), default page permissions
deleted_at, deleted_by	pond-level trash (ADR 0013)

pages

Column	Notes
id, pond_id
title	also indexed for search weight A
slug	unique per pond, for stable URLs and wikilink resolution
ydoc_state (bytea)	current merged Yjs state (ADR 0003)
ydoc_updates	append log table page_updates(page_id, seq, update bytea), compacted periodically
sort_key	manual sidebar ordering (fractional indexing)
created_by, created_at, updated_at
deleted_at, deleted_by	trash

page_content_cache

One row per page, refreshed on persistence: plain_text, markdown, html, outline (headings JSON, for TOC plugins), generated tsvector column with GIN index (ADR 0010).

page_versions (ADR 0013)

page_id, ydoc_snapshot (bytea, self-contained), trigger (auto / manual / pre_restore), label, contributor_ids, created_at.

labels

pond_id, name, parent_id (nullable — hierarchy), color, unique on (pond_id, parent_id, name). Cycles are rejected at write time. page_labels(page_id, label_id) is the assignment table.

page_links

Wikilink index maintained on persistence: from_page_id, to_page_id (nullable when target does not exist yet — "phantom" links), target_slug. Backlinks = query by to_page_id. Creating a page with a phantom-linked slug resolves those rows.

attachments (ADR 0011)

id, pond_id, page_id (nullable — pond-level files), file_name, mime_type, size_bytes, storage_path, uploaded_by, created_at, deleted_at.

Plugins (ADR 0008)

plugins

id (manifest id), version, manifest (jsonb), storage_path, kind (code / section_style), instance_mode (disabled / optional / required), installed_by, installed_at.

pond_plugins

(pond_id, plugin_id, enabled) — only meaningful for optional plugins; required plugins are active everywhere.

Quotas and settings

instance_settings

Key-value (typed JSON) singleton set: registration mode, SMTP config (secrets referenced from env, not stored plaintext — see security.md), default quotas, upload allowlist, legal pages content (imprint, privacy), instance default locale.

quota_overrides

subject_type (user / pond), subject_id, quota_key (editors_per_pond, readers_per_pond, additional_ponds, storage_bytes, max_file_bytes), value. Resolution: pond override → user override → instance default (most specific wins, mirroring the permission philosophy).

pond_usage

Cached counters per pond: storage_bytes_used, editor_count, reader_count — updated transactionally, reconciled nightly.

Collaboration support

• collab_tokens are not stored — they are short-lived signed JWTs (ADR 0007).
• mail_outbox: pending/sent e-mails with retry state (ADR 0002 — no broker).
• jobs: conversion jobs for import/export (ADR 0009) and maintenance jobs (compaction, trash purge, quota reconciliation) with status + timestamps.

Comments & notifications (later milestone)

• comments: page_id, author_id, body (Markdown), anchor (optional serialized position), resolved_at, created_at, thread via parent_id.
• watches: (user_id, target_type page/pond, target_id).
• notifications: user_id, type, payload (jsonb), created_at, read_at; delivered in-app, optionally by e-mail digest.

Deliberate non-entities

• No organizations/teams — ponds + grants cover the vision; groups can be added as a new subject_type in role_grants without migration pain.
• No content translations (ADR 0012).
• No per-keystroke authorship — contributor granularity is the version snapshot (ADR 0013).