docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coodos merged 10 commits into from
Jan 26, 2026
Merged

docs: add infrastructure, protocol, and getting started docs #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
6fb93ec
docs: add infrastructure docs
coodos Jan 25, 2026
0d6bb33
docs: fix evault documentation
coodos Jan 25, 2026
a216618
docs: fix example for social media post
coodos Jan 25, 2026
e90b8cc
docs: fix contradiction around hw and sw keymanagers
coodos Jan 25, 2026
373c3da
chore: address points on getting started page
coodos Jan 26, 2026
1b18529
chore: fix code rabbit suggestions
coodos Jan 26, 2026
f543666
docs: address issues in eid wallet doc
coodos Jan 26, 2026
166838b
docs: address evault.md docs issues
coodos Jan 26, 2026
c528a0a
docs: address issues in auth & signing
coodos Jan 26, 2026
4c3b1c3
chore: fix broken lang blocks
coodos Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 180 additions & 23 deletions docs/docs/Getting Started/getting-started.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.

## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
subgraph Users["Users & Groups"]
UserA[User A<br/>eName: @user-a.w3id]
UserB[User B<br/>eName: @user-b.w3id]
Group1[Group 1<br/>eName: @group-1.w3id]
end

subgraph EVaults["eVaults"]
EVaultA[User A's eVault]
EVaultB[User B's eVault]
EVaultG1[Group 1's eVault]
end
Comment thread
coodos marked this conversation as resolved.

subgraph Platforms["Platforms"]
Blabsy[Blabsy]
Pictique[Pictique]
OtherPlatform[Other Platforms]
end

subgraph Infrastructure["Infrastructure"]
Registry[Registry Service<br/>W3ID Resolution]
EVaultCore[eVault Core<br/>GraphQL API]
end

UserA -->|Owns| EVaultA
UserB -->|Owns| EVaultB
Group1 -->|Owns| EVaultG1

Blabsy -->|Read/Write| EVaultA
Pictique -->|Read/Write| EVaultA
OtherPlatform -->|Read/Write| EVaultA

EVaultA -->|Webhooks| Blabsy
EVaultA -->|Webhooks| Pictique
EVaultA -->|Webhooks| OtherPlatform

Blabsy -.->|Resolve eName| Registry
Pictique -.->|Resolve eName| Registry
OtherPlatform -.->|Resolve eName| Registry
EVaultCore -->|Store Data| EVaultA

style UserA fill:#e1f5ff,color:#000000
style EVaultA fill:#fff4e1,color:#000000
style Blabsy fill:#e8f5e9,color:#000000
style Pictique fill:#e8f5e9,color:#000000
style Registry fill:#f3e5f5,color:#000000
style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)

@nsergey82nsergey82Jan 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?

@sosweethamsosweethamJan 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation

registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally

6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
participant User as User
participant Platform as Platform
participant LocalDB as Platform Database
participant Adapter as Web3 Adapter
participant Registry as Registry Service
participant EVault as User's eVault
participant OtherPlatforms as Other Platforms

User->>Platform: Create post
Platform->>LocalDB: Store post locally
Platform->>Adapter: Trigger sync
Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
Adapter->>Registry: Resolve eName to eVault URL
Registry-->>Adapter: Return eVault URL
Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
EVault->>EVault: Store MetaEnvelope
EVault-->>Adapter: Return stored MetaEnvelope
Adapter-->>Platform: Sync complete
EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
EVault->>Registry: Get active platforms
Registry-->>EVault: Return platform list
EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
participant User as User
participant Wallet as eID Wallet
participant Provisioner as Provisioner Service
participant Registry as Registry Service
participant EVault as eVault Core

User->>Wallet: Initiate onboarding
Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
Provisioner->>EVault: Create eVault instance
EVault-->>Provisioner: eVault URL
Provisioner->>Registry: Register eName → eVault URL
Registry->>Registry: Store W3ID mapping
Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
Registry-->>Provisioner: Registration complete
Provisioner->>EVault: Store public key<br/>(for signature verification)
EVault-->>Provisioner: Public key stored
Provisioner-->>Wallet: eVault URL + certificate
Wallet->>Wallet: Store eVault URL
Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
docs: add infrastructure, protocol, and getting started docs#721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

coodos
merged 10 commits into

from

Jan 26, 2026
 Merged


docs: add infrastructure, protocol, and getting started docs
#721
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


10 commits


Select commit
Hold shift + click to select a range
6fb93ec

docs: add infrastructure docs


coodos Jan 25, 2026
0d6bb33

docs: fix evault documentation


coodos Jan 25, 2026
a216618

docs: fix example for social media post


coodos Jan 25, 2026
e90b8cc

docs: fix contradiction around hw and sw keymanagers


coodos Jan 25, 2026
373c3da

chore: address points on getting started page


coodos Jan 26, 2026
1b18529

chore: fix code rabbit suggestions


coodos Jan 26, 2026
f543666

docs: address issues in eid wallet doc


coodos Jan 26, 2026
166838b

docs: address evault.md docs issues


coodos Jan 26, 2026
c528a0a

docs: address issues in auth & signing


coodos Jan 26, 2026
4c3b1c3

chore: fix broken lang blocks


coodos Jan 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


203 changes: 180 additions & 23 deletions
docs/docs/Getting Started/getting-started.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,46 +2,203 @@
sidebar_position: 1
---

# Tutorial Intro
# Getting Started with W3DS

Let's discover **Docusaurus in less than 5 minutes**.
Welcome to **W3DS (Web 3 Data Spaces)** - a decentralized data synchronization protocol that puts users in control of their data.

## Getting Started
## What is W3DS?

Get started by **creating a new site**.
W3DS is a protocol that enables seamless data synchronization across multiple platforms while ensuring users own and control their data. Instead of platforms storing user data in silos, W3DS allows users to store their data in their own **eVaults** and have platforms sync from these vaults.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
## Core Concept

### What you'll need
The fundamental principle of W3DS is simple: **Users, groups, and objects own their own eVaults**. All data about a person, group, or object is stored in their eVault, and platforms act as frontends that display and interact with this data, while also serving as caches and aggregators for improved performance and user experience.

- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
 - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
### Key Principles
Comment thread
nsergey82 marked this conversation as resolved.


## Generate a new site
1. **Data Ownership & Decentralized Storage**: Users own their data, not platforms. Each user has their own eVault for data storage, ensuring true data ownership and control.

Generate a new Docusaurus site using the **classic template**.
2. **Platform Independence & Automatic Synchronization**: Platforms are interchangeable frontends that automatically synchronize data, while also serving as caches and aggregators. Data created on one platform automatically appears on all platforms, enabling true interoperability across the ecosystem.

The classic template will automatically be added to your project after you run the command:
## How It Works: A Simple Example

```bash
npm init docusaurus@latest my-website classic
Imagine User A creates a post on **Blabsy** (a social media platform):

1. User A posts "Hello, world!" on Blabsy
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
3. User A's eVault stores the post and notifies all registered platforms
4. **Pictique** (another social media platform) receives the notification
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system

This is the power of W3DS: your data follows you across all platforms automatically.

## Architecture Overview

```mermaid
graph TB
 subgraph Users["Users & Groups"]
 UserA[User A<br/>eName: @user-a.w3id]
 UserB[User B<br/>eName: @user-b.w3id]
 Group1[Group 1<br/>eName: @group-1.w3id]
 end

 subgraph EVaults["eVaults"]
 EVaultA[User A's eVault]
 EVaultB[User B's eVault]
 EVaultG1[Group 1's eVault]
 end
Comment thread
coodos marked this conversation as resolved.


 subgraph Platforms["Platforms"]
 Blabsy[Blabsy]
 Pictique[Pictique]
 OtherPlatform[Other Platforms]
 end

 subgraph Infrastructure["Infrastructure"]
 Registry[Registry Service<br/>W3ID Resolution]
 EVaultCore[eVault Core<br/>GraphQL API]
 end

 UserA -->|Owns| EVaultA
 UserB -->|Owns| EVaultB
 Group1 -->|Owns| EVaultG1

 Blabsy -->|Read/Write| EVaultA
 Pictique -->|Read/Write| EVaultA
 OtherPlatform -->|Read/Write| EVaultA

 EVaultA -->|Webhooks| Blabsy
 EVaultA -->|Webhooks| Pictique
 EVaultA -->|Webhooks| OtherPlatform

 Blabsy -.->|Resolve eName| Registry
 Pictique -.->|Resolve eName| Registry
 OtherPlatform -.->|Resolve eName| Registry
 EVaultCore -->|Store Data| EVaultA

 style UserA fill:#e1f5ff,color:#000000
 style EVaultA fill:#fff4e1,color:#000000
 style Blabsy fill:#e8f5e9,color:#000000
 style Pictique fill:#e8f5e9,color:#000000
 style Registry fill:#f3e5f5,color:#000000
 style EVaultCore fill:#f3e5f5,color:#000000
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
## Key Components

### eVault Core

The command also installs all necessary dependencies you need to run Docusaurus.
The **eVault Core** is the central storage system that manages user data. It provides:

## Start your site
- **GraphQL API** for storing and retrieving data using MetaEnvelope storage for structured data
- **Webhook delivery** to notify platforms of data changes
- **Access control** via ACLs (Access Control Lists)

Run the development server:
### Web3 Adapter

```bash
cd my-website
npm run start
The **Web3 Adapter** is a library that platforms use to:

- Handle bidirectional data synchronization between local databases and eVaults
- Convert between platform-specific schemas and global ontology schemas

### Registry Service

The **Registry Service** provides:

- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
- **Platform registration**: Tracks active platforms for webhook delivery

### Platforms

**Platforms** are applications that:

- Display and interact with user data
- Act as caches and aggregators for improved performance
- Sync data to/from user eVaults
- Convert between local and global data schemas
- Handle webhooks to receive data updates

## Data Flow

When a user creates data on a platform:

```text
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
1. **User Action**: User creates a post, message, or other data
2. **Platform Database**: Platform stores data locally
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
4. **User's eVault**: eVault stores the data as a MetaEnvelope
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
@nsergey82nsergey82Jan 25, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we say somwhere that this is a very simple prototype-level implementation of the "awareness mechanism"?
@sosweethamsosweethamJan 25, 2026

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also might be worth having a sequence diagram of interactions between the layers inclusive of web 3 adapter internal implementation
registration sequence diagram might also help to understand the role of the provisioner and registry better for theoretical knowledge required to setup a w3ds environment locally
6. **All Platforms**: Other platforms receive webhooks and create the data locally

> **Note**: This is a simplified overview of the data flow. The current implementation uses a basic webhook delivery mechanism. For production deployments, platforms should implement message delivery queues to handle eVault and platform downtime gracefully, ensuring reliable data synchronization.

### Detailed Data Flow Sequence

The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:

```mermaid
sequenceDiagram
 participant User as User
 participant Platform as Platform
 participant LocalDB as Platform Database
 participant Adapter as Web3 Adapter
 participant Registry as Registry Service
 participant EVault as User's eVault
 participant OtherPlatforms as Other Platforms

 User->>Platform: Create post
 Platform->>LocalDB: Store post locally
 Platform->>Adapter: Trigger sync
 Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
 Adapter->>Registry: Resolve eName to eVault URL
 Registry-->>Adapter: Return eVault URL
 Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
 EVault->>EVault: Store MetaEnvelope
 EVault-->>Adapter: Return stored MetaEnvelope
 Adapter-->>Platform: Sync complete
 EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
 EVault->>Registry: Get active platforms
 Registry-->>EVault: Return platform list
 EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
 OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
```

### Registration Sequence

The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:

```mermaid
sequenceDiagram
 participant User as User
 participant Wallet as eID Wallet
 participant Provisioner as Provisioner Service
 participant Registry as Registry Service
 participant EVault as eVault Core

 User->>Wallet: Initiate onboarding
 Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
 Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
 Provisioner->>EVault: Create eVault instance
 EVault-->>Provisioner: eVault URL
 Provisioner->>Registry: Register eName → eVault URL
 Registry->>Registry: Store W3ID mapping
 Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
 Registry-->>Provisioner: Registration complete
 Provisioner->>EVault: Store public key<br/>(for signature verification)
 EVault-->>Provisioner: Public key stored
 Provisioner-->>Wallet: eVault URL + certificate
 Wallet->>Wallet: Store eVault URL
 Wallet-->>User: Onboarding complete
```

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
## Next Steps

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
- Learn more about [W3DS Basics](/docs/W3DS%20Basics/getting-started) - Deep dive into eVault ownership and data flow
- Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
- Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
- Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
- Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
Loading