@powerhousedao/academy 4.1.0-staging.1 → 5.0.0-staging.10

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

@@ -6,6 +6,7 @@ Let's start with the basics and gradually add more complex features and function
 ## 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
@@ -13,8 +14,8 @@ A subgraph in Powerhouse is a **GraphQL-based modular data component** that exte
 
 ### Subgraphs can retrieve data from
 
-- **The Reactor** – The core Powerhouse data system or network node.   
-- **Relational Data Stores** – Structured data storage for operational processes, offering real-time updates, for querying structured data.  
+- **The Reactor** – The core Powerhouse data system or network node.
+- **Relational 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
@@ -24,22 +25,21 @@ A subgraph in Powerhouse is a **GraphQL-based modular data component** that exte
 - **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).
 
-
-
 ## Example: Implement a search subgraph based on data from the reactor
 
-In this example we implement a subgraph which allows to search through todo-list documents in a specific document drive. 
+In this example we implement a subgraph which allows to search through todo-list documents in a specific document drive.
 
 First we will generate the subgraph with the help of the ph cli, then we will define the GraphQL schema and implement the resolvers and finally we will start the reactor and execute a query through the GraphQL Gateway.
 
 ### 1. Generate the subgraph
 
-Let's start by generating a new subgraph. For our tutorial we will create a new subgraph within our To-do List project.   
+Let's 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.   
+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 search-todos
@@ -57,24 +57,26 @@ Loaded templates: /projects/powerhouse/powerhouse/packages/codegen/dist/src/code
 ```
 
 ### What happened?
+
 1. A new subgraph was created in `./subgraphs/search-todos/`
 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 `ph reactor` we will see the new subgraph being registered during the startup of the Reactor.
-  > Registered /graphql/search-todos subgraph.
+
+> Registered /graphql/search-todos subgraph.
 
 ```
 Initializing Subgraph Manager...
-> Registered /graphql/auth subgraph.  
+> Registered /graphql/auth subgraph.
 > Registered /graphql/system subgraph.
 > Registered /graphql/analytics subgraph.
 > Registered /d/:drive subgraph.
 > Updating router
-> Registered /graphql supergraph 
-> Registered /graphql/search-todos subgraph. 
+> Registered /graphql supergraph
+> Registered /graphql/search-todos subgraph.
 > Updating router
-> Registered /graphql supergraph 
+> Registered /graphql supergraph
   ➜  Reactor:   http://localhost:4001/d/powerhouse
 ```
 
@@ -89,16 +91,13 @@ import { gql } from "graphql-tag";
 import type { DocumentNode } from "graphql";
 
 export const schema: DocumentNode = gql`
-"""
-Subgraph definition
-"""
-
-type Query {
+  """
+  Subgraph definition
+  """
+  type Query {
     searchTodos(driveId: String!, searchTerm: String!): [String!]!
-}
-
+  }
 `;
-
 ```
 
 **Step 2: Create resolvers in `subgraphs/search-todos/resolvers.ts`:**
@@ -113,7 +112,10 @@ export const getResolvers = (subgraph: Subgraph) => {
 
   return {
     Query: {
-      searchTodos: async (parent: unknown, args: { driveId: string, searchTerm: string }) => {
+      searchTodos: async (
+        parent: unknown,
+        args: { driveId: string; searchTerm: string },
+      ) => {
         const documents = await reactor.getDocuments(args.driveId);
         const todoItems: string[] = [];
         for (const docId of documents) {
@@ -122,7 +124,9 @@ export const getResolvers = (subgraph: Subgraph) => {
             continue;
           }
 
-          const amountEntries = doc.state.global.items.filter(e => e.text.includes(args.searchTerm)).length;
+          const amountEntries = doc.state.global.items.filter((e) =>
+            e.text.includes(args.searchTerm),
+          ).length;
           if (amountEntries > 0) {
             todoItems.push(docId);
           }
@@ -132,13 +136,12 @@ export const getResolvers = (subgraph: Subgraph) => {
     },
   };
 };
-
 ```
 
-
 ## 3. Testing the to-do list subgraph
 
 ### 3.1. Start the reactor
+
 To activate the subgraph, run:
 
 ```bash
@@ -146,14 +149,17 @@ ph reactor
 ```
 
 You should see the subgraph being registered in the console output:
+
 ```
 > Registered /graphql/search-todos subgraph.
 ```
 
 ### 3.2. Create some test data
+
 Before testing queries, let's create some To-do List documents with test data:
 
-1. Start Connect 
+1. Start Connect
+
 ```bash
 ph connect
 ```
@@ -167,6 +173,7 @@ ph connect
    - "Test the subgraph" (leave unchecked)
 
 ### 3.3. Access GraphQL playground
+
 Open your browser and go to:
 
 ```bash
@@ -176,6 +183,7 @@ http://localhost:4001/graphql
 ### 3.4. Test the queries
 
 **Query 1: Search for Todos **
+
 ```graphql
 query {
   searchTodos(driveId: "powerhouse", searchTerm: "Test")
@@ -196,28 +204,26 @@ To verify that your subgraph stays synchronized with document changes:
 
 This demonstrates the real-time synchronization between the document model and the subgraph through event processing.
 
-
 ## 4. Working with the GraphQL Gateway
 
 The GraphQL Gateway 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.
+- **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.
-
+- **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 access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the 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 access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph.
 
 - Start the reactor:
 
@@ -231,18 +237,16 @@ The Powerhouse supergraph for any given remote drive or reactor can be found und
   http://localhost:4001/graphql
   ```
 
-The supergraph allows you to both query & mutate data from the same endpoint. 
+The supergraph allows you to both query & mutate data from the same endpoint.
 
 **Example: Using the supergraph with To-do List documents**
 
 1. Create a todo document in the `powerhouse` drive using the `ToDoList_createDocument` mutation:
+
    ```graphql
    mutation {
      ToDoList_createDocument(
-       input: {
-         documentId: "my-todo-list"
-         name: "My Test To-do List"
-       }
+       input: { documentId: "my-todo-list", name: "My Test To-do List" }
      ) {
        id
        name
@@ -251,19 +255,18 @@ The supergraph allows you to both query & mutate data from the same endpoint.
    ```
 
 2. Add some items to your to-do list using the `ToDoList_addTodoItem` mutation:
+
    ```graphql
    mutation {
      ToDoList_addTodoItem(
        docId: "my-todo-list"
-       input: {
-         id: "item-1"
-         text: "Learn about supergraphs"
-       }
+       input: { id: "item-1", text: "Learn about supergraphs" }
      )
    }
    ```
 
 3. Query the document state using the `GetDocument` query:
+
    ```graphql
    query {
      ToDoList {
@@ -303,13 +306,14 @@ The supergraph allows you to both query & mutate data from the same endpoint.
    }
    ```
 
-This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint. 
+This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint.
 
 ## 5. Summary
 
 Congratulations! You've successfully built a complete To-do List subgraph that demonstrates the power of extending document models with custom GraphQL functionality. Let's recap what you've accomplished:
 
 ### Key concepts learned:
+
 - **Subgraphs extend document models** with additional querying and data processing capabilities
 - **Operational data stores** provide efficient storage for subgraph data
 - **Event processing** enables real-time synchronization between document models and subgraphs
@@ -323,7 +327,7 @@ This tutorial has provided you with a solid foundation for building sophisticate
    - 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**: 
+2. **External Integrations**:
    - Sync tasks with external project management tools
    - Connect with notification systems
    - Integrate with analytics platforms
@@ -333,14 +337,6 @@ This tutorial has provided you with a solid foundation for building sophisticate
    - Add automated task assignments
    - Create custom reporting functionality
 
-
 ### 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/04-analytics-processor.md

@@ -152,9 +152,7 @@ const dimensions = {
   asset: AnalyticsPath.fromString(
     `sky/rwas/assets/t-bills/${fixedIncomeTransaction.assetId}`,
   ),
-  portfolio: AnalyticsPath.fromString(
-    `sky/rwas/portfolios/${documentId}`,
-  ),
+  portfolio: AnalyticsPath.fromString(`sky/rwas/portfolios/${documentId}`),
 };
 
 // create the series values
@@ -202,9 +200,7 @@ With variables:
     "granularity": "annual",
     "start": "2024-01-01",
     "end": "2025-01-01",
-    "metrics": [
-      "AssetBalance",
-    ],
+    "metrics": ["AssetBalance"],
     "dimensions": [
       {
         "name": "asset",
@@ -220,14 +216,17 @@ With variables:
 
 The RWA processor example pulls information from operation _inputs_ to insert analytics data. Another use case might be to capture meta-analytics from the states themselves.
 
-This processor listens to all documents of type `powerhouse/document-drive`, and since the `document-drive` is itself implemented on top of the document model core systems, this means that we can process all virtual file system operations.  This processor count basic usage metrics using document operations and states.
+This processor listens to all documents of type `powerhouse/document-drive`, and since the `document-drive` is itself implemented on top of the document model core systems, this means that we can process all virtual file system operations. This processor count basic usage metrics using document operations and states.
 
 ```typescript
 import { IAnalyticsStore } from "@powerhousedao/reactor-api";
 import { AnalyticsPath } from "@powerhousedao/reactor-api";
 import { AnalyticsSeriesInput } from "@powerhousedao/reactor-api";
 import { InternalTransmitterUpdate, IProcessor } from "document-drive";
-import { AddFileInput, DeleteNodeInput } from "document-drive/drive-document-model/gen/types";
+import {
+  AddFileInput,
+  DeleteNodeInput,
+} from "document-drive/drive-document-model/gen/types";
 import { PHDocument } from "document-model";
 import { DateTime } from "luxon";
 
@@ -247,91 +246,103 @@ export class DriveProcessorProcessor implements IProcessor {
   constructor(private readonly analyticsStore: IAnalyticsStore) {
     //
   }
-  
+
   async onStrands<TDocument extends PHDocument>(
-    strands: InternalTransmitterUpdate<TDocument>[]
+    strands: InternalTransmitterUpdate<TDocument>[],
   ): Promise<void> {
     if (strands.length === 0) {
       return;
     }
 
-    const values:AnalyticsSeriesInput[] = [];
+    const values: AnalyticsSeriesInput[] = [];
 
     for (const strand of strands) {
       const operations = strand.operations;
-      await Promise.all(operations.map((operation) => {
-        const source = AnalyticsPath.fromString(`switchboard/default/${strand.driveId}`);
-    
-        const start = DateTime.fromISO(operation.timestamp);
-        const dimensions: any = {
-          documentType: AnalyticsPath.fromString(`document/type/powerhouse/document-drive`),
-        };
-
-        if (operation.index === 0) {
-          this.analyticsStore.clearSeriesBySource(source);
-        }
-    
-        switch (operation.type) {
-          case "ADD_FILE": {
-            // count documents of each type (ADD_FILE, input.documentType)
-    
-            // lookup node in state
-            const input = operation.input as AddFileInput;
-            const node = findNode(strand.state, input.id);
-            if (!node) {
-              return Promise.resolve();
-            }
-    
-            dimensions["kind"] = AnalyticsPath.fromString(`document/kind/${node.kind}`);
-    
-            // increment by adding a 1
-            values.push({
-              source,
-              start,
-              value: 1,
-              metric: "Count",
-              dimensions,
-            });
-            
-            break;
-          }
-          case "ADD_FOLDER": {
-            dimensions["kind"] = AnalyticsPath.fromString("document/kind/folder");
-    
-            // increment by adding a 1
-            values.push({
-              source,
-              start,
-              value: 1,
-              metric: "Count",
-              dimensions,
-            });
-            
-            break;
+      await Promise.all(
+        operations.map((operation) => {
+          const source = AnalyticsPath.fromString(
+            `switchboard/default/${strand.driveId}`,
+          );
+
+          const start = DateTime.fromISO(operation.timestamp);
+          const dimensions: any = {
+            documentType: AnalyticsPath.fromString(
+              `document/type/powerhouse/document-drive`,
+            ),
+          };
+
+          if (operation.index === 0) {
+            this.analyticsStore.clearSeriesBySource(source);
           }
-          case "DELETE_NODE": {
-            // the operation only contains the id, so lookup deleted item type in previous state
-            const input = operation.input as DeleteNodeInput;
-            const node = findNode(operation.previousState, input.id);
-            if (!node) {
-              return Promise.resolve();
+
+          switch (operation.type) {
+            case "ADD_FILE": {
+              // count documents of each type (ADD_FILE, input.documentType)
+
+              // lookup node in state
+              const input = operation.input as AddFileInput;
+              const node = findNode(strand.state, input.id);
+              if (!node) {
+                return Promise.resolve();
+              }
+
+              dimensions["kind"] = AnalyticsPath.fromString(
+                `document/kind/${node.kind}`,
+              );
+
+              // increment by adding a 1
+              values.push({
+                source,
+                start,
+                value: 1,
+                metric: "Count",
+                dimensions,
+              });
+
+              break;
+            }
+            case "ADD_FOLDER": {
+              dimensions["kind"] = AnalyticsPath.fromString(
+                "document/kind/folder",
+              );
+
+              // increment by adding a 1
+              values.push({
+                source,
+                start,
+                value: 1,
+                metric: "Count",
+                dimensions,
+              });
+
+              break;
+            }
+            case "DELETE_NODE": {
+              // the operation only contains the id, so lookup deleted item type in previous state
+              const input = operation.input as DeleteNodeInput;
+              const node = findNode(operation.previousState, input.id);
+              if (!node) {
+                return Promise.resolve();
+              }
+
+              dimensions["kind"] = AnalyticsPath.fromString(
+                `document/kind/${node.kind}`,
+              );
+
+              // decrement by adding a -1
+              values.push({
+                source,
+                start,
+                value: -1,
+                metric: "Count",
+                dimensions,
+              });
+
+              break;
             }
-    
-            dimensions["kind"] = AnalyticsPath.fromString(`document/kind/${node.kind}`);
-    
-            // decrement by adding a -1
-            values.push({
-              source,
-              start,
-              value: -1,
-              metric: "Count",
-              dimensions,
-            });
-    
-            break;
           }
-        }
-      }));
+        }),
+      );
     }
 
     await this.analyticsStore.addSeriesValues(values);
@@ -462,9 +473,12 @@ Now, we can define the dimensions we want to group by. We can imagine that we wi
 
 ```ts
 const totalSpendOnHeadcount = useAnalyticsQuery({
-  start, end, granularity, metrics,
+  start,
+  end,
+  granularity,
+  metrics,
   select: {
-    contributor: "/billing-statement/contributor"
+    contributor: "/billing-statement/contributor",
   },
   lod: {
     contributor: 3,
@@ -483,7 +497,7 @@ const totalSpend = useAnalyticsQuery({
   granularity: "total", // <--- this means we'll get results for the entire time period
   metrics: ["Cash", "Powt"],
   select: {
-    budget: "/billing-statement"
+    budget: "/billing-statement",
   },
   lod: {
     budget: 0, // <--- this means we'll get all results lumped together
@@ -496,7 +510,7 @@ const monthlySpendByBudget = useAnalyticsQuery({
   granularity: "monthly", // <--- this means we'll get results grouped by month
   metrics: ["Cash", "Powt"],
   select: {
-    budget: "/billing-statement/budget"
+    budget: "/billing-statement/budget",
   },
   lod: {
     budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
@@ -509,7 +523,7 @@ const monthlySpendByCategory = useAnalyticsQuery({
   granularity: "monthly", // <--- this means we'll get results grouped by month
   metrics: ["Cash", "Powt"],
   select: {
-    category: "/billing-statement/category"
+    category: "/billing-statement/category",
   },
   lod: {
     category: 3, // <--- this means we'll get results grouped by "/billing-statement/category/category1", "/billing-statement/category/category2", etc.
@@ -522,7 +536,7 @@ const yearlySpendByBudget = useAnalyticsQuery({
   granularity: "yearly", // <--- this means we'll get results grouped by year
   metrics: ["Cash", "Powt"],
   select: {
-    budget: "/billing-statement/budget"
+    budget: "/billing-statement/budget",
   },
   lod: {
     budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
@@ -535,7 +549,7 @@ const monthlySpendByBudget = useAnalyticsQuery({
   granularity: "monthly", // <--- this means we'll get results grouped by month
   metrics: ["Cash", "Powt"],
   select: {
-    budget: "/billing-statement/budget"
+    budget: "/billing-statement/budget",
   },
   lod: {
     budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
@@ -548,7 +562,7 @@ const last30DaysSpendByBudget = useAnalyticsQuery({
   granularity: "day", // <--- this means we'll get results grouped by day
   metrics: ["Cash", "Powt"],
   select: {
-    budget: "/billing-statement/budget"
+    budget: "/billing-statement/budget",
   },
   lod: {
     budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
@@ -568,10 +582,10 @@ For instance, say we take our monthly spend by category query:
 const monthlySpendByCategory = useAnalyticsQuery({
   start,
   end,
-  granularity: "monthly", 
+  granularity: "monthly",
   metrics: ["Cash", "Powt"],
   select: {
-    category: "/billing-statement/category"
+    category: "/billing-statement/category",
   },
   lod: {
     category: 3,
@@ -583,31 +597,36 @@ This gives us the results we're looking for but, by design, there may be many di
 
 ```ts
 // this source will match all analytics updates from any document in the drive
-const driveSource = AnalyticsPath.fromString(`billing-statement/${drive.header.id}`);
+const driveSource = AnalyticsPath.fromString(
+  `billing-statement/${drive.header.id}`,
+);
 
 // this source will match all analytics updates from a specific document in a drive
-const documentSource = AnalyticsPath.fromString(`billing-statement/${drive.header.id}/${document.header.id}`);
+const documentSource = AnalyticsPath.fromString(
+  `billing-statement/${drive.header.id}/${document.header.id}`,
+);
 ```
 
 ```ts
 const { state, data: drive } = useSelectedDrive();
 
-const results = useAnalyticsQuery({
-  start, end,
-  granularity: "monthly", 
-  metrics: ["Cash", "Powt"],
-  select: {
-    category: "/billing-statement/category"
+const results = useAnalyticsQuery(
+  {
+    start,
+    end,
+    granularity: "monthly",
+    metrics: ["Cash", "Powt"],
+    select: {
+      category: "/billing-statement/category",
+    },
+    lod: {
+      category: 3,
+    },
   },
-  lod: {
-    category: 3,
+  {
+    sources: [`/billing-statement/${drive.header.id}/`],
   },
-},
-{
-  sources: [
-   `/billing-statement/${drive.header.id}/` 
-  ],
-});
+);
 ```
 
 ### `IProcessor`
@@ -617,6 +636,3 @@ Now that we have designed out our data, we can open up `line-item-processor/inde
 ```ts
 
 ```
-
-
-