@powerhousedao/academy 3.3.0-dev.1 → 3.3.0-dev.3

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 3.3.0-dev.3 (2025-07-08)
+
+### 🚀 Features
+
+- added operational hooks and utils in reactor-browser ([216f7d03d](https://github.com/powerhouse-inc/powerhouse/commit/216f7d03d))
+
+### ❤️ Thank You
+
+- acaldas
+
+## 3.3.0-dev.2 (2025-07-05)
+
+### 🩹 Fixes
+
+- **academy:** graphql at powerhouse update ([fea4eae24](https://github.com/powerhouse-inc/powerhouse/commit/fea4eae24))
+
+### ❤️ Thank You
+
+- Callme-T
+
 ## 3.3.0-dev.1 (2025-07-04)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/01-GetStarted/home.mdx

@@ -98,7 +98,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
       </h3>
     </div>
     <div className={styles.cardContent}>
-      <a href="/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI" className="path-button">Read & write through the API</a>
+      <a href="/academy/MasteryTrack/WorkWithData/UsingTheAPI" className="path-button">Read & write through the API</a>
       <a href="/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs" className="path-button">Create your own subgraph</a>
       <a href="/academy/MasteryTrack/WorkWithData/Analytics-Engine/intro" className="path-button">Use the analytics engine</a>
     </div>

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md

@@ -66,7 +66,7 @@ You can also add a new remote drive to your Connect environment programmatically
   `bash
   ph reactor
   `
-- 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).
+- 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/UsingSubgraphs).
 - Appropriate permissions to perform mutations.
 :::
 
@@ -143,6 +143,6 @@ This approach allows you to automate drive creation and integration with other s
 You've now experienced the use of GraphQL to modify or read data captured in Powerhouse for the first time. 
 You can now either continue with:
 - User interfaces and [build a custom drive experiences](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) 
-- Keep playing with data and the [Switchboard API](/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI)
+- Keep playing with data and the [Switchboard API](/academy/MasteryTrack/WorkWithData/UsingTheAPI)
 
 Enjoy!

package/docs/academy/02-MasteryTrack/04-WorkWithData/{02-GraphQLAtPowerhouse.md → 01-GraphQLAtPowerhouse.md}

@@ -1,9 +1,10 @@
 # GraphQL at Powerhouse
 
-In this section, we will cover **the core concepts of GraphQL with examples applied to the Powerhouse ecosystem**. More specifically, GraphQL is used as:
-- The **schema definition language (SDL)** for defining our document models and thereby self-documenting the API to the data model. It allows developers to define the structure and relationships of data in a strongly-typed format.
-- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically. Jump to the section [GraphQL and Subgraphs](/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs/GraphQLAndSubgraphs) to learn more about this.
+In this section, we will cover **the core concepts of GraphQL with examples applied to the Powerhouse ecosystem**. GraphQL plays a fundamental role in defining document model data schemas, handling data access patterns, and enabling event-driven workflows within the Powerhouse ecosystem.
 
+More specifically, GraphQL is used as:
+- The **schema definition language (SDL)** for defining our document models and thereby self-documenting the API to the data model. It allows developers to define the structure and relationships of data in a strongly-typed format.
+- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically.
 
 ### Why GraphQL?
 
@@ -152,5 +153,132 @@ When dealing with lists of data, GraphQL employs a pattern that includes:
     ```
 
 ---
+
+## GraphQL Subgraphs in Powerhouse
+
+Powerhouse structures its data into **subgraphs**, which are modular GraphQL services that connect to the Reactor (Powerhouse's core data infrastructure) or Operational Data Stores fueled by data from processors. Each subgraph has its own SDL, ensuring modularity and flexibility while working within the ecosystem.
+
+### Fetching data from the Reactor
+
+Powerhouse uses GraphQL to expose system-level data, such as drives, users, and operational records through the **System Subgraph**, which allows querying of drives, stored files and folders.
+
+### Operational data stores
+
+Custom subgraphs can be created to store and retrieve operational data in real time. For example, a subgraph can track file uploads and expose this data via GraphQL queries:
+
+```graphql title="File Schema Example"
+type File {
+  id: ID!
+  name: String!
+  size: Int!
+  createdAt: DateTime!
+}
+
+type Query {
+  getFile(id: ID!): File
+}
+```
+
+This schema ensures that every File entity has an ID, name, size, and timestamp, providing a structured approach to file management data.
+
+---
+
+## CQRS Architecture with GraphQL
+
+Powerhouse uses **CQRS (Command Query Responsibility Segregation)** to separate write operations (commands) from read operations (queries). This improves system scalability and flexibility:
+
+- **GraphQL Queries** handle read operations, retrieving structured data efficiently
+- **GraphQL Mutations** handle write operations, modifying the state in a controlled manner
+
+Powerhouse's subgraphs act as the read layer, while processors handle write operations into operational data stores. This prevents conflicts between querying and modifying data.
+
+| Layer | Role | GraphQL Usage | Implementation |
+| --- | --- | --- | --- |
+| Write Model (Commands) | Handles state changes (adding, modifying, deleting) | GraphQL Mutations | Processor |
+| Read Model (Queries) | Optimized for fetching/reading/retrieving data | GraphQL Queries | Subgraph |
+
+### Read and write separation  
+
+**Read Model (Query)**  
+- Optimized for data retrieval
+- Structured using GraphQL Queries
+- Aggregates and exposes data via a subgraph
+- Pulls data from Operational Data Stores, Analytics Stores, and Reactor
+- Subgraphs do not directly modify the data—they only expose pre-processed information
+
+```graphql title="Example Query Operation"
+query {
+  getFile(id: "123") {
+    name
+    size
+    createdAt
+  }
+}
+```
+
+**Write Model (Mutation)** 
+- Handles state changes (adding, modifying, deleting)
+- Structured using GraphQL Mutations
+- Writes data to Operational Data Stores
+
+```graphql title="Example Mutation Operation"
+mutation {
+  createFile(name: "document.pdf", size: 1024) {
+    id
+    name
+    createdAt
+  }
+}
+```
+
+---
+
+## GraphQL and Event-Driven Architecture
+
+Event-Driven Architecture (EDA) enables asynchronous processing where events trigger actions. Powerhouse uses GraphQL to expose real-time event data from its Reactor and Operational Data Stores.
+
+### How GraphQL fits into EDA
+
+- **Real-Time Data Exposure** – Subgraphs fetch event-based data updates
+- **Event Subscription Mechanism** – Powerhouse is working towards integrating GraphQL Subscriptions for real-time updates
+- **Efficient Decoupling** – Events are stored in an operational datastore, and GraphQL queries retrieve structured results
+
+### Example: Powerhouse's event flow
+
+1. Processor detects an event (e.g., file upload)
+2. Writes event data to the Operational Data Store
+3. Subgraph exposes the updated data via GraphQL
+
+---
+
+## GraphQL Subscriptions
+
+Although Powerhouse currently uses queries and mutations, **GraphQL Subscriptions** could allow real-time streaming of event-based data in future implementations:
+
+```graphql title="Example Future Subscription"
+subscription {
+  fileUploaded {
+    id
+    name
+    size
+    createdAt
+  }
+}
+```
+
+This would enable clients to listen for new file uploads without polling, providing a more efficient real-time experience.
+
+---
+
 ## Summary
-GraphQL offers a streamlined and efficient approach to data retrieval, particularly useful when you need granular control over your API interactions. By defining a robust schema, using precise fields and arguments, and leveraging introspection, GraphQL minimizes unnecessary data transfers. If you want to learn more about GraphQL, there is the following link to the official documentation: [Introduction to GraphQL](https://graphql.org/learn/).
+
+GraphQL offers a streamlined and efficient approach to data retrieval, particularly useful when you need granular control over your API interactions. In the Powerhouse ecosystem, GraphQL serves multiple critical functions:
+
+- **Schema Definition**: Defines document models and self-documents APIs
+- **Subgraph Architecture**: Enables modular, scalable data services
+- **CQRS Implementation**: Separates read and write operations for better performance
+- **Event-Driven Integration**: Supports real-time data exposure and future subscription capabilities
+
+By defining robust schemas, using precise fields and arguments, leveraging introspection, and implementing subgraphs with CQRS principles, GraphQL minimizes unnecessary data transfers while maximizing flexibility and scalability in the Powerhouse platform.
+
+For more information about GraphQL fundamentals, visit the [Introduction to GraphQL](https://graphql.org/learn/) documentation.

package/docs/academy/02-MasteryTrack/04-WorkWithData/{01-ReadingAndWritingThroughTheAPI.mdx → 02-UsingTheAPI.mdx}

@@ -1,9 +1,10 @@
-# Read and write through the API
+# Using the API
 
 ## Introduction to Switchboard
 
-**Switchboard** is the API interface that allows developers and data engineers to get access to data collected through document models in Connect and Fusion.
-After structurally capturing the desired data from your formalized business processes, it can be used to build insightful experiences in external websites, drive widgets, or create specific reports and dashboards in Fusion.
+**Switchboard** is the API interface that enables developers and data engineers to access data captured through document models in Connect and Fusion.
+
+Once you've structured and captured data from your business processes, Switchboard allows you to leverage that data to build insightful experiences in external websites, create interactive drive widgets, or generate detailed reports and dashboards in Fusion.
 
 :::tip Using your document's state schema
 Since your document models are defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your documents.
@@ -39,10 +40,10 @@ This will return a URL to access the Reactor.
 
 ### Adding a remote drive or Reactor to Connect
 
-If the remote drive or Reactor isn't present yet in Connect, you can add it by clicking the (+) button in the Connect drive navigation and using the localhost URL to add a new drive with its underlying reactor. Usually, this is http://localhost:4001/d/powerhouse.
+If the remote drive or Reactor isn't present yet in Connect, you can add it by clicking the (+) 'Create New Drive' button in the Connect drive navigation and using the localhost URL to add a new drive with its underlying reactor. Usually, this is http://localhost:4001/d/powerhouse.
 
 Get access to an **organization's drive** instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive URL.
-Click the (+) to add a public drive. To add a new drive, you'll have to know the correct public URL of the drive. Read more about [configuring drives](/academy/Architecture/WorkingWithTheReactor).
+Click the (+) 'Create New Drive' to add a public drive. To add a new drive, you'll have to know the correct public URL of the drive. Read more about [configuring drives](/academy/Architecture/WorkingWithTheReactor).
 
 <figure className="image-container">
   <img src={require("./images/AddNewDriveURL.png").default} alt="Add a drive through an URL" />
@@ -92,7 +93,7 @@ Copy this ID to use it in the Switchboard API.
   <figcaption>You can copy your Document ID from your operations history.</figcaption>
 </figure>
 
-When you navigate to your Switchboard endpoint (e.g., http://localhost:4001/graphql/system, https://switchboard.phd/graphql/system, or a custom domain), you can use this document ID to query the state of your document.
+When you navigate to your Switchboard endpoint by adding **`/graphql/system`** to the end of your URL. (e.g., http://localhost:4001/graphql/system, https://switchboard.phd/graphql/system, or add it to a custom domain), you can use this document ID to query the state of your document.
 The documentation on the left-hand side of the Apollo Sandbox will show you all the different fields that are available to query.
 
 <figure className="image-container">
@@ -128,7 +129,7 @@ It extracts common metadata fields such as **id**, **name**, **documentType**, *
 
 ### Get the state of the document
 
-Once you've found your document via any of the three options, you'll be able to query its state.
+Once you've found your document via any of the three options above, you'll be able to query its state.
 
 In the previous step, we queried for document metadata. Now let's query for the actual content of the document state.
 
@@ -230,4 +231,7 @@ After performing a write mutation, you can verify that the change was successful
 1.  **Query the document state again:** Rerun the `getDocument` query from earlier in this tutorial. You should see the new item in the list or the deleted item removed.
 2.  **Check the Operation History:** The operation history in Connect will show the new `ADD_TODO_ITEM` or `DELETE_TODO_ITEM` operation, along with who performed it and when. This provides a complete audit trail of all changes to the document.
 
+
+### Summary
+
 This ability to programmatically read from and write to documents via the GraphQL API is a powerful feature of Powerhouse. It unlocks countless possibilities for integrating your structured data into other applications, building automated workflows, and creating rich, data-driven user experiences.