= Grid34

Grid34 is an open-source, browser‑based collaborative workspace that runs entirely on the nostr:naddr1qvzqqqrcvgpzp925xvyklj3z8u56ml2j5rpduparc5htdq8eknv7kmzxmyvkc4qwqqzkummnw3eq3q8xf0[Nostr] protocol. It blends a Notion‑style block editor with Git‑style versioning, peer‑to‑peer networking, and end‑to‑end encryption – all without a central server. Users authenticate with their nostr:naddr1qvzqqqrcvgpzp925xvyklj3z8u56ml2j5rpduparc5htdq8eknv7kmzxmyvkc4qwqqzkummnw3eq3q8xf0[Nostr] identity, create encrypted repositories, and collaborate in real time with others through a fully local‑first architecture.

[cols=“1,3”] |=== | Developer(s) | imattau | Initial release | June 2026 | Repository | https://github.com/imattau/grid34 | Written in | TypeScript, React | Platform | Web | License | Not specified | Website | https://grid34.3nostr.com |===

== Overview

Grid34 is designed as a local‑first, serverless alternative to centralized collaboration tools like Notion, Google Docs, or Coda. Every workspace is modelled as an encrypted Git‑style repository stored natively on Nostr relays using NIP‑34 (Git‑over‑Nostr), while an embedded SQLite engine indexes content locally for fast querying. The editor is built with Tiptap/ProseMirror and supports rich‑text blocks, nested lists, and structured database grids.

Because all logic runs in the browser, the application works offline and synchronises changes once a connection is restored. Real‑time collaboration is handled by a libp2p‑based encrypted mesh network, with Yjs used for conflict‑free state synchronisation and live cursor awareness.

== Architecture

Grid34 is structured into three distinct subsystems, all running inside the client browser:

---

UI[Editor UI - React & Tiptap] –>|Drafts| DS[Draft Store] DS –>|Sync / Local SQL| SQL[SQLite Indexer - sql.js] DS –>|Collab Integration| Collab[Presence & Yjs Sync] Collab –>|Encrypted Mesh| P2P[libp2p P2P Network] DS –>|Commit Pipeline| Storage[NIP-34 Encrypted Git-over-Nostr] Storage –>|Relays| Nostr[Nostr Relays] ––

=== Storage and Persistence Layer (src/storage/)

This layer models every workspace as an encrypted Git‑style repository stored on Nostr via NIP‑34 events, mirroring the data into a local SQLite database for fast querying. It consists of three components:

• CEK Encryption (src/storage/crypto/) – manages Content Encryption Keys to ensure that only invited collaborators can decrypt block contents.
• Reducer & Commits (src/storage/repo/ & src/storage/commit/) – implements Git‑like patch reduction. Modified blocks are staged, compiled into commit event templates, and published as signed events to Nostr relays.
• SQLite Engine (src/storage/index/) – uses sql.js to index raw repository contents in the browser, enabling efficient querying of workspace data.

=== Block Editor UI (src/editor/)

A modular React editor built with Tiptap/ProseMirror provides the user interface for content creation:

• Rich‑Text Blocks – supports paragraphs, headings, and native nested bullet/numbered lists, all inside a single database block for seamless inline editing.
• Notion‑style Database Blocks – structured grids backed by reactive SQL index queries, allowing users to filter, sort, and search database items.
• Draft Pipeline (src/editor/stores/draftStore.ts) – an intermediary staging layer that continuously captures edits, debounces input, and creates local checkpoints before publishing to Nostr.
• Slash Commands (/) – an inline command palette for creating database blocks, headers, and lists.

=== Collaboration and Peer‑to‑Peer Sync (src/collab/)

This layer maintains live collaborative editing sessions with zero central servers:

• Encrypted Discovery (src/collab/discovery/) – uses Nostr NIP‑44 encrypted events to advertise peer metadata and coordinate encryption endpoints.
• Gossipsub Room Management (src/collab/room/) – handles pub/sub room dynamics (join/leave) backed by custom libp2p transport layers.
• Yjs Sync Integration (src/collab/doc/ & src/collab/integration/) – coordinates concurrent Yjs document states and cursor presence, feeding them directly into the React editor.

== Key Features

• Local‑first and offline ready – all revisions are staged locally and indexed via an embedded browser SQLite database (sql.js).
• Nostr identity integration – standard NIP‑07 login (e.g., Alby, nos2x) with contacts sync for workspace collaborator invites.
• Decentralised persistence – serverless storage using Git‑style commit patches broadcast via Nostr relays.
• Live multi‑user collaboration – fully encrypted peer‑to‑peer workspace sharing, editing, and live cursor awareness.
• Responsive dark/light mode – full CSS‑variable‑based theme toggling with custom overrides for syntax trees, databases, modals, and login screens.
• Stately visual design – clean borders, typography, status badges, and logo aesthetics.

== Technology Stack

[cols=“1,2”] |=== | Build tool / environment | Vite | Frontend framework | React with TypeScript | Styling | Tailwind CSS | Rich‑text editor | Tiptap / ProseMirror | Real‑time synchronisation | Yjs + libp2p | Nostr subscription helpers | applesauce | Browser SQLite | sql.js |===

== Development

=== Commands

[source,bash] –– # Install dependencies npm install

Start the Vite development server npm run dev

Build for production npm run build

Run the test suite (Vitest) npm test

Run specific matching tests npm test – <pattern>

Run tests in watch mode npm run test:watch

---

=== Project Structure

---

src/ ├── storage/ # Persistence layer (CEK, commits, SQLite indexing) ├── editor/ # UI components, block types, draft pipeline ├── collab/ # P2P networking, discovery, Yjs sync └── … ––

== See also

• https://nostr.com/[Nostr protocol] – the decentralised social protocol underpinning Grid34
• https://github.com/nostr-protocol/nips/blob/master/34.md[NIP‑34] – Git‑over‑Nostr specification
• https://yjs.dev/[Yjs] – CRDT‑based real‑time collaboration framework
• https://libp2p.io/[libp2p] – modular peer‑to‑peer networking stack

== External links

• https://github.com/imattau/grid34[GitHub repository]
• https://grid34.3nostr.com[Grid34 website]