@powerhousedao/academy 3.2.0-dev.9 → 3.2.0-staging.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +2 -48
  2. package/docs/academy/01-GetStarted/00-ExploreDemoPackage.mdx +51 -60
  3. package/docs/academy/01-GetStarted/01-CreateNewPowerhouseProject.md +28 -8
  4. package/docs/academy/01-GetStarted/02-DefineToDoListDocumentModel.md +1 -1
  5. package/docs/academy/01-GetStarted/images/OperationsHistory.png +0 -0
  6. package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md +29 -53
  7. package/docs/academy/02-MasteryTrack/04-WorkWithData/01-ReadingAndWritingThroughTheAPI.mdx +56 -174
  8. package/docs/academy/02-MasteryTrack/04-WorkWithData/04-analytics-processor.md +1 -281
  9. package/docs/academy/02-MasteryTrack/04-WorkWithData/05-AnalyticsProcessorTutorial/02-CreateNewPowerhouseProject.md +2 -4
  10. package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md +1 -2
  11. package/docs/academy/04-APIReferences/01-ReactHooks.md +5 -0
  12. package/docs/academy/06-ComponentLibrary/00-DocumentEngineering.md +0 -52
  13. package/docs/academy/07-Cookbook.md +2 -2
  14. package/package.json +1 -1
  15. package/src/css/custom.css +1 -22
  16. package/docs/academy/01-GetStarted/images/OperationsHistoryButton.png +0 -0
  17. package/docs/academy/01-GetStarted/images/OperationsHistorySignature.png +0 -0
  18. package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/images/Screenshot 2025-06-26 at 17.41.14.png +0 -0
  19. package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/images/AddDrive.png +0 -0
  20. package/docs/academy/02-MasteryTrack/04-WorkWithData/07-drive-analytics.md +0 -467
  21. package/docs/academy/02-MasteryTrack/04-WorkWithData/images/AddNewDriveURL.png +0 -0
  22. package/docs/academy/02-MasteryTrack/04-WorkWithData/images/DocumentID.png +0 -0
  23. package/docs/academy/02-MasteryTrack/04-WorkWithData/images/OnboardingTasks.png +0 -0
  24. package/docs/academy/02-MasteryTrack/04-WorkWithData/images/QueryDocument.png +0 -0
  25. package/docs/academy/02-MasteryTrack/04-WorkWithData/images/QueryDocument2.png +0 -0
  26. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/00-DocumentToolbar.mdx +0 -0
  27. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/01-OperationHistory.md +0 -0
  28. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/02-RevisionHistoryTimeline.md +0 -0
  29. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/_category_.json +0 -0
  30. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/DocumentToolbar.png +0 -0
  31. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/committer-address-popup.png +0 -0
  32. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/revision-hash-popup.png +0 -0
  33. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/revision-history-list.png +0 -0
  34. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/revision-history-timeline.png +0 -0
  35. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{06-DocumentTools → 07-DocumentTools}/images/signature-details-popup.png +0 -0
  36. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/01-RenownAuthenticationFlow.md +0 -0
  37. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/02-Authorization.md +0 -0
  38. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/_category_.json +0 -0
  39. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/images/ConnectAddress.png +0 -0
  40. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/images/LoginComplete.png +0 -0
  41. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/images/OperationsHistory.png +0 -0
  42. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/images/RenownLogin.png +0 -0
  43. /package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/{07-Authorization → 08-Authorization}/images/ReturnToConnect.png +0 -0
package/CHANGELOG.md CHANGED
@@ -1,52 +1,6 @@
1
- ## 3.2.0-dev.9 (2025-07-02)
1
+ ## 3.2.0-staging.0 (2025-06-26)
2
2
 
3
- ### 🩹 Fixes
4
-
5
- - updated processor generator and added codegen test for it ([6af3bbcf7](https://github.com/powerhouse-inc/powerhouse/commit/6af3bbcf7))
6
- - added test to generate and compile a generated document-model ([17bbca3bb](https://github.com/powerhouse-inc/powerhouse/commit/17bbca3bb))
7
-
8
- ### ❤️ Thank You
9
-
10
- - Benjamin Jordan (@thegoldenmule)
11
-
12
- ## 3.2.0-dev.8 (2025-07-01)
13
-
14
- ### 🚀 Features
15
-
16
- - **academy:** add Drive Analytics documentation and examples ([daedc28a3](https://github.com/powerhouse-inc/powerhouse/commit/daedc28a3))
17
-
18
- ### ❤️ Thank You
19
-
20
- - Guillermo Puente @gpuente
21
-
22
- ## 3.2.0-dev.7 (2025-06-28)
23
-
24
- ### 🚀 Features
25
-
26
- - starting to stub out a complete example of the analytics processor ([a84ed2dcf](https://github.com/powerhouse-inc/powerhouse/commit/a84ed2dcf))
27
-
28
- ### ❤️ Thank You
29
-
30
- - Benjamin Jordan (@thegoldenmule)
31
-
32
- ## 3.2.0-dev.6 (2025-06-27)
33
-
34
- ### 🚀 Features
35
-
36
- - **connect:** use atom store and provider from state library ([28f646636](https://github.com/powerhouse-inc/powerhouse/commit/28f646636))
37
- - added drive analytics processor ([#1607](https://github.com/powerhouse-inc/powerhouse/pull/1607))
38
-
39
- ### 🩹 Fixes
40
-
41
- - updated document-engineering ver ([3522179d6](https://github.com/powerhouse-inc/powerhouse/commit/3522179d6))
42
- - updated atoms with header changes ([2b557197a](https://github.com/powerhouse-inc/powerhouse/commit/2b557197a))
43
-
44
- ### ❤️ Thank You
45
-
46
- - Benjamin Jordan (@thegoldenmule)
47
- - Guillermo Puente
48
- - Guillermo Puente Sandoval
49
- - ryanwolhuter
3
+ This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
50
4
 
51
5
  ## 3.2.0-dev.5 (2025-06-26)
52
6
 
@@ -1,5 +1,18 @@
1
1
  # Explore the demo package
2
2
 
3
+ <details>
4
+ <summary>How long will this tutorial take?</summary>
5
+
6
+ We've designed this "Get Started" track to be as smooth as possible. The time it takes will vary based on your familiarity with modern web development tools.
7
+
8
+ - **For Experienced Developers** (familiar with TypeScript, React, and CLIs), you can expect to complete the entire four-part tutorial in approximately **1 to 1.5 hours**.
9
+ - **For Developers New to This Stack**, we recommend setting aside **3.5 to 4.5 hours**. This allows for time to understand not just the steps, but the core concepts behind them.
10
+
11
+ This is just a guideline. The goal is to learn comfortably and build a solid foundation with Powerhouse!
12
+
13
+ A more theoretical and advanced version of this tutorial can also be found in [Mastery Track - Document Model Creation](../MasteryTrack/DocumentModelCreation/WhatIsADocumentModel).
14
+ </details>
15
+
3
16
  ## Let's get started
4
17
 
5
18
  To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package?
@@ -96,55 +109,7 @@ Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, w
96
109
  <figcaption>The Package Manager showing the installed todo-demo-package.</figcaption>
97
110
  </figure>
98
111
 
99
- ## Step 4: Create a todo list document
100
-
101
- :::tip What is a 'drive' at Powerhouse?
102
- A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
103
- :::
104
-
105
- ### 4.1 Create a local todolist app drive
106
-
107
- First, let's create a dedicated drive for your to-do lists:
108
-
109
- - Click the new drive icon in the interface
110
- - In the **Drive App** field, select 'To-do Drive App'
111
- - This creates a specialized drive that's optimized for to-do list documents
112
-
113
- ### 4.2 Create a todolist document
114
-
115
- Now move into the drive you've just created:
116
-
117
- - Click the button at the bottom of the page to create a new to-do list document
118
- - This opens the to-do list editor where you can start managing your tasks
119
-
120
- ### 4.3 Add a few todos and inspect the document history
121
-
122
- - Add a few to-dos that are on your mind
123
- - You'll see a statistics widget that counts the open to-dos
124
- - After closing the document, look at the To-do Drive App interface—you'll see that it tracks your tasks and displays a progress bar
125
-
126
- <figure className="image-container">
127
- <img src={require("./images/TodoDriveApp.png").default} alt="Todo Drive App" />
128
- <figcaption>A list of todo's in the custom todo drive app. </figcaption>
129
- </figure>
130
-
131
- A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when.
132
-
133
- <figure className="image-container">
134
- <img src={require("./images/OperationsHistoryButton.png").default} alt="Operations History Button" />
135
- <figcaption> You can find the button to visit the operations history in the document model toolbar </figcaption>
136
- </figure>
137
-
138
- <figure className="image-container">
139
- <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
140
- <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
141
- </figure>
142
-
143
- Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
144
-
145
- This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
146
-
147
- ## Step 5: Enable operation signing and verification through Renown
112
+ ## Step 4: Log in with Renown
148
113
 
149
114
  Renown is Powerhouse's **decentralized identity and reputation system** designed to address the challenge of trust within open organizations, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities.
150
115
 
@@ -152,18 +117,16 @@ Renown is Powerhouse's **decentralized identity and reputation system** designed
152
117
  When signing in with Renown, use an Ethereum or blockchain address that can function as your 'identity', as this address will accrue more experience and history over time.
153
118
  :::
154
119
 
155
- ### 5.1 Click the renown icon and connect your eth identity
156
-
157
- "**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.
120
+ ### Login flow
121
+ "**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.
158
122
 
159
123
  <figure className="image-container">
160
124
  <img src={require("./images/RenownLogin.png").default} alt="Renown Login" />
161
125
  <figcaption>The Renown login screen, prompting for a signature from a wallet.</figcaption>
162
126
  </figure>
163
127
 
164
- ### 5.2 Authorize Connect to sign document edits on your behalf
165
-
166
- This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.
128
+ ### Generate a DID to sign operations in Connect
129
+ This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.
167
130
 
168
131
  <figure className="image-container">
169
132
  <img src={require("./images/ConnectAddress.png").default} alt="Connect Address for DID" />
@@ -175,17 +138,45 @@ This DID is then associated with a credential that authorizes a specific Connect
175
138
  <figcaption>Confirmation of a successful login with Renown.</figcaption>
176
139
  </figure>
177
140
 
178
- ### 5.3 Verify the signatures of new operations in the todo list
141
+ ### Verifying signatures
142
+ **Switchboard**, our (remote & local) data processing engine, acts as a verifier in the Renown authentication flow. Switchboard checks the validity of the DID and credential, ensuring the operation request is legitimate. This flow is designed to offer a verifiable, cryptographically secure login system that replaces traditional password-based authentication with decentralized identity and signature-based trust.
179
143
 
180
- By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity.
144
+ ## Step 5: Create a to-do list and explore the document operations history
145
+
146
+ <figure className="image-container">
147
+ <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
148
+ <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
149
+ </figure>
181
150
 
182
- Now, return to your to-do list and make some additional changes. You'll notice that these operations are now signed with your Renown identity, making every action traceable and verifiable in the operations history.
151
+ By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity.
152
+
153
+ A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when. This ensures every action is traceable and verifiable.
154
+ Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
155
+
156
+
157
+ ### 5.1 Create a to-do list
158
+
159
+ Now, move back to your local drive and create a to-do list. Add a few to-dos that are on your mind. You'll see a statistics widget that counts the open to-dos.
160
+
161
+ ### 5.2 Create a specific to-do drive app
162
+
163
+ :::tip What is a 'drive' at Powerhouse?
164
+ A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
165
+ :::
166
+
167
+ Since your previous to-do list was created inside a local drive with a general-purpose drive explorer, it didn't look particularly special.
168
+
169
+ - Now let's create a new drive by clicking the new drive icon. In the **Drive App** field, select 'To-do Drive App'.
170
+ - Now move into the drive you've just created and create a new to-do list by clicking the button at the bottom of the page.
171
+ - Add a new set of random to-dos
172
+ - After closing the document, look at the To-do Drive App interface. You'll see that it tracks your tasks and displays a progress bar.
183
173
 
184
174
  <figure className="image-container">
185
- <img src={require("./images/OperationsHistorySignature.png").default} alt="Operation History Signature" />
186
- <figcaption>Your DID is now signing the operations that are being added to the history.</figcaption>
175
+ <img src={require("./images/TodoDriveApp.png").default} alt="Operations History" />
176
+ <figcaption>A list of todo's in the custom todo drive app. </figcaption>
187
177
  </figure>
188
178
 
179
+ This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
189
180
  ## Step 6: Export a document
190
181
 
191
182
  Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network.
@@ -1,4 +1,4 @@
1
- # Create a new to-do list document
1
+ # Create a to-do list document
2
2
 
3
3
  ## Overview
4
4
  This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.
@@ -18,32 +18,52 @@ Create a new Powerhouse project with a single command:
18
18
  ```bash
19
19
  ph init
20
20
  ```
21
+ <details>
22
+ <summary>How to use different branches</summary>
23
+
24
+ When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches.
25
+ These branches contain more experimental features then the latest stable release the PH CLI uses by default.
26
+ They can be used to get access to a bugfix or features under development.
27
+
28
+ | Command | Description |
29
+ |---------|-------------|
30
+ | **pnpm install -g ph-cmd** | Install latest stable version |
31
+ | **pnpm install -g ph-cmd@dev** | Install development version |
32
+ | **pnpm install -g ph-cmd@staging** | Install staging version |
33
+ | **ph init** | Use latest stable version of the boilerplate |
34
+ | **ph init --dev** | Use development version of the boilerplate |
35
+ | **ph init --staging** | Use staging version of the boilerplate |
36
+ | **ph use** | Switch all dependencies to latest production versions |
37
+ | **ph use dev** | Switch all dependencies to development versions |
38
+ | **ph use prod** | Switch all dependencies to production versions |
39
+
40
+ Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
41
+ </details>
21
42
 
22
43
  ## Before you begin
23
44
  1. Open your terminal (either your system terminal or IDE's integrated terminal)
24
- 2. Optionally, create a folder first to keep your Powerhouse projects:
45
+ 2. Navigate to your desired project directory using:
25
46
 
26
47
  ```bash
27
- mkdir ph-projects
28
- cd ph-projects
48
+ cd your-directory
29
49
  ```
30
50
  3. Ensure you're in the correct directory before running the `ph init` command.
31
51
  In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
32
52
  ```bash
33
- you@yourmachine:~/ph-projects % ph init
53
+ you@yourmachine:~/Powerhouse$ ph init
34
54
 
35
- ? What is the project name? ‣ getting-started
55
+ ? What is the project name? ‣ <ToDoList>
36
56
  ```
37
57
 
38
58
  Once the project is created, you will see the following output:
39
59
  ```bash
40
- Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
60
+ Initialized empty Git repository in /Users/yourmachine/<ToDoList>/.git/
41
61
  The installation is done!
42
62
  ```
43
63
 
44
64
  Navigate to the newly created project directory:
45
65
  ```bash
46
- cd getting-started
66
+ cd <yourprojectname>
47
67
  ```
48
68
  Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
49
69
  Run the following command to start the Connect application:
@@ -1,4 +1,4 @@
1
- # Write the document specification
1
+ # Define the to-do list document specification
2
2
 
3
3
  In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
4
4
  If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
@@ -1,6 +1,6 @@
1
1
  # Configure a drive
2
2
 
3
- A drive in Powerhouse is a container for documents and data. It's a place where you can organize and store your documents and share them with others. This guide walks you through configuring and managing drives in your Powerhouse environment.
3
+ A drive in Powerhouse is a container or a wrapper for documents and data. It's a place where you can organize and store your documents and share them with others. This guide will walk you through the process of configuring and managing drives in your Powerhouse environment.
4
4
 
5
5
  :::info **Prerequisites**
6
6
 
@@ -14,74 +14,64 @@ Before configuring a drive, ensure you have:
14
14
 
15
15
  ### Local drives
16
16
 
17
- A local drive is a container for local documents and data, hosted on your local machine. Technically, a drive is itself a document that contains a list of the documents inside it. When you run Connect locally with `ph connect`, a local drive is automatically added. You can also create a new local drive by clicking **'Create New Drive'** in Connect.
17
+ A local drive is a container for local documents and data, hosted on your local machine. Technically a drive is just another document model with a list of the documents inside the drive. When you run connect locally with `ph connect` a local drive is automatically added. You can also create a new local drive by clicking **'add drive'** in connect.
18
18
 
19
19
  ### Remote drives vs. reactors
20
20
 
21
- Remote drives in Powerhouse allow you to connect to and work with data stored in external systems or cloud services. These drives act as bridges between Powerhouse contributors or other data sources, enabling seamless data synchronization. Drives can exist in three types of locations:
21
+ Remote drives in Powerhouse allow you to connect to and work with data stored in external systems or cloud services. These drives act as bridges between Powerhouse contributors and/or other data sources, enabling seamless data synchronization. Drives can exist in 3 category locations.
22
22
 
23
23
  - **Local Storage**: For offline or on-device access.
24
24
  - **Cloud Storage**: For centralized, scalable data management.
25
25
  - **Decentralized Storage**: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options.
26
26
 
27
27
  :::tip **Explainer**
28
- **Powerhouse Reactors** are the nodes in the network that store and synchronize documents and drives, resolve conflicts, and rerun operations to verify document event histories.
29
- Reactors can be configured for local storage, centralized cloud storage, or a decentralized storage network.
28
+ **Powerhouse Reactors** are the nodes in the network that store and synchronise documents & drives , resolve conflicts and rerun operations to verify document event histories.
29
+ Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network.
30
30
 
31
- A reactor allows you to store multiple documents and host **drives** and Drive Explorers with different organizational purposes, users, access rights, and more.
31
+ A reactor allows you to store multiple documents, but also host **drives** & Drive Explorers with different organisational purposes, users, access rights and more.
32
32
  :::
33
33
 
34
- A drive uses a reactor and its underlying storage layer. A reactor is the low-level component that enables the synchronization of documents and drives.
34
+ A drive exists by making use of a reactor and the storagelayer that specific reactor is based on. A reactor is the lower level component that makes synchronisation of documents & drives possible.
35
35
 
36
36
  ### Drive apps
37
37
 
38
- **Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with documents within a drive. As mentioned, a drive is technically just another document containing a list of other documents. This means you can create a custom editor for your drive document.
38
+ **Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with document models within a drive. As mentioned previously, technically a drive is just another document, with a list of the documents inside the drive. So it is obvious that you can create a custom editor for your drive-document.
39
39
 
40
- These customized editors are called Drive Explorers or Drive Apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive Explorer might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing.
40
+ These customized editors are called Drive explorers or Drive Apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive Explorer might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing.
41
41
 
42
42
  To learn more about building and customizing Drive Explorers, check out our [Building a Drive Explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) guide.
43
43
 
44
44
 
45
45
  ## Creating a new drive
46
46
 
47
- <figure className="image-container">
48
- <img src={require("./images/CreateDrive.png").default} alt="Create a new drive" />
49
- <figcaption>The drive management modal after clicking the 'Create New Drive' button.</figcaption>
50
- </figure>
47
+ ![Create New Drive](./images/CreateNewDrive.png)
51
48
 
52
49
  To create a new drive in Powerhouse, follow these steps:
53
- 1. Click the "**Create New Drive**" button in the Connect interface or the **+** icon in the Connect sidebar.
50
+ 1. Click on the "**Create New Drive**" button in the Connect interface or in the Connect sidebar on the (+) Icon.
54
51
  2. In the modal that appears, enter a name for your drive in the "**Drive Name**" field.
55
52
  3. Select the desired Drive App (such as the Generic Drive Explorer, or any other Drive App you've installed).
56
53
  4. Choose the location for your drive: **Local** (only available to you), **Cloud** (available to people in this drive), or **Public** (available to everyone).
57
54
  5. (Optional) Enable the "Make available offline" toggle if you want to keep a local backup of your drive.
58
55
  6. Once all options are set, click the "Create new drive" button to finalize and create your drive.
59
56
 
60
- ## Add a new remote drive via GraphQL mutation
57
+ ## Adding a new remote drive via graphql mutation
61
58
 
62
59
  You can also add a new remote drive to your Connect environment programmatically using GraphQL mutations. This is especially useful for automation, scripting, or integrating with external systems.
63
60
 
64
61
  :::info **Prerequisites**
65
- - Access to the Switchboard or remote reactor (server node) of your Connect instance. In your local project, you can start your Reactor by running the following command in a different terminal from Connect Studio.
66
- `bash
67
- ph reactor
68
- `
69
- - The GraphQL endpoint of your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql/system` (this is a supergraph gateway. Read more about [subgraphs and supergraphs here](/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs).
62
+ - Access to the Switchboard or remote reactor (server node) of your Connect instance.
63
+ - The GraphQL endpoint for your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql/system` (this is a supergraph gateway).
70
64
  - Appropriate permissions to perform mutations.
71
65
  :::
72
66
 
73
- <figure className="image-container">
74
- <img src={require("./images/CreateNewDrive.png").default} alt="Create a new drive" />
75
- <figcaption>The GraphQL interface for creating a new drive through a mutation.</figcaption>
76
- </figure>
67
+ ### Steps
68
+ 1. **Navigate to the GraphQL Playground or use a GraphQL client**
69
+ - Open [https://staging.switchboard.phd/graphql/system](https://staging.switchboard.phd/graphql/system) in your browser, or use a tool like [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/).
77
70
 
78
- ### 1. **Navigate to the GraphQL Playground or use a GraphQL client**
79
- - Open [https://switchboard.phd/graphql/system](https://switchboard.phd/graphql/system) in your browser, or use a tool like [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/).
80
-
81
- ### 2. **Prepare the Mutation**
71
+ 2. **Prepare the Mutation**
82
72
  - Use the following mutation to create a new drive:
83
73
 
84
- ```graphql title="Create Drive Mutation"
74
+ ```graphql
85
75
  mutation Mutation($name: String!, $icon: String, $addDriveId: String, $slug: String) {
86
76
  addDrive(name: $name, icon: $icon, id: $addDriveId, slug: $slug) {
87
77
  icon
@@ -92,8 +82,8 @@ You can also add a new remote drive to your Connect environment programmatically
92
82
  }
93
83
  ```
94
84
 
95
- - These are the example variables, feel free to change these as you like and add a different name or logo for your drive:
96
- ```json title="Example Variables"
85
+ - Example variables:
86
+ ```json
97
87
  {
98
88
  "name": "AcademyTest",
99
89
  "icon": "https://static.thenounproject.com/png/3009860-200.png",
@@ -101,12 +91,12 @@ You can also add a new remote drive to your Connect environment programmatically
101
91
  "slug": null
102
92
  }
103
93
  ```
104
- - You can also provide a custom `id` or `slug` if needed.
94
+ - You can also provide a custom `id`, `slug`, or `preferredEditor` if needed.
105
95
 
106
- ### 3. **Execute the Mutation**
96
+ 3. **Execute the Mutation**
107
97
  - Run the mutation. On success, you will receive a response containing the new drive's `icon`, `id`, `name`, and `slug`:
108
98
 
109
- ```json title="Successful Response"
99
+ ```json
110
100
  {
111
101
  "data": {
112
102
  "addDrive": {
@@ -119,30 +109,16 @@ You can also add a new remote drive to your Connect environment programmatically
119
109
  }
120
110
  ```
121
111
 
122
- ### 4. **Construct the Drive URL**
112
+ 4. **Construct the Drive URL**
123
113
  - Once you have the `id` or `slug`, you can construct the drive URL for Connect:
124
- - Format: `domain/d/<driveId>` or `domain/d/<driveSlug>`
125
- - Depending on whether you are using a hosted or a local environment, the domain in your URL will change.
126
- - Example: `https://connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
127
- - Example: `https://localhost:4001/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
128
-
129
- ### 5. **Add the Drive in Connect**
130
- - Use the constructed URL to add or access the drive in your Connect environment via the 'Add Drive' button.
114
+ - Format: `domain/d/driveId` or `domain/d/driveSlug`
115
+ - Example: `https://staging.connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
131
116
 
132
- <figure className="image-container">
133
- <img src={require("./images/AddDrive.png").default} alt="Create a new drive" />
134
- <figcaption>The 'Add Drive' button that allows you to enter your constructed Drive URL.</figcaption>
135
- </figure>
117
+ 5. **Add the Drive in Connect**
118
+ - Use the constructed URL to add or access the drive in your Connect environment.
136
119
 
137
120
  ---
138
121
 
139
122
  This approach allows you to automate drive creation and integration with other systems, making it easy to manage drives at scale.
140
123
 
141
- ## Up next
142
-
143
- You've now experienced the use of GraphQL to modify or read data captured in Powerhouse for the first time.
144
- You can now either continue with:
145
- - User interfaces and [build a custom drive experiences](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
146
- - Keep playing with data and the [Switchboard API](/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI)
147
124
 
148
- Enjoy!