# 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

```mermaid
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).