Records, fields and relationships

1 · Storage map

Each server data location is relative to the authenticated account’s storage root, normally APP_DATA_DIR/users/<userKey>/. The legacy owner can use APP_DATA_DIR/ itself. The global users and sessions files live at that top level. Never choose an account root from an untrusted request field.

2 · Relationships and identifiers

User (userKey)
  ├─ Session [sessionId]
  └─ Account storage
       ├─ NotesFolder [id] ── parentId → NotesFolder
       │    └─ Note [id, folderId]
       │         ├─ editor blocks → media source / other note
       │         ├─ Pending / Base / Deleted [noteId]
       │         ├─ DriveIndex [noteId] → Google Drive .md [fileId]
       │         └─ Canvas [docId, id] → Elements → Connectors
       └─ FilesFolder [id] → Media metadata → local file / Drive source

Unless specified otherwise, app timestamps are numbers in milliseconds since the Unix epoch. Drive revision values are opaque strings; never compare them as integers. Positions are numeric sibling order. Missing optional fields and explicit null have different meanings: preserve the distinction during round trips.

3 · Note record and editor content

DocumentRecord is the browser/API document shape. Core fields are required for a normalized note; optional fields must survive supported round trips.

Editor node structure

{
  "id": "doc-example",
  "title": "Research notes",
  "folderId": "note-folder-example",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": {
          "level": 1
        },
        "content": [
          {
            "type": "text",
            "text": "Research notes"
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "My observations about the source file."
          }
        ]
      }
    ]
  },
  "createdAt": 1793000000000,
  "updatedAt": 1793000001000,
  "trashedAt": null
}

4 · Folder tables

The server keeps dictionaries noteFolders[id] and folders[id]. The browser uses Notes workspaces in its local graph or folder:<id> records in Drive mode.

{
  "id": "note-folder-example",
  "name": "Sources",
  "parentId": "folder-notes",
  "position": 0,
  "createdAt": 1793000000000,
  "updatedAt": 1793000000000
}

5 · Browser tables and outgoing operations

Drive mode: account database

IndexedDB filesandnotes-drive-<userKey>, version 1, contains the object store records. Keys are external strings; the stored value is the record itself, not a {key,value} wrapper.

Write the local document and its pending operation in the same IndexedDB transaction. An acknowledgement may clear only the operation whose token still matches. Keep newer edits, failed operations and tombstones through reloads. Use account-specific browser locks and sync messages.

Browser-only mode and compatibility

The existing browser-only store opens paper_documents, version 4. It is still used when Drive mode is inactive and can later be imported into the Drive store. Local-first sync is disabled in its current constructor; these stores do not imply a second server sync protocol.

6 · Server JSON and technical Drive index

data.json is normalized through an explicit top-level whitelist. Adding a service key without updating that whitelist loses it on the next write.

Drive state

Persisted Drive file entry

This is the actual allowlist from driveFileMetadata. No title, content, baseContent, questions or goalReferences in newly persisted entries. Legacy entries may remain until a receipt-checked transfer is acknowledged; never delete them before verifying the browser import.

7 · Users, sessions and Drive connection

Google sign-in and Drive consent are separate flows. Store credentials only on the server; browser payloads expose connection status, not refresh tokens. Session IDs and OAuth secrets must never become fixture content in this package.

8 · Media, annotations and canvas

Media metadata

Local records are keyed by safe filename; Drive records by Google file ID. Sparse records are valid. A Drive upload returns the fuller shape below; a listing may derive display fields dynamically rather than persist each field.

Canvas document

Canvas JSON and media annotations are existing server-side content stores with their own privacy scope. They are not covered by a claim that all application data is browser/Drive-only. Do not add a duplicate server copy of editor note content to either collection.

9 · Drive Markdown and encrypted tickets

Drive file format

A note is a readable Markdown file with a single filesandnotes: JSON metadata line inside frontmatter. The encoder removes content, driveRevision, driveFileId and driveReadError from that metadata. Editor blocks have a Base64-encoded JSON node comment plus readable Markdown; this preserves supported structured nodes while allowing external edits.

---
filesandnotes: {"id":"doc-example","title":"Research notes","folderId":"note-folder-example","createdAt":1793000000000,"updatedAt":1793000001000,"trashedAt":null}
---

<!-- filesandnotes:block <Base64 JSON node; schematic placeholder> -->
# Research notes
<!-- /filesandnotes:block -->

The placeholder above is schematic, not an importable file. Base64 is not encryption. If a block’s Markdown changes outside the app, the decoder reparses that Markdown; malformed metadata/block markers produce an error rather than an empty overwrite.

Temporary encrypted packet

A ticket is a random 32-character hex ID. Its account-scoped file is deleted when a completed result is consumed. Ticket acceptance confirms receipt, not a successful Drive write. The server can decrypt these packets; this is not end-to-end encryption. See 08 Security for risks and outstanding hardening.

Detailed implementation boundaries

Use the normalized document schema with 11 API Contracts for wire payloads, 13 Markdown Compatibility for supported node attributes/defaults, and 12 Failure & Recovery for lifecycle decisions. The generic structural node schema does not make unknown node types supported. Extension arrays need their own declared validation when selected.

10 · Data contract prompt and acceptance checks

Read prompt/data-structure.html before implementing stores or API payloads.
Create explicit shared record schemas for the chosen scope. Keep logical note IDs, folder IDs, userKey, Drive file IDs and revision strings distinct. Use synthetic fixtures only.
Implement account-scoped browser stores; do not reproduce the legacy browser-only database naming limitation. Preserve optional compatibility fields without creating new product workflows.
Keep note titles, bodies, questions, references and merge bases in the browser and optional user Drive. Persist only the documented technical Drive allowlist on the server. Keep canvas/media annotation storage explicit.
Commit document + pending operation atomically. Clear a queued version only after its matching acknowledgement. Keep tombstones and failed work after reload. Define migrations before changing schema versions.
Verify record round trips, folder integrity, two-account isolation, stale acknowledgements, retry-safe Drive creation, offline reload, deletion races and legacy import acknowledgement. Do not erase user data to make a migration pass.
Report schema decisions, actual test evidence and any unsupported extension fields in build-status.md.

1. Round-trip the synthetic note and folder without changing IDs, nulls, block order or supported attributes.
2. Reject invalid IDs, folder cycles and cross-account access; test browser-only and Drive modes separately.
3. Reload offline with pending work, then replay it. A stale token must not clear a newer edit.
4. Inspect new server files after saving a unique note sentence and title: neither may appear as readable note content. Inspect technical Drive entries against the allowlist; canvas/media fixtures use their separate scope.
5. Verify supported Markdown blocks and external edits, then verify that malformed data cannot overwrite a good note with a blank one.
6. Use 06 Verification for the broader product scenarios. Use A01–A12 and synthetic fixtures in 15 Acceptance & Fixtures. These are checks to perform in the generated app, not claims that this documentation edit ran them.