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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.3.0-dev.1",
+  "version": "3.3.0-dev.3",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/src/components/HomepageFeatures/index.tsx

@@ -25,7 +25,7 @@ const FeatureList: FeatureItem[] = [
   {
     title: "Switchboard",
     imageSrc: require("@site/static/img/switchboard.png").default,
-    docPath: "/docs/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI",
+    docPath: "/docs/academy/MasteryTrack/WorkWithData/UsingTheAPI",
     description: <>Get access to the open API interface with Switchboard</>,
   },
   {
@@ -200,7 +200,7 @@ export default function HomepageFeatures() {
               <h3 className={styles.cardTitle}>Work with Data</h3>
             </div>
             <div className={styles.cardContent}>
-              <a href="//docs/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI" className={styles.pathButton}>Reading & Writing through the API</a>
+              <a href="//docs/academy/MasteryTrack/WorkWithData/UsingTheAPI" className={styles.pathButton}>Reading & Writing through the API</a>
               <a href="/docs/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs" className={styles.pathButton}>Create your own Subgraph</a>
               <a href="/docs/academy/WorkWithData/Analytics Engine/intro" className={styles.pathButton}>Using the Analytics Engine</a>
             </div>

package/docs/academy/02-MasteryTrack/04-WorkWithData/03-WorkingWithSubgraphs/02-GraphQLAndSubgraphs.mdx

@@ -1,119 +0,0 @@
-# GraphQL and subgraphs
-
-GraphQL plays a fundamental role in defining document model data schemas, handling data access patterns, and enabling event-driven workflows within the Powerhouse ecosystem.   
-This document provides an intro to graphQL and how it is used at Powerhouse when dealing with subgraphs
-
-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.
-
-
-## Powerhouse's use of GraphQL subgraphs
-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 a processor.
-
-### Fetching data from the Reactor
-
-Powerhouse uses GraphQL to expose system-level data, such as drives, users, and operational records.  
-Example: The **System Subgraph** 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.
-Example: A subgraph can track file uploads and expose this data via GraphQL queries.    ????
-
-??
-
-```graphql
-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.
-
-??
-
-In Powerhouse, each subgraph has its own SDL, ensuring modularity and flexibility while working within the ecosystem.
-
-## CQRS breakdown
-
-Powerhouse uses CQRS 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 of a Powerhouse Contributor schema in GraphQL"
-query {
-  getFile(id: "123") {
-    name
-    size
-  }
-}
-```
-
-**Write Model (Mutation)** 
-- Handles state changes (adding, modifying, deleting)
-- Structured using GraphQL Mutations
-- Writes data to Operational Data Stores
-
-```graphql title="Example of a Powerhouse Contributor schema in GraphQL"
-mutation {
-  createFile(name: "document.pdf", size: 1024) {
-    id
-    name
-  }
-}
-```
-
-### GraphQL and event-driven architecture (EDA)
-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.
-
-#### Example (future implementation):
-
-```graphql 
-subscription {
-  fileUploaded {
-    id
-    name
-  }
-}
-```
-This would enable clients to listen for new file uploads without polling.

package/docs/academy/02-MasteryTrack/04-WorkWithData/03-WorkingWithSubgraphs/03-WorkingWithSubgraphs.md

@@ -1,312 +0,0 @@
-# Working with subgraphs
-
-This tutorial will demonstrate how to create and customize a subgraph using our To-do List project as an example.
-Let's start with the basics and gradually add more complex features and functionality.
-
-## What is a subgraph?
-
-A subgraph in Powerhouse is a **GraphQL-based modular data component** that extends the functionality of your document models. While document models handle the core state and operations, subgraphs can:
-1. Connect to external APIs or databases
-2. Add custom queries and mutations
-3. Automate interactions between different document models
-4. Provide additional backend functionality
-
-### Subgraphs can retrieve data from
-
-- **The Reactor** – The core Powerhouse data system or network node.   
-- **Operational Data Stores** – Structured data storage for operational processes, offering real-time updates, for querying structured data.  
-- **Analytics Stores** – Aggregated historical data, useful for insights, reporting and business intelligence.
-
-### Subgraphs consist of
-
-- **A schema** – Which defines the GraphQL Queries and Mutations.
-- **Resolvers** – Which handle data fetching and logic.
-- **Context Fields** – Additional metadata that helps in resolving data efficiently.
-
-#### Additionally, context fields allow resolvers to access extra information, such as:
-- **User authentication** (e.g., checking if a user is an admin).
-- **External data sources** (e.g., analytics).
-
-
-
-```typescript title="Example of a context field"
-context: {
-  admin: async (session) => {
-    const admins = await operationalStore.get("admins");
-    return admins.includes(session.user);
-  }
-}
-```
-
-## 1. How to generate a subgraph
-
-Lets start by generating a new subgraph. For our tutorial we will create a new subgraph within our To-do List project.   
-Open your project and start your terminal.
-The Powerhouse toolkit provides a command-line utility to create new subgraphs easily.   
-
-```bash title="Run the following command to generate a new subgraph"
-ph generate --subgraph <to-do-list-subgraph>
-```
-
-```bash title="Expected Output"
-Loaded templates: node_modules/@powerhousedao/codegen/dist/codegen/.hygen/templates
-       FORCED: ./subgraphs/to-do-list-subgraph/index.ts
-     skipped: ./subgraphs/index.ts
-      inject: ./subgraphs/index.ts
-```
-
-### What happened?
-1. A new subgraph was created in `./subgraphs/to-do-list-subgraph/`
-2. The subgraph was automatically registered in your project's registry
-3. Basic boilerplate code was generated with an example query
-
-If we now run 'phreactor' we will see the new subgraph being registered during the startup of the Reactor.
-  > Registered /todolist subgraph.
-
-## 2. Customizing your subgraph with a schema
-
-Now that we've generated our subgraph, let's open it and define the schema inside the `index.ts` file.
-
-### 2.1 Define the schema
-
-Here we define the schema (typeDefs) which defines the structure of your queries and mutations.
-For educational purposes we will define a simple query that mimics the functionality of the todoList interface (or editor): 
-- Returns the total number of todo's
-- The number of todo's that are checked
-- The number of todo's that are not checked
-
-
-
-```graphql
-type Query {
-  fileIds: [String]
-}
-```
-
-### What happened?
-
-- Added two queries: todoList and todoItems
-- Created an operational table todo_items to store the todo items
-- Added resolvers to fetch and filter todo items
-- Removed the example code
-- The todoItems query accepts an optional checked parameter to filter items by their status
-- The todoList query returns the full list with its statistics
-
-
-### 2.2 Implement the resolver for the subgraph's schema
-Resolvers define how data is retrieved or modified.
-If you query for a specific value you can retrieve the value from either the reactor itself or an operational datastore.    
-We'll look into this in more detail in the next section.
-
-```js
-resolvers: {
-  Query: {
-    fileIds: async () => {
-      return ["file1", "file2", "file3"];
-    }
-  }
-}
-```
-
-### 2.3 Add operational data storage (optional)
-If you need to persist data, initialize an operational datastore inside onSetup():
-
-```typescript title="Adding an operational datastore"
-async onSetup() {
-  await this.createOperationalTables();
-}
-
-async createOperationalTables() {
-  await this.operationalStore.schema.createTableIfNotExists(
-    "fileIds",
-    (table) => {
-      table.string("id").primary();
-    }
-  );
-}
-```
-
-### 2.4 Fetching from an operational store
-If your subgraph interacts with an Operational Data Store, modify the resolver:
-
-```typescript title="Example of a resolver that fetches data from an operational store"
-resolvers: {
-  Query: {
-    fileIds: async (_, __, { operationalStore }) => {
-      return await operationalStore.getAll("fileIds");
-    }
-  }
-}
-```
-
-### 2.5 Connecting to a processor (optional, but recommended)
-
-#### Why connect a processor?
-Subgraphs alone are limited. A subgraph only queries data, but doesn't generate or store it.
-To make subgraphs useful, connect them with processors that update the data dynamically.
-**A processor listens to system events and updates the operational store in real-time.**
-
-Making use of a processor allows for:
-- **Live updates** instead of static data.
-- **Scalable architecture** through event-driven data changes.
-- **Seamless integration** with other Powerhouse components.
-
-Inside your processor, you can listen for new files, which in turn update the datastore:
-
-```typescript title="Example: Creating a Simple Processor"
-async process(event) {
-  if (event.type === "ADD_FILE") {
-    await this.operationalStore.insert("fileIds", { id: event.fileId });
-  }
-}
-```
-
-Then, modify your subgraph resolver to return real-time data:
-
-```js
-resolvers: {
-  Query: {
-    fileIds: async (_, __, { operationalStore }) => {
-      return await operationalStore.getAll("fileIds");
-    }
-  }
-}
-```
-
-## 3. Testing the subgraph
-
-### 3.1. Start the reactor
-To activate the subgraph, run:
-
-```bash
-ph reactor
-```
-Or, for full system startup:
-
-```bash title="Start the Reactor & Connect in Studio or Locally
-ph dev 
-```
-
-### 3.2. Access GraphQL playground
-Open your browser and go to:
-
-```bash
-http://localhost:4001/<subgraph-name>
-```
-Example:
-
-```bash
-http://localhost:4001/test-subgraph
-```
-
-### 3.3. Run a query
-
-```graphql
-query {
-  fileIds
-}
-```
-
-### 3.4. Expected response
-If everything works, you should see:
-
-```json
-{
-  "data": {
-    "fileIds": ["file1", "file2", "file3"]
-  }
-}
-```
-
-## 4. Working with the supergraph or gateway
-
-A supergraph is a GraphQL schema that combines multiple underlying GraphQL APIs, known as subgraphs, into a single, unified graph. This architecture allows different teams to work independently on their respective services (subgraphs) while providing a single entry point for clients or users to query all available data
-
-### 4.1 Key concepts
-
-*   **Subgraph:** An independent GraphQL service with its own schema. Each subgraph typically represents a specific domain or microservice within a larger system.
-*   **Gateway/Router:** A server that sits in front of the subgraphs. It receives client queries, consults the supergraph schema, and routes parts of the query to the relevant subgraphs. It then stitches the results back together before sending the final response to the client.
-
-### 4.2 Benefits of using a supergraph
-
-*   **Federated Architecture:** Enables a microservices-based approach where different teams can own and operate their services independently.
-*   **Scalability:** Individual subgraphs can be scaled independently based on their specific needs.
-*   **Improved Developer Experience:** Clients interact with a single, consistent GraphQL API, simplifying data fetching and reducing the need to manage multiple endpoints.
-*   **Schema Evolution:** Subgraphs can evolve their schemas independently, and the supergraph can be updated without breaking existing clients, as long as breaking changes are managed carefully.
-*   **Clear Separation of Concerns:** Each subgraph focuses on a specific domain, leading to more maintainable and understandable codebases.
-
-
-### 4.3 Use the Powerhouse supergraph
-
-The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To get to the endpoint open your localhost by starting the reactor and adding `graphql` to the end of the url. The following commands explain how you can test & try the supergraph. 
-
-- Start the reactor:
-
-  ```bash
-  ph reactor
-  ```
-
-- Open the GraphQL editor in your browser:
-
-  ```
-  http://localhost:4001/graphql
-  ```
-
-The supergraph allows to both query & mutate data from the same endpoint. 
-
-- Create a todo document in the `powerhouse` drive using the `ToDo_createDocument` mutation.
-  ![ToDo_createDocument](https://i.ibb.co/GQTZr7Wk/Screenshot-2025-05-01-at-1-22-23-PM.png)
-
-- Get the document state using the `GetDocument` query.
-  ![GetDocument](https://i.ibb.co/v47cj4Q4/Screenshot-2025-05-01-at-1-22-41-PM.png)
-
-- In a different terminal, start connect:
-
-  ```bash
-  ph connect
-  ```
-
-- Open Connect and add the `powerhouse` drive:
-
-  ```
-  http://localhost:4001/d/powerhouse
-  ```
-
-- You should now see the todo document you've created earlier. Edit the todo document with the document editor and add a few tasks that you can query later. 
-
-- Go back to the GraphQL explorer and use the `GetDocument` query again — you should see the updated state.
-
-This is a quick example of how the supegraph can be used. 
-
-
-## Subgraphs are particularly useful for
-
-1. **Cross-Document Interactions**: For example, connecting a To-do List with an Invoice document model:
-   - When an invoice-related task is marked complete, update the invoice status
-   - When an invoice is paid, automatically check off related tasks
-
-2. **External Integrations**: 
-   - Sync tasks with external project management tools
-   - Connect with notification systems
-   - Integrate with analytics platforms
-
-3. **Custom Business Logic**:
-   - Implement complex task prioritization
-   - Add automated task assignments
-   - Create custom reporting functionality
-
-### Prebuilt subgraphs
-
-Some subgraphs (e.g., System Subgraph, Drive Subgraph) already exist.  
-To integrate with them, register them via the Reactor API.
-
-### Future enhancements
-
-Bridge Processors and Subgraphs – Currently, there's a gap in how processors and subgraphs interact. Powerhouse might improve this in future updates.
-
-
-
-
-
-
-

package/docs/academy/02-MasteryTrack/04-WorkWithData/03-WorkingWithSubgraphs/_category_.json

@@ -1,8 +0,0 @@
-{
-    "label": "Working With Subgraphs",
-    "position": 4,
-    "link": {
-      "type": "generated-index",
-      "description": "Learn how to work with graphQL, subgraphs, and processors in Powerhouse."
-    }
-}