Skip to content

Commit 483bcc6

Browse files
coodoscoodos
authored
docs: add infrastructure, protocol, and getting started docs (#721)
* docs: add infrastructure docs * docs: fix evault documentation * docs: fix example for social media post * docs: fix contradiction around hw and sw keymanagers * chore: address points on getting started page * chore: fix code rabbit suggestions * docs: address issues in eid wallet doc * docs: address evault.md docs issues * docs: address issues in auth & signing * chore: fix broken lang blocks
1 parent 27b7e8a commit 483bcc6

8 files changed

Lines changed: 2307 additions & 49 deletions

File tree

‎docs/docs/Getting Started/getting-started.md‎

Lines changed: 180 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,46 +2,203 @@
22
sidebar_position: 1
33
---
44

5-
# Tutorial Intro
5+
# Getting Started with W3DS
66

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

9-
## Getting Started
9+
## What is W3DS?
1010

11-
Get started by **creating a new site**.
11+
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.
1212

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

15-
### What you'll need
15+
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.
1616

17-
- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
18-
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
17+
### Key Principles
1918

20-
## Generate a new site
19+
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.
2120

22-
Generate a new Docusaurus site using the **classic template**.
21+
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.
2322

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

26-
```bash
27-
npm init docusaurus@latest my-website classic
25+
Imagine User A creates a post on **Blabsy** (a social media platform):
26+
27+
1. User A posts "Hello, world!" on Blabsy
28+
2. Blabsy's Web3 Adapter syncs the post to User A's eVault
29+
3. User A's eVault stores the post and notifies all registered platforms
30+
4. **Pictique** (another social media platform) receives the notification
31+
5. Pictique creates the post locally - User A's post automatically appears on Pictique through the synchronization system
32+
33+
This is the power of W3DS: your data follows you across all platforms automatically.
34+
35+
## Architecture Overview
36+
37+
```mermaid
38+
graph TB
39+
subgraph Users["Users & Groups"]
40+
UserA[User A<br/>eName: @user-a.w3id]
41+
UserB[User B<br/>eName: @user-b.w3id]
42+
Group1[Group 1<br/>eName: @group-1.w3id]
43+
end
44+
45+
subgraph EVaults["eVaults"]
46+
EVaultA[User A's eVault]
47+
EVaultB[User B's eVault]
48+
EVaultG1[Group 1's eVault]
49+
end
50+
51+
subgraph Platforms["Platforms"]
52+
Blabsy[Blabsy]
53+
Pictique[Pictique]
54+
OtherPlatform[Other Platforms]
55+
end
56+
57+
subgraph Infrastructure["Infrastructure"]
58+
Registry[Registry Service<br/>W3ID Resolution]
59+
EVaultCore[eVault Core<br/>GraphQL API]
60+
end
61+
62+
UserA -->|Owns| EVaultA
63+
UserB -->|Owns| EVaultB
64+
Group1 -->|Owns| EVaultG1
65+
66+
Blabsy -->|Read/Write| EVaultA
67+
Pictique -->|Read/Write| EVaultA
68+
OtherPlatform -->|Read/Write| EVaultA
69+
70+
EVaultA -->|Webhooks| Blabsy
71+
EVaultA -->|Webhooks| Pictique
72+
EVaultA -->|Webhooks| OtherPlatform
73+
74+
Blabsy -.->|Resolve eName| Registry
75+
Pictique -.->|Resolve eName| Registry
76+
OtherPlatform -.->|Resolve eName| Registry
77+
EVaultCore -->|Store Data| EVaultA
78+
79+
style UserA fill:#e1f5ff,color:#000000
80+
style EVaultA fill:#fff4e1,color:#000000
81+
style Blabsy fill:#e8f5e9,color:#000000
82+
style Pictique fill:#e8f5e9,color:#000000
83+
style Registry fill:#f3e5f5,color:#000000
84+
style EVaultCore fill:#f3e5f5,color:#000000
2885
```
2986

30-
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
87+
## Key Components
88+
89+
### eVault Core
3190

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

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

36-
Run the development server:
97+
### Web3 Adapter
3798

38-
```bash
39-
cd my-website
40-
npm run start
99+
The **Web3 Adapter** is a library that platforms use to:
100+
101+
- Handle bidirectional data synchronization between local databases and eVaults
102+
- Convert between platform-specific schemas and global ontology schemas
103+
104+
### Registry Service
105+
106+
The **Registry Service** provides:
107+
108+
- **W3ID resolution**: Maps eNames (like `@user-a.w3id`) to eVault URLs
109+
- **Key binding certificates**: Stores user public keys for signature verification (used when platforms verify user signatures during authentication)
110+
- **Platform registration**: Tracks active platforms for webhook delivery
111+
112+
### Platforms
113+
114+
**Platforms** are applications that:
115+
116+
- Display and interact with user data
117+
- Act as caches and aggregators for improved performance
118+
- Sync data to/from user eVaults
119+
- Convert between local and global data schemas
120+
- Handle webhooks to receive data updates
121+
122+
## Data Flow
123+
124+
When a user creates data on a platform:
125+
126+
```text
127+
User Action → Platform Database → Web3 Adapter → User's eVault → Webhooks → All Platforms
41128
```
42129

43-
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.
130+
1. **User Action**: User creates a post, message, or other data
131+
2. **Platform Database**: Platform stores data locally
132+
3. **Web3 Adapter**: Adapter converts data to global schema and syncs to eVault
133+
4. **User's eVault**: eVault stores the data as a MetaEnvelope
134+
5. **Webhooks**: eVault sends webhooks to all registered platforms (except the originating one)
135+
6. **All Platforms**: Other platforms receive webhooks and create the data locally
136+
137+
> **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.
138+
139+
### Detailed Data Flow Sequence
140+
141+
The following sequence diagram shows the detailed interactions between components, including the Web3 Adapter's internal implementation:
142+
143+
```mermaid
144+
sequenceDiagram
145+
participant User as User
146+
participant Platform as Platform
147+
participant LocalDB as Platform Database
148+
participant Adapter as Web3 Adapter
149+
participant Registry as Registry Service
150+
participant EVault as User's eVault
151+
participant OtherPlatforms as Other Platforms
152+
153+
User->>Platform: Create post
154+
Platform->>LocalDB: Store post locally
155+
Platform->>Adapter: Trigger sync
156+
Adapter->>Adapter: Convert to global schema<br/>(ontology mapping)
157+
Adapter->>Registry: Resolve eName to eVault URL
158+
Registry-->>Adapter: Return eVault URL
159+
Adapter->>EVault: POST GraphQL mutation<br/>(storeMetaEnvelope)
160+
EVault->>EVault: Store MetaEnvelope
161+
EVault-->>Adapter: Return stored MetaEnvelope
162+
Adapter-->>Platform: Sync complete
163+
EVault->>EVault: Wait 3 seconds<br/>(prevent ping-pong)
164+
EVault->>Registry: Get active platforms
165+
Registry-->>EVault: Return platform list
166+
EVault->>OtherPlatforms: POST webhook<br/>(data change notification)
167+
OtherPlatforms->>OtherPlatforms: Process webhook<br/>(create post locally)
168+
```
169+
170+
### Registration Sequence
171+
172+
The following sequence diagram shows how a new user registers and creates their eVault, illustrating the roles of the Provisioner and Registry services:
173+
174+
```mermaid
175+
sequenceDiagram
176+
participant User as User
177+
participant Wallet as eID Wallet
178+
participant Provisioner as Provisioner Service
179+
participant Registry as Registry Service
180+
participant EVault as eVault Core
181+
182+
User->>Wallet: Initiate onboarding
183+
Wallet->>Wallet: Generate hardware keys<br/>(ECDSA P-256)
184+
Wallet->>Provisioner: POST /provision<br/>(eName, publicKey)
185+
Provisioner->>EVault: Create eVault instance
186+
EVault-->>Provisioner: eVault URL
187+
Provisioner->>Registry: Register eName → eVault URL
188+
Registry->>Registry: Store W3ID mapping
189+
Registry->>Registry: Issue key binding certificate<br/>(JWT with public key)
190+
Registry-->>Provisioner: Registration complete
191+
Provisioner->>EVault: Store public key<br/>(for signature verification)
192+
EVault-->>Provisioner: Public key stored
193+
Provisioner-->>Wallet: eVault URL + certificate
194+
Wallet->>Wallet: Store eVault URL
195+
Wallet-->>User: Onboarding complete
196+
```
44197

45-
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/.
198+
## Next Steps
46199

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

0 commit comments

Comments
 (0)