From ca51f348991ff33a20bf7908cd5234c900d1e314 Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Fri, 19 Sep 2025 20:37:55 -0700 Subject: [PATCH 1/7] adding hypergraph --- website/next.config.js | 11 ++- website/src/pages/en/global.json | 1 + .../src/pages/en/hypergraph/_meta-titles.json | 4 + website/src/pages/en/hypergraph/_meta.js | 6 ++ website/src/pages/en/hypergraph/faq.mdx | 75 ++++++++++++++ .../pages/en/hypergraph/hypergraph-intro.mdx | 99 +++++++++++++++++++ 6 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 website/src/pages/en/hypergraph/_meta-titles.json create mode 100644 website/src/pages/en/hypergraph/_meta.js create mode 100644 website/src/pages/en/hypergraph/faq.mdx create mode 100644 website/src/pages/en/hypergraph/hypergraph-intro.mdx diff --git a/website/next.config.js b/website/next.config.js index e1338f8b251e..b30937779bc3 100644 --- a/website/next.config.js +++ b/website/next.config.js @@ -73,18 +73,25 @@ const withNextra = nextra({ '---4': { type: 'separator', }, + hypergraph: { + type: 'children', + title: t('global.navigation.hypergraph'), + }, + '---5': { + type: 'separator', + }, 'ai-suite': { type: 'children', title: t('global.navigation.ai-suite'), }, - '---5': { + '---6': { type: 'separator', }, indexing: { type: 'children', title: t('global.navigation.indexing'), }, - '---6': { + '---7': { type: 'separator', }, resources: { diff --git a/website/src/pages/en/global.json b/website/src/pages/en/global.json index f1d954fe756e..659ff686d613 100644 --- a/website/src/pages/en/global.json +++ b/website/src/pages/en/global.json @@ -6,6 +6,7 @@ "subgraphs": "Subgraphs", "substreams": "Substreams", "sps": "Substreams-Powered Subgraphs", + "hypergraph": "Hypergraph", "ai-suite": "AI Suite", "tokenApi": "Token API", "indexing": "Indexing", diff --git a/website/src/pages/en/hypergraph/_meta-titles.json b/website/src/pages/en/hypergraph/_meta-titles.json new file mode 100644 index 000000000000..e8a93936aca5 --- /dev/null +++ b/website/src/pages/en/hypergraph/_meta-titles.json @@ -0,0 +1,4 @@ +{ + "hypergraph": "Hypergraph Introduction", + "faq": "Hypergraph FAQ" +} diff --git a/website/src/pages/en/hypergraph/_meta.js b/website/src/pages/en/hypergraph/_meta.js new file mode 100644 index 000000000000..7e8dc0d040e7 --- /dev/null +++ b/website/src/pages/en/hypergraph/_meta.js @@ -0,0 +1,6 @@ +import titles from './_meta-titles.json' + +export default { + 'hypergraph-intro': '', + faq: '', +} diff --git a/website/src/pages/en/hypergraph/faq.mdx b/website/src/pages/en/hypergraph/faq.mdx new file mode 100644 index 000000000000..aeda320af83d --- /dev/null +++ b/website/src/pages/en/hypergraph/faq.mdx @@ -0,0 +1,75 @@ +--- +title: FAQ +--- + +## General Questions + +### What is Hypergraph? + +Hypergraph is a TypeScript-first framework for building local-first apps that syncs encrypted data to a shared knowledge graph. + +### Does it replace my backend? + +Yes. Hypergraph is your data layer. You still host a thin sync server, but your business logic lives entirely on the client. + +### Who is Hypergraph for? + +Developers building collaborative, consumer-facing apps that require real-time data sync, end-to-end encryption, and public knowledge graph interoperability. Ideal for those who want to focus on client-side logic without managing backend infrastructure. + +### What problems does Hypergraph solve? + +- Real-time sync of private data across users and devices with E2EE +- No traditional backend or database required (framework handles storage and sync) +- Publishing and consuming public data in an interoperable knowledge graph +- Built-in user authentication and access control +- Enables network effects by reusing existing data across apps + +### What should developers know? + +You should be comfortable writing React applications in TypeScript and familiar with common UI patterns (e.g., inboxes). + +## Implementation Questions + +### How can I integrate Hypergraph into an existing application? + +You can add Hypergraph as a collaboration and privacy layer to an existing app, enabling real-time sync and end-to-end encryption while keeping your current stack for other functionality. + +### What are Spaces? + +Spaces are the primary grouping for users and content in Hypergraph: they represent collaboration contexts and topics. Only members of a space can access its private data. + +### How do I get started? + +Check out the [Quickstart](https://docs.hypergraph.thegraph.com/docs/quickstart). + +### Where can I find the API reference? + +Refer to the [API Reference](https://docs.hypergraph.thegraph.com/docs/api-reference/hypergraph/). + +### How do I troubleshoot common errors? + +Find solutions in the [Troubleshooting Guide](https://docs.hypergraph.thegraph.com/docs/troubleshooting). + +## Support and Community + +### Where can I find more examples or support? + +Browse our GitHub repository for sample apps and open issues. Join the community through our issue tracker and discussion forums. + +### How can I share feedback? + +Provide feedback via GitHub issues or our upcoming feedback form linked in the docs. + +### Is Hypergraph open-source? + +100%. Apache-2.0 license. Contributions are welcomed. + +## Security and Privacy + +### Can the server read my private data? + +No. All private content is encrypted client-side with a per-Space symmetric key. + +### What happens if I lose my keys? + +Today you're out of luck (similar to Signal). A social recovery scheme is on the roadmap. Follow [#51](https://github.com/graphprotocol/hypergraph/issues/51). diff --git a/website/src/pages/en/hypergraph/hypergraph-intro.mdx b/website/src/pages/en/hypergraph/hypergraph-intro.mdx new file mode 100644 index 000000000000..b1f75face33e --- /dev/null +++ b/website/src/pages/en/hypergraph/hypergraph-intro.mdx @@ -0,0 +1,99 @@ +--- +title: Hypergraph +--- + +## Overview + +[Hypergraph](https://docs.hypergraph.thegraph.com/) is a TypeScript-first framework for building local-first applications that sync encrypted data to a shared knowledge graph. Instead of relying on traditional backend infrastructure, it shifts control to the client and puts data where it belongs: with the user. + +At its core, Hypergraph is powered by two innovations: + +1. Client-side architecture that keeps users in control of their data while apps remain real-time, private, and interoperable by default. +2. The [GRC-20](https://thegraph.com/blog/grc20-knowledge-graph/) standard which enables truly composable knowledge graphs. + +With Hypergraph, developers can build collaborative apps that feel seamless, secure, and user-owned while focusing purely on client-side logic. + +It offers end-to-end encryption, a GRC-20 Knowledge Graph SDK, JSON-LD storage, conflict-free sync with CRDTs, and Spaces for organizing people and data with fine-grained access. + +For more specifics check out, [key features](https://docs.hypergraph.thegraph.com/docs/key-features). + +## Core Concepts + +### Knowledge Graphs + +Unlike traditional databases that store data in rows and columns, knowledge graphs represent information as connected networks. This structure makes complex queries natural and efficient, while allowing the data model to evolve organically without schema migrations. + +#### Example Use Case + +In a social app, a traditional database might require complex joins to answer a query like: `"Posts by photographers that my friends liked"` + +In a knowledge graph, relationships are the data: + +``` +Teresa --> profession --> Photography +Teresa --> owns --> Fujifilm X100 +Teresa --> posted --> Street Photo +Alex --> friend_of --> Teresa +Alex --> liked --> Street Photo +``` + +This model makes queries natural and efficient, while allowing the schema to evolve organically. + +### The Hypergraph Advantage + +- **Private by default**: Personal data is encrypted on the device. +- **Peer-to-peer**: No central server required. Collaboration is direct. +- **Real-time**: Changes synchronize instantly across devices. +- **Interoperable**: Data is usable across applications that support the protocol. + +Hypergraph serializes all data using the [GRC-20 standard](https://thegraph.com/blog/grc20-knowledge-graph/). Hypergraph handles serialization, encryption, and networking behind the scenes, while developers interact with simple SDK calls. + +### Spaces + +A Space is the fundamental unit of collaboration. It groups people and data, similar to a folder, Slack channel, or shared document. Each Space maps one-to-one with an Automerge document, enabling conflict-free offline editing. + +Membership and roles are tracked in an append-only Space Event Log, supporting common operations like creating a Space, updating roles, inviting members, or removing members. + +### Identities + +Each user controls a cryptographic **Identity** used for authentication, encryption, and signing events. Identities are stored locally, enabling multi-device logins without a backend. + +### Inboxes + +An Inbox is a lightweight queue for delivering updates or direct messages. + +- **Account Inboxes**: Belong to a single user. +- **Space Inboxes**: Broadcast messages to all members. + +Inboxes can be public or private, with authentication policies controlling who can send messages. + +### Events and CRDTs + +Hypergraph uses CRDTs (Conflict-Free Replicated Data Types) to manage updates across peers. + +- Updates are signed, encrypted, and broadcast to peers. +- Conflicts resolve automatically without manual intervention. +- Large logs are periodically compacted into snapshots for efficiency. + +### Security Model + +Hypergraph is designed with security as a core principle: + +- End-to-end encryption ensures data privacy. +- Digital signatures verify the authenticity of events. +- Outdated or invalid updates are automatically rejected. +- Keys are rotated when membership changes to prevent unauthorized access. + +## Exploring Spaces + +Spaces can be browsed using [Geo Browser's Testnet](https://testnet.geobrowser.io/root) by entering a Space ID. Access is restricted by each Space's privacy rules. + +## Getting Started + +- [Quickstart Guide](https://docs.hypergraph.thegraph.com/docs/quickstart) +- [Core Concepts](https://docs.hypergraph.thegraph.com/docs/core-concepts#why-does-grc-20-exist) +- [AI Usage](https://docs.hypergraph.thegraph.com/docs/ai-usage) +- [API Reference](https://docs.hypergraph.thegraph.com/docs/api-reference/hypergraph/) +- [Troubleshooting Guide](https://docs.hypergraph.thegraph.com/docs/troubleshooting) + +For all Hypergraph documentation check out [Hypergraph Docs](https://docs.hypergraph.thegraph.com/docs/quickstart) and the [Hypergraph Github Repo](https://github.com/graphprotocol/hypergraph) From 77c7eb7440defb8f54a69dc2bb428b186102c8c0 Mon Sep 17 00:00:00 2001 From: benface Date: Mon, 22 Sep 2025 13:13:04 -0400 Subject: [PATCH 2/7] Add Hypergraph logo to sidebar --- website/src/layout/Layout.tsx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/src/layout/Layout.tsx b/website/src/layout/Layout.tsx index fce5483d21fb..b1e76d3d29c6 100644 --- a/website/src/layout/Layout.tsx +++ b/website/src/layout/Layout.tsx @@ -36,6 +36,7 @@ import { BookOpenText, Files, House, + Hypergraph, MagnifyingGlass, RoleIndexer, SidebarSimple, @@ -199,6 +200,9 @@ export default function Layout({ pageOpts, children }: NextraThemeLayoutProps } + if (routeWithoutLocale === '/hypergraph' || routeWithoutLocale.startsWith('/hypergraph/')) { + return + } if (routeWithoutLocale === '/ai-suite' || routeWithoutLocale.startsWith('/ai-suite/')) { return } From fa6986d74e83455e1d7ad1e0e67828f3ef42a598 Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Mon, 22 Sep 2025 12:12:06 -0700 Subject: [PATCH 3/7] fixing names --- website/src/pages/en/hypergraph/_meta-titles.json | 2 +- website/src/pages/en/hypergraph/_meta.js | 2 +- .../pages/en/hypergraph/{hypergraph-intro.mdx => overview.mdx} | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) rename website/src/pages/en/hypergraph/{hypergraph-intro.mdx => overview.mdx} (99%) diff --git a/website/src/pages/en/hypergraph/_meta-titles.json b/website/src/pages/en/hypergraph/_meta-titles.json index e8a93936aca5..69ca06f20230 100644 --- a/website/src/pages/en/hypergraph/_meta-titles.json +++ b/website/src/pages/en/hypergraph/_meta-titles.json @@ -1,4 +1,4 @@ { - "hypergraph": "Hypergraph Introduction", + "overview": "Hypergraph Overview", "faq": "Hypergraph FAQ" } diff --git a/website/src/pages/en/hypergraph/_meta.js b/website/src/pages/en/hypergraph/_meta.js index 7e8dc0d040e7..3e253cb65cf4 100644 --- a/website/src/pages/en/hypergraph/_meta.js +++ b/website/src/pages/en/hypergraph/_meta.js @@ -1,6 +1,6 @@ import titles from './_meta-titles.json' export default { - 'hypergraph-intro': '', + overview: '', faq: '', } diff --git a/website/src/pages/en/hypergraph/hypergraph-intro.mdx b/website/src/pages/en/hypergraph/overview.mdx similarity index 99% rename from website/src/pages/en/hypergraph/hypergraph-intro.mdx rename to website/src/pages/en/hypergraph/overview.mdx index b1f75face33e..02d4c9401320 100644 --- a/website/src/pages/en/hypergraph/hypergraph-intro.mdx +++ b/website/src/pages/en/hypergraph/overview.mdx @@ -1,5 +1,6 @@ --- title: Hypergraph +sidebarTitle: Overview --- ## Overview From 9b0b34c5f6e54dd2966ab67a8895536abdad23d5 Mon Sep 17 00:00:00 2001 From: Idalith <126833353+idalithb@users.noreply.github.com> Date: Mon, 22 Sep 2025 13:17:32 -0700 Subject: [PATCH 4/7] Update website/src/pages/en/hypergraph/_meta.js MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Benoît Rouleau --- website/src/pages/en/hypergraph/_meta.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/src/pages/en/hypergraph/_meta.js b/website/src/pages/en/hypergraph/_meta.js index 3e253cb65cf4..3db8b76c3175 100644 --- a/website/src/pages/en/hypergraph/_meta.js +++ b/website/src/pages/en/hypergraph/_meta.js @@ -1,5 +1,3 @@ -import titles from './_meta-titles.json' - export default { overview: '', faq: '', From 17ba8a2065f2d6c8ab2a0eb16035709fcb3ab5a5 Mon Sep 17 00:00:00 2001 From: Idalith <126833353+idalithb@users.noreply.github.com> Date: Mon, 22 Sep 2025 13:17:42 -0700 Subject: [PATCH 5/7] Update website/src/pages/en/hypergraph/overview.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Benoît Rouleau --- website/src/pages/en/hypergraph/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/pages/en/hypergraph/overview.mdx b/website/src/pages/en/hypergraph/overview.mdx index 02d4c9401320..35c1f3f1488b 100644 --- a/website/src/pages/en/hypergraph/overview.mdx +++ b/website/src/pages/en/hypergraph/overview.mdx @@ -97,4 +97,4 @@ Spaces can be browsed using [Geo Browser's Testnet](https://testnet.geobrowser.i - [API Reference](https://docs.hypergraph.thegraph.com/docs/api-reference/hypergraph/) - [Troubleshooting Guide](https://docs.hypergraph.thegraph.com/docs/troubleshooting) -For all Hypergraph documentation check out [Hypergraph Docs](https://docs.hypergraph.thegraph.com/docs/quickstart) and the [Hypergraph Github Repo](https://github.com/graphprotocol/hypergraph) +For all Hypergraph documentation check out the [Hypergraph Docs](https://docs.hypergraph.thegraph.com/docs/quickstart) and the [Hypergraph GitHub Repo](https://github.com/graphprotocol/hypergraph). From 174d698a664dd3ed6cfcb4094edcc8840f0af787 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Rouleau?= Date: Mon, 22 Sep 2025 17:06:01 -0400 Subject: [PATCH 6/7] Delete website/src/pages/en/hypergraph/_meta-titles.json --- website/src/pages/en/hypergraph/_meta-titles.json | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 website/src/pages/en/hypergraph/_meta-titles.json diff --git a/website/src/pages/en/hypergraph/_meta-titles.json b/website/src/pages/en/hypergraph/_meta-titles.json deleted file mode 100644 index 69ca06f20230..000000000000 --- a/website/src/pages/en/hypergraph/_meta-titles.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "overview": "Hypergraph Overview", - "faq": "Hypergraph FAQ" -} From 2f0cd40a05bdda94dfe267841b30ba2ffeb42331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Rouleau?= Date: Mon, 22 Sep 2025 17:06:58 -0400 Subject: [PATCH 7/7] Update website/src/pages/en/hypergraph/faq.mdx --- website/src/pages/en/hypergraph/faq.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/src/pages/en/hypergraph/faq.mdx b/website/src/pages/en/hypergraph/faq.mdx index aeda320af83d..9511f5f69d18 100644 --- a/website/src/pages/en/hypergraph/faq.mdx +++ b/website/src/pages/en/hypergraph/faq.mdx @@ -1,5 +1,6 @@ --- -title: FAQ +title: Hypergraph FAQ +sidebarTitle: FAQ --- ## General Questions