@powerhousedao/academy 3.3.0-dev.14 → 3.3.0-dev.16

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.3.0-dev.16 (2025-07-22)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 3.3.0-dev.15 (2025-07-17)
+
+### 🩹 Fixes
+
+- **codegen:** updated subgraph template to deal with undefined return on getDocument ([7b2862a91](https://github.com/powerhouse-inc/powerhouse/commit/7b2862a91))
+- **academy:** update broken links ([cbbfe9b30](https://github.com/powerhouse-inc/powerhouse/commit/cbbfe9b30))
+
+### ❤️ Thank You
+
+- acaldas
+- Callme-T
+
 ## 3.3.0-dev.14 (2025-07-17)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

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

@@ -19,9 +19,9 @@ A subgraph in Powerhouse is a **GraphQL-based modular data component** that exte
 
 ### 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.
+- **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).
@@ -40,30 +40,30 @@ context: {
 
 ## 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.   
+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.   
 
 ```bash title="Run the following command to generate a new subgraph"
-ph generate --subgraph <to-do-list-subgraph>
+ph generate --subgraph to-do-list
 ```
 
 ```bash title="Expected Output"
 Loaded templates: node_modules/@powerhousedao/codegen/dist/codegen/.hygen/templates
-       FORCED: ./subgraphs/to-do-list-subgraph/index.ts
+       FORCED: ./subgraphs/to-do-list/index.ts
      skipped: ./subgraphs/index.ts
       inject: ./subgraphs/index.ts
 ```
 
 ### What happened?
-1. A new subgraph was created in `./subgraphs/to-do-list-subgraph/`
+1. A new subgraph was created in `./subgraphs/to-do-list/`
 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 /todolist subgraph.
 
-Alternatively, when you are running a local reactor with `ph reactor` a series of subgraphs will automatically get registered, amongst those one for the available document models in your Powerhouse project. 
+Alternatively, when you are running a local reactor with `ph reactor`, a series of subgraphs will automatically get registered, among those, one for the available document models in your Powerhouse project. 
 
 ```
 Initializing Subgraph Manager...
@@ -120,30 +120,77 @@ Now let's create a subgraph that provides enhanced querying capabilities for our
 ```typescript
 export const typeDefs = `
   type Query {
+    # Dashboard-style summary query - returns high-level metrics
+    # Similar to ToDoListStats from document model but optimized for quick queries
     todoList: TodoListSummary
+    
+    # Filtered list query - lets you get items by completion status
+    # More flexible than the basic document model - can filter checked/unchecked
     todoItems(checked: Boolean): [TodoItem!]!
+    
+    # Count-only query - when you just need numbers, not full data
+    # Faster than getting full list when you only need totals for dashboards
     todoItemsCount(checked: Boolean): Int!
   }
 
+  # This mirrors ToDoListStats from the document model
+  # But it's a "view" optimized for summary reports and dashboards
   type TodoListSummary {
-    total: Int!
-    checked: Int!
-    unchecked: Int!
+    total: Int!     # Total number of items
+    checked: Int!   # Number of completed items  
+    unchecked: Int! # Number of pending items
   }
 
+  # This matches the ToDoItem from the document model
+  # Same data structure, but accessed through subgraph queries for filtering
   type TodoItem {
-    id: ID!
-    text: String!
-    checked: Boolean!
+    id: ID!          # Unique identifier
+    text: String!    # The task description
+    checked: Boolean! # Completion status
   }
 `;
 ```
 
+
+
+#### Understanding Resolvers
+
+Before diving into the technical implementation, let's understand why these three different query types matter for your product.
+Think of resolvers as custom API endpoints that are automatically created based on what your users actually need to know about your data.
+
+ When someone asks your system a question through GraphQL, the resolver:
+
+1. **Understands the request** - "The customer wants unchecked items"
+2. **Knows where to get the data** - "I need to check the todo_items database table"  
+3. **Applies the right filters** - "Only get items where checked = false"
+4. **Returns the answer** - "Here are the 5 unchecked items"
+
+**The three resolvers serve different business needs:**
+
+- **`todoList` Resolver - The Dashboard**
+  - **Business value**: Perfect for executive dashboards or KPI displays
+  - **Use case**: "We have 150 total tasks, 89 completed, 61 pending"
+  - **Users**: Executives, managers, anyone needing high-level metrics
+
+- **`todoItems` Resolver - The Detailed List**  
+  - **Business value**: Great for operational views where people need to see actual tasks
+  - **Use case**: "Show me all pending tasks" or "Show me everything"
+  - **Users**: Workers, operators, anyone who needs to act on specific items
+
+- **`todoItemsCount` Resolver - The Counter**
+  - **Business value**: Super fast for analytics or when you only need numbers
+  - **Use case**: "How many completed tasks do we have?" → "47"
+  - **Users**: Analysts, automated systems, performance dashboards
+
+**Why this architecture matters:**
+- **Performance**: Count queries are much faster than getting full lists when you only need numbers
+- **User Experience**: Different resolvers serve different user needs efficiently
+- **Flexibility**: Users can ask for exactly what they need, nothing more, nothing less
+
 **Step 2: Create resolvers in `subgraphs/to-do-list/resolvers.ts`:**
 
 ```typescript
 // subgraphs/to-do-list/resolvers.ts
-// subgraphs/to-do-list/resolvers.ts
 interface SubgraphInstance {
   operationalStore: any;
 }
@@ -196,35 +243,48 @@ import { typeDefs } from './schema.js';
 import { createResolvers } from './resolvers.js';
 
 export default class ToDoListSubgraph {
+  // Define the API endpoint where this subgraph will be accessible
+  // Users can query this at: http://localhost:4001/graphql/to-do-list
   path = '/to-do-list';
   
+  // GraphQL schema definition (what queries are available)
   typeDefs = typeDefs;
+  
+  // Query handlers (how to fetch the data)
   resolvers: any;
+  
+  // Database interface (injected by Powerhouse framework)
   operationalStore: any;
   
   constructor() {
+    // Connect the resolvers to this subgraph instance
+    // This gives resolvers access to the database through this.operationalStore
     this.resolvers = createResolvers(this);
   }
 
+  // Called once when the subgraph starts up
   async onSetup() {
     await this.createOperationalTables();
   }
 
+  // Create the database tables we need for storing todo items
   async createOperationalTables() {
     await this.operationalStore.schema.createTableIfNotExists(
-      "todo_items",
+      "todo_items", // Table name
       (table: any) => {
-        table.string("id").primary();
-        table.string("text").notNullable();
-        table.boolean("checked").defaultTo(false);
-        table.timestamp("created_at").defaultTo(this.operationalStore.fn.now());
-        table.timestamp("updated_at").defaultTo(this.operationalStore.fn.now());
+        table.string("id").primary();           // Unique identifier for each todo item
+        table.string("text").notNullable();     // The actual todo task text
+        table.boolean("checked").defaultTo(false); // Completion status (unchecked by default)
+        table.timestamp("created_at").defaultTo(this.operationalStore.fn.now()); // When item was created
+        table.timestamp("updated_at").defaultTo(this.operationalStore.fn.now()); // When item was last modified
       }
     );
   }
 
+  // Event processor: Keeps subgraph data synchronized with document model changes
+  // When users add/update/delete todos in Connect, this method handles the updates
   async process(event: any) {
-    // Handle To-do List document operations
+    // Handle new todo item creation
     if (event.type === "ADD_TODO_ITEM") {
       await this.operationalStore.insert("todo_items", {
         id: event.input.id,
@@ -237,12 +297,13 @@ export default class ToDoListSubgraph {
       console.log(`Added todo item: ${event.input.text}`);
     }
     
+    // Handle todo item updates (text changes, checking/unchecking)
     if (event.type === "UPDATE_TODO_ITEM") {
       const updateData: any = {
-        updated_at: new Date()
+        updated_at: new Date() // Always update the timestamp
       };
       
-      // Only update fields that were provided
+      // Only update fields that were actually changed
       if (event.input.text !== undefined) {
         updateData.text = event.input.text;
       }
@@ -257,6 +318,7 @@ export default class ToDoListSubgraph {
       console.log(`Updated todo item: ${event.input.id}`);
     }
     
+    // Handle todo item deletion
     if (event.type === "DELETE_TODO_ITEM") {
       await this.operationalStore.delete("todo_items")
         .where("id", event.input.id);
@@ -267,11 +329,6 @@ export default class ToDoListSubgraph {
 }
 ```
 
-**What this schema provides:**
-- `todoList`: Returns statistics about all to-do items (total, checked, unchecked counts)
-- `todoItems`: Returns a list of to-do items, optionally filtered by checked status
-- `todoItemsCount`: Returns just the count of items, optionally filtered by checked status
-
 ### 2.3 Understanding the Implementation
 
 **What this multi-file approach provides:**
@@ -287,70 +344,72 @@ export default class ToDoListSubgraph {
 - Resolvers that fetch and filter todo items from the operational store
 - Event processing to keep the subgraph data synchronized with document model changes
 
-### 2.4 Connect to Document Model Events (Processor Integration)
+### 2.4 Understanding the Document Model Event Integration
 
-To make our subgraph truly useful, we need to connect it to the actual To-do List document model events. This ensures that when users interact with To-do List documents through Connect, the subgraph data stays synchronized.
+Notice that our `index.ts` file already includes a `process` method - this is the **processor integration** that keeps our subgraph synchronized with To-do List document model events. When users interact with To-do List documents through Connect, this method automatically handles the updates.
 
-Add this processor integration to your subgraph:
+**How the existing processor integration works:**
 
+The `process` method in our `index.ts` file handles three types of document model events:
+
+**1. Adding new todo items:**
 ```typescript
-async process(event) {
-  // Handle To-do List document operations
-  if (event.type === "ADD_TODO_ITEM") {
-    await this.operationalStore.insert("todo_items", {
-      id: event.input.id,
-      text: event.input.text,
-      checked: false,
-      created_at: new Date(),
-      updated_at: new Date()
-    });
-    
-    console.log(`Added todo item: ${event.input.text}`);
-  }
-  
-  if (event.type === "UPDATE_TODO_ITEM") {
-    const updateData = {
-      updated_at: new Date()
-    };
-    
-    // Only update fields that were provided
-    if (event.input.text !== undefined) {
-      updateData.text = event.input.text;
-    }
-    if (event.input.checked !== undefined) {
-      updateData.checked = event.input.checked;
-    }
-    
-    await this.operationalStore.update("todo_items")
-      .where("id", event.input.id)
-      .update(updateData);
-    
-    console.log(`Updated todo item: ${event.input.id}`);
-  }
+if (event.type === "ADD_TODO_ITEM") {
+  await this.operationalStore.insert("todo_items", {
+    id: event.input.id,
+    text: event.input.text,
+    checked: false,
+    created_at: new Date(),
+    updated_at: new Date()
+  });
+}
+```
+
+**2. Updating existing items:**
+```typescript
+if (event.type === "UPDATE_TODO_ITEM") {
+  // Only update fields that were actually changed
+  const updateData = { updated_at: new Date() };
+  if (event.input.text !== undefined) updateData.text = event.input.text;
+  if (event.input.checked !== undefined) updateData.checked = event.input.checked;
   
-  if (event.type === "DELETE_TODO_ITEM") {
-    await this.operationalStore.delete("todo_items")
-      .where("id", event.input.id);
-    
-    console.log(`Deleted todo item: ${event.input.id}`);
-  }
+  await this.operationalStore.update("todo_items")
+    .where("id", event.input.id)
+    .update(updateData);
+}
+```
+
+**3. Deleting items:**
+```typescript
+if (event.type === "DELETE_TODO_ITEM") {
+  await this.operationalStore.delete("todo_items")
+    .where("id", event.input.id);
 }
 ```
 
-**What this processor does:**
-- Listens for document model operations (`ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`)
-- Updates the operational store in real-time when these operations occur
-- Provides console logging for debugging
-- Maintains data consistency between the document model and the subgraph
+**The integration happens automatically:**
+1. **User action**: Someone adds a todo item in Connect
+2. **Document model**: Processes the `ADD_TODO_ITEM` operation  
+3. **Framework routing**: Powerhouse automatically calls your subgraph's `process` method
+4. **Subgraph response**: Your `process` method updates the operational store
+5. **Query availability**: Users can now query the updated data via GraphQL
 
 ### 2.5 Summary of What We've Built
 
-- **Added two main queries**: `todoList` for statistics and `todoItems` for item lists
-- **Created an operational table** `todo_items` to store the todo items with proper schema
-- **Added resolvers** to fetch and filter todo items from the operational store
-- **Implemented event processing** to keep the subgraph data synchronized with document model changes
-- **The todoItems query accepts an optional checked parameter** to filter items by their completion status
-- **The todoList query returns the full statistics** including total, checked, and unchecked counts
+Our complete To-do List subgraph includes:
+
+- **GraphQL schema** (`schema.ts`): Defines `todoList`, `todoItems`, and `todoItemsCount` queries
+- **Resolvers** (`resolvers.ts`): Handle data fetching and filtering from the operational store
+- **Main subgraph class** (`index.ts`): Coordinates everything and includes:
+  - **Operational table creation**: Sets up the `todo_items` table with proper schema
+  - **Event processing**: The `process` method keeps subgraph data synchronized with document model changes
+  - **Real-time updates**: Automatically handles `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` events
+
+**Key features:**
+- **Filtering capability**: The `todoItems` query accepts an optional `checked` parameter
+- **Performance optimization**: The `todoItemsCount` query returns just numbers when you don't need full data
+- **Real-time synchronization**: Changes in Connect immediately appear in subgraph queries
+- **Complete statistics**: The `todoList` query returns total, checked, and unchecked counts
 
 ## 3. Testing the To-do List Subgraph
 
@@ -485,7 +544,7 @@ This demonstrates the real-time synchronization between the document model and t
 
 ## 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
+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
 
@@ -503,7 +562,7 @@ A supergraph is a GraphQL schema that combines multiple underlying GraphQL APIs,
 
 ### 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. 
+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:
 
@@ -517,7 +576,7 @@ The Powerhouse supergraph for any given remote drive or reactor can be found und
   http://localhost:4001/graphql
   ```
 
-The supergraph allows 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**
 
@@ -639,7 +698,7 @@ 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.
+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/07-OperationalDbProcessorTutorial/01-TodoList-example.md

@@ -1,28 +1,62 @@
-# Build a Todo-List processor
+# Build a Todo-List Processor
 
-1. Generate the processor
-2. Define your database schema
-3. Customize the processor to your needs
-4. Test your processor
-5. Use the relational database in Frontend and Subgraph
+## What You'll Learn
 
+In this tutorial, you'll learn how to build a **relational database processor** that listens to changes in Powerhouse TodoList documents and automatically maintains a synchronized relational database. This is useful for creating queryable data stores, generating reports, or integrating with existing database-driven applications.
 
-## Generate the Processor
+## What is a Processor?
+
+A **processor** in Powerhouse is a background service that automatically responds to document changes. Think of it as a "listener" that watches for specific document operations (like creating, updating, or deleting todos) and then performs custom logic - in this case, updating a relational database.
+
+**Key Benefits:**
+- **Real-time synchronization**: Your database stays automatically up-to-date with document changes
+- **Query performance**: Relational databases excel at complex queries and joins
+
+## Tutorial Steps
+
+1. **Generate the processor** - Create the basic processor structure
+2. **Define your database schema** - Design the tables to store your data
+3. **Generate TypeScript types** - Get type safety for database operations
+4. **Configure the filter** - Specify which documents to listen to
+5. **Customize the processor logic** - Implement how document changes update the database
+6. **Use the data via Subgraph** - Query your processed data through GraphQL
+
+---
+
+## Step 1: Generate the Processor
+
+First, we'll create the processor using the Powerhouse CLI. This command scaffolds all the necessary files and configuration.
 
-In order to generate the processor you need to run the following command:
 ```bash
 ph generate --processor todo-processor --processor-type relational-db --document-types powerhouse/todolist
 ```
 
-With that command you create a processor named todo-processor which is of type relational db and listens on changes from documents of type powerhouse/todolist.
+**Breaking down this command:**
+- `--processor todo-processor`: Names your processor "todo-processor"
+- `--processor-type relational-db`: Creates a processor that works with SQL databases
+- `--document-types powerhouse/todolist`: Tells the processor to listen for changes in TodoList documents
+
+**What gets created:**
+- `processors/todo-processor/` directory with all necessary files
+- Migration files for database schema management
+- Factory function for processor instantiation
+- Base processor class ready for customization
+
+---
 
-## Define your database schema
+## Step 2: Define Your Database Schema
 
-As next step we need to define the db schema in the `processors/todo-processor/migration.ts` file.
+Next, we need to define what our database tables will look like. This happens in the **migration file**, which contains instructions for creating (and optionally destroying) database tables.
 
-The migration file has a up and a down function which gets called when either the processor was added or when the processor was removed.
+**File location:** `processors/todo-processor/migration.ts`
 
-Below you can find the example of a todo table.
+### Understanding Migrations
+
+Migrations are scripts that modify your database structure. They have two functions:
+- **`up()`**: Runs when the processor is added - creates tables and indexes
+- **`down()`**: Runs when the processor is removed - cleans up by dropping tables
+
+Here's our TodoList migration:
 
 ```ts
 import { type IBaseRelationalDb } from "document-drive/processors/types"
@@ -30,41 +64,61 @@ import { type IBaseRelationalDb } from "document-drive/processors/types"
 export async function up(db: IBaseRelationalDb): Promise<void> {
   // Create table
   await db.schema
-    .createTable("todo")
-    .addColumn("name", "varchar(255)")
-    .addColumn("completed", "boolean")
-    .addPrimaryKeyConstraint("todo_pkey", ["name"])
-    .ifNotExists()
-    .execute();
-
+    .createTable("todo")                          // Table name: "todo"
+    .addColumn("name", "varchar(255)")            // Todo item text (up to 255 characters)
+    .addColumn("completed", "boolean")            // Completion status (true/false)
+    .addPrimaryKeyConstraint("todo_pkey", ["name"]) // Primary key on 'name' column
+    .ifNotExists()                               // Only create if table doesn't exist
+    .execute();                                  // Execute the SQL command
+
+  // Optional: Log all tables for debugging
   const tables = await db.introspection.getTables();
   console.log(tables);
 }
 
 export async function down(db: IBaseRelationalDb): Promise<void> {
-  // drop table
+  // Clean up: drop the table when processor is removed
   await db.schema.dropTable("todo").execute();
 }
 ```
 
-## Generate Types
+**Design decisions explained:**
+- **`name` as primary key**: Assumes todo names are unique (you might want to use an auto-incrementing ID instead)
+- **Simple boolean for completion**: Easy to query for completed vs. incomplete todos
+- **`ifNotExists()`**: Prevents errors if the processor restarts
+
+---
 
-After defining your db schema its important to generate the types for typescript. This allows to create type safety queries and make use of code completion in your IDE when writing database queries.
+## Step 3: Generate TypeScript Types
 
-Simply execute the following command. 
+After defining your database schema, generate TypeScript types for type-safe database operations. This provides IDE autocomplete and catches errors at compile time.
 
 ```bash
 ph generate --migration-file processors/todo-indexer/migrations.js --schema-file processors/todo-indexer/schema.ts
 ```
 
-Afterwards check your `processors/todo-processor/schema.ts` file.
-It will contain the types of your database.
+**What this does:**
+- Analyzes your migration file
+- Generates TypeScript interfaces matching your database tables
+- Creates a `schema.ts` file with type definitions
+
+**Result:** You'll get types like:
+```ts
+interface Todo {
+  name: string;
+  completed: boolean;
+}
+```
 
-## Define the Filter
+These types will be available in `processors/todo-processor/schema.ts` and ensure your database queries are type-safe.
 
-Checkout the `processors/todo-processor/factory.ts`.
+---
 
-Here you can define how the processor is being instantiated. In thise case it listens on powerhouse/todo-list document changes in the main branch and the global scope.
+## Step 4: Configure the Filter
+
+The **filter** determines which document changes your processor should respond to. This is configured in the factory function.
+
+**File location:** `processors/todo-processor/factory.ts`
 
 ```ts
 export const todoProcessorProcessorFactory =
@@ -75,10 +129,10 @@ export const todoProcessorProcessorFactory =
 
     // Create a filter for the processor
     const filter: RelationalDbProcessorFilter = {
-      branch: ["main"],
-      documentId: ["*"],
-      documentType: ["powerhouse/todo-list"],
-      scope: ["global"],
+      branch: ["main"],                           // Only listen to main branch changes
+      documentId: ["*"],                          // Listen to ALL documents (wildcard)
+      documentType: ["powerhouse/todo-list"],     // Only TodoList document types
+      scope: ["global"],                          // Global scope (vs. user-specific)
     };
 
     // Create a namespaced store for the processor
@@ -96,14 +150,23 @@ export const todoProcessorProcessorFactory =
       },
     ];
   };
-
 ```
 
-## Customize the logic of the processor
+**Filter options explained:**
+- **`branch`**: Which document branches to monitor (usually "main" for production data)
+- **`documentId`**: Specific document IDs or "*" for all documents
+- **`documentType`**: The document model type - must match exactly
+- **`scope`**: "global" for shared data, or specific scopes for user/organization data
+
+**Namespace concept**: Each processor gets its own database namespace to avoid conflicts when multiple processors or drives exist.
 
-When you defined your db schema and the filter when your processor should receive processed operations its time to implement the actual logic.
+---
 
-In the following you'll find an example where we store all the created and udpated todos in a table.
+## Step 5: Implement the Processor Logic
+
+Now for the core functionality - how your processor responds to document changes. This is where you define what happens when TodoList documents are created, updated, or deleted.
+
+**File location:** `processors/todo-processor/index.ts`
 
 ```ts
 type DocumentType = ToDoListDocument;
@@ -112,88 +175,209 @@ export class TodoIndexerProcessor extends RelationalDbProcessor<DB> {
 
   static override getNamespace(driveId: string): string {
     // Default namespace: `${this.name}_${driveId.replaceAll("-", "_")}`
+    // Each drive gets its own database tables to prevent data mixing
     return super.getNamespace(driveId);
   }
 
   override async initAndUpgrade(): Promise<void> {
+    // Run database migrations when processor starts
+    // This creates your tables if they don't exist
     await up(this.relationalDb as IBaseRelationalDb);
   }
 
   override async onStrands(
     strands: InternalTransmitterUpdate<DocumentType>[],
   ): Promise<void> {
+    // Early exit if no data to process
     if (strands.length === 0) {
       return;
     }
 
+    // Process each strand (a strand represents changes to one document)
     for (const strand of strands) {
       if (strand.operations.length === 0) {
         continue;
       }
 
+      // Process each operation in the strand
       for (const operation of strand.operations) {
+        // Simple example: Insert a new todo for every operation
+        // In a real implementation, you'd check the operation type and data
         await this.relationalDb
           .insertInto("todo")
           .values({
-            task: strand.documentId,
-            status: true,
+            task: strand.documentId,              // Use document ID as task name
+            status: true,                         // Default to completed
           })
           .execute();
       }
     }
   }
 
-  async onDisconnect() {}
+  async onDisconnect() {
+    // Cleanup logic when processor shuts down
+    // Could include closing connections, saving state, etc.
+  }
 }
-
 ```
 
-## Fetch Data through a Subgraph
+### Understanding Strands and Operations
 
-### Generate Subgraph
+**Strands** represent a sequence of changes to a single document. Each strand contains:
+- `documentId`: Which document changed
+- `operations`: Array of operations (add todo, complete todo, etc.)
+- `state`: The current document state
 
-Simply generate a new subgraph with:
-```bash
-ph generate --subgraph <subgraph-name>
+**Operations** are the actual changes made to the document:
+- `ADD_TODO`: New todo item created
+- `TOGGLE_TODO`: Todo completion status changed
+- `DELETE_TODO`: Todo item removed
+
+### Improving the Example
+
+The provided example is simplified. In production, you'd want to:
+
+1. **Parse operation types:**
+```ts
+switch (operation.type) {
+  case 'ADD_TODO':
+    // Insert new todo
+    break;
+  case 'CHECK_TODO': 
+    // Update completion status
+    break;
+  case 'DELETE_TODO':
+    // Remove todo from database
+    break;
+}
+```
+
+2. **Handle errors gracefully:**
+```ts
+try {
+  await this.relationalDb.insertInto("todo").values(values).execute();
+} catch (error) {
+  console.error('Failed to insert todo:', error);
+  // Could implement retry logic, dead letter queue, etc.
+}
 ```
 
-### Fetch Data from Processor
+3. **Use transactions for consistency:**
+```ts
+await this.relationalDb.transaction().execute(async (trx) => {
+  // Multiple operations that should all succeed or all fail
+});
+```
 
-open ```./subgraphs/<subgraph-name>/index.ts```
+---
 
+## Step 6: Query Data Through a Subgraph
 
+Once your processor is storing data in the database, you can expose it via GraphQL using a **subgraph**. This creates a clean API for frontend applications to query the processed data.
 
-define the following:
+### Generate a Subgraph
 
+Create a new GraphQL subgraph that can query your processor's database:
+
+```bash
+ph generate --subgraph <subgraph-name>
+```
+
+**What this creates:**
+- GraphQL schema definitions
+- Resolver functions that fetch data
+- Integration with your processor's database
+
+### Configure the Subgraph
+
+**File location:** `./subgraphs/<subgraph-name>/index.ts`
 
 ```ts
 resolvers = {
     Query: {
       todoList: {
         resolve: async (parent, args, context, info) => {
+          // Query the processor's database using the generated types
           const todoList = await TodoProcessor.query(
-              args.driveId ?? "powerhouse", 
-              this.relationalDb
+              args.driveId ?? "powerhouse",        // Default drive if none specified
+              this.relationalDb                    // Database connection from processor
           )
-            .selectFrom("todo")
-            .selectAll()
-            .execute();
+            .selectFrom("todo")                    // FROM todo table
+            .selectAll()                           // SELECT * (all columns)
+            .execute();                            // Execute and return results
           return todoList
         },
       },
     },
   };
 
+  // GraphQL schema definition
   typeDefs = gql`
     type Query {
       type Todo {
-        name: String!
-        completed: Boolean!
+        name: String!                              # Todo text (required)
+        completed: Boolean!                        # Completion status (required)
       }
 
-      todoList(driveId: String): [Todo!]!
+      todoList(driveId: String): [Todo!]!         # Query to get all todos for a drive
     }
   `;
-  ``` 
+```
+
+### Understanding the GraphQL Integration
+
+**Resolvers** are functions that fetch data for each GraphQL field:
+- `parent`: Data from parent resolver (unused here)
+- `args`: Arguments passed to the query (like `driveId`)
+- `context`: Shared context (database connections, user info, etc.)
+- `info`: Metadata about the GraphQL query
+
+**Type Definitions** describe your GraphQL schema:
+- `type Todo`: Defines the structure of a todo item
+- `todoList(driveId: String): [Todo!]!`: A query that returns an array of todos
+- `!` means the field is required/non-null
+
+### Querying Your Data
+
+Once deployed, frontend applications can query your data like this:
+
+```graphql
+query GetTodos($driveId: String) {
+  todoList(driveId: $driveId) {
+    name
+    completed
+  }
+}
+```
+
+This would return:
+```json
+{
+  "data": {
+    "todoList": [
+      {"name": "Buy groceries", "completed": false},
+      {"name": "Write tutorial", "completed": true}
+    ]
+  }
+}
+```
+
+---
+
+## Next Steps and Best Practices
+
+### Testing Your Processor
+
+1. **Unit tests**: Test individual functions with mock data
+2. **Integration tests**: Test the full processor with real document operations
+
+### Production Considerations
+
+1. **Error handling**: Implement robust error handling and logging
+2. **Monitoring**: Add metrics to track processor performance
+3. **Scaling**: Consider database indexing and query optimization
+4. **Security**: Validate input data and implement proper access controls
+
+This processor tutorial demonstrates the power of Powerhouse's event-driven architecture, where document changes automatically flow through to specialized data stores optimized for different use cases.
 
 

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-OperationalDbProcessorTutorial/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "RelationalDb Processor",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how to make use of a RelationalDb Processor in this tutorial!"
+  }
+}

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -50,6 +50,42 @@ const updateInvoiceName = useUpdateDocumentField('docId', 'name')
 // Combined read + write (like useState)
 const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
 ```
+Initial documentation about the hooks can be found [here](https://github.com/powerhouse-inc/powerhouse/blob/main/packages/common/state/README.md)
+
+### Temporary use of new hooks on custom drive editors. 
+
+
+To use the new hooks in custom components or editors today, devs must:
+
+1. Pass in the existing Reactor instance as a prop (createReactor).
+2. Call useInitializeReactor(props.createReactor, false) in the custom component.
+3. Optionally wrap dispatch() to trigger a refresh manually, using:
+
+const refresh = useSyncDrivesAndDocumentsWithReactor();
+
+For maximum compatibility, consider passing data and set functions (drives, documents, etc.) directly as props instead of using the hooks inside the custom editor..
+
+Example: 
+
+```
++import { AtomStoreProvider } from "@powerhousedao/common";
+
+export default function Editor(props: IProps) {
+  return (
++    <AtomStoreProvider reactor={props.context.reactor}> 
+      <DriveContextProvider value={props.context}>
+        <WagmiContext>
+          <BaseEditor {...props} />
+        </WagmiContext>
+      </DriveContextProvider>
++    </AtomStoreProvider>
+  );
+}
+```
+
+Until the hooks are fully integrated and event handling is granular, the team will need to handle some of this manually or limit their use to experimental side projects and internal demos.
+
+
 
 
 ## An overview of currently available hooks

package/docs/academy/04-APIReferences/04-RelationalDatabase.md

@@ -7,11 +7,11 @@ This page covers the relational database tools available in Powerhouse applicati
 The relational database layer gives you powerful tools to work with data in your Powerhouse applications. You get type-safe queries, real-time updates, and a simple API that feels familiar to React developers.
 
 **Key Benefits:**
-- 🔒 **Type-safe queries** with full TypeScript support
-- 🔄 **Live query capabilities** with real-time updates  
-- ⚡ **Automatic optimization** to prevent infinite re-renders
-- 🎯 **Simple API** that abstracts away complexity
-- 🧠 **Smart memoization** for parameters and queries
+- **Type-safe queries** with full TypeScript support
+- **Live query capabilities** with real-time updates  
+- **Automatic optimization** to prevent infinite re-renders
+- **Simple API** that abstracts away complexity
+- **Smart memorization** for parameters and queries
 
 ## Quick Start
 
@@ -40,23 +40,26 @@ type MyDatabase = {
 
 ```typescript
 import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
+import { MyProcessor } from './processors/my-processor';
 
-const useTypedQuery = createProcessorQuery<MyDatabase>();
+// Create a typed query hook for your processor
+const useTypedQuery = createProcessorQuery(MyProcessor);
 ```
 
 ### Step 3: Use it in your component
 
 ```typescript
 // Simple query - no parameters needed
-export function useUserList() {
-  return useTypedQuery(db => {
+export function useUserList(driveId: string) {
+  return useTypedQuery(driveId, db => {
     return db.selectFrom('users').selectAll().compile();
   });
 }
 
 // Query with parameters
-export function useUserById(userId: number) {
+export function useUserById(driveId: string, userId: number) {
   return useTypedQuery(
+    driveId,
     (db, params) => {
       return db
         .selectFrom('users')
@@ -72,8 +75,8 @@ export function useUserById(userId: number) {
 ### Step 4: Use in your React component
 
 ```typescript
-function UserList() {
-  const { isLoading, error, result } = useUserList();
+function UserList({ driveId }: { driveId: string }) {
+  const { isLoading, error, result } = useUserList(driveId);
 
   if (isLoading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
@@ -98,40 +101,40 @@ function UserList() {
 ### 1. createProcessorQuery()
 
 <details>
-<summary>`createProcessorQuery<Schema>()`: Creates a typed query hook for your database schema</summary>
+<summary>`createProcessorQuery(ProcessorClass)`: Creates a typed query hook factory for your processor</summary>
 
-### Hook Name and Signature
+### Function Name and Signature
 
 ```typescript
-function createProcessorQuery<Schema>(): TypedQueryHook<Schema>
+function createProcessorQuery<Schema>(
+  ProcessorClass: RelationalDbProcessorClass<Schema>
+): TypedQueryHook<Schema>
 ```
 
 ### Description
 
-Creates a typed query hook that provides type-safe database operations with live query capabilities. This is the main hook you'll use for most relational database operations in your components.
+Creates a typed query hook factory for a specific processor class. This is the main function you'll use to create hooks for querying your relational database.
 
 ### Usage Example
 
 ```typescript
 import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
+import { MyProcessor } from './processors/my-processor';
 
-type AppDatabase = {
-  users: { id: number; name: string; email: string };
-  posts: { id: number; title: string; author_id: number };
-};
-
-const useTypedQuery = createProcessorQuery<AppDatabase>();
+// Create a typed query hook for your processor
+const useTypedQuery = createProcessorQuery(MyProcessor);
 
-// Static query (no parameters)
-function useAllUsers() {
-  return useTypedQuery(db => {
+// Use it to create specific query hooks
+export const useUsers = (driveId: string) => {
+  return useTypedQuery(driveId, (db) => {
     return db.selectFrom('users').selectAll().compile();
   });
-}
+};
 
-// Dynamic query with parameters
-function useUsersByStatus(status: string) {
+// With parameters
+export const useUsersByStatus = (driveId: string, status: string) => {
   return useTypedQuery(
+    driveId,
     (db, params) => {
       return db
         .selectFrom('users')
@@ -141,41 +144,32 @@ function useUsersByStatus(status: string) {
     },
     { status }
   );
-}
+};
 ```
 
 ### Parameters
 
-The returned hook has two overloads:
-
-**Static queries (no parameters):**
-- `queryCallback: (db: EnhancedKysely<Schema>) => QueryCallbackReturnType` - Function that receives the database instance and returns a query
-
-**Parameterized queries:**
-- `queryCallback: (db: EnhancedKysely<Schema>, parameters: TParams) => QueryCallbackReturnType` - Function that receives the database instance and parameters
-- `parameters: TParams` - Parameters for the query (automatically memoized)
+The returned hook accepts:
+- `driveId`: The ID of the drive
+- `queryCallback`: Function that receives the database instance and optional parameters
+- `parameters`: Optional parameters for the query
 
 ### Return Value
 
 ```typescript
 {
-  isLoading: boolean;    // True while query is loading
-  error: Error | null;   // Any error that occurred
-  result: LiveQueryResults<T> | null; // Query results with real-time updates
+  isLoading: boolean;      // True while loading or retrying
+  error: Error | null;     // Any error that occurred
+  result: LiveQueryResults<T> | null;  // Query results with live updates
 }
 ```
 
 ### Notes / Caveats
 
-- Parameters are automatically memoized using deep comparison
-- Queries update in real-time when the database changes
-- The callback must return an object with `sql` and optional `parameters` properties
-- Use `.compile()` on Kysely queries to get the required format
-
-### Related Hooks
-
-- [`useOperationalStore`](#useoperationalstore) - For direct database access
-- [`useOperationalQuery`](#useoperationalquery) - Lower-level query hook
+- Create one `useTypedQuery` hook per processor
+- The hook includes automatic retry logic for common errors
+- Parameters are automatically memoized
+- Queries are live and will update automatically when data changes
 
 </details>
 
@@ -246,8 +240,8 @@ function DatabaseOperations() {
 
 ### Related Hooks
 
-- [`createProcessorQuery`](#createProcessorQuery) - For optimized queries
-- [`useOperationalQuery`](#useoperationalquery) - For manual query control
+- [`createProcessorQuery`](#1-createprocessorquery) - For optimized queries
+- [`useOperationalQuery`](#3-useoperationalquery) - For manual query control
 
 </details>
 
@@ -314,8 +308,8 @@ function UserCount() {
 
 ### Related Hooks
 
-- [`createProcessorQuery`](#createProcessorQuery) - Recommended higher-level API
-- [`useOperationalStore`](#useoperationalstore) - For direct database access
+- [`createProcessorQuery`](#1-createprocessorquery) - Recommended higher-level API
+- [`useOperationalStore`](#2-useoperationalstore) - For direct database access
 
 </details>
 

package/docs/academy/04-APIReferences/05-PHDocumentMigrationGuide.md

@@ -1,12 +1,12 @@
-# PHDocument Migration Guide (v3.3.0)
+# PHDocument Migration Guide
 
 :::tip
-This guide covers the **breaking changes** introduced in Powerhouse v3.3.0 related to PHDocument structure changes. If you're upgrading from v3.2.0 or earlier, **this migration is required** and document models must be regenerated.
+This guide covers the **breaking changes** introduced in Powerhouse v4.0.0 related to PHDocument structure changes. If you're upgrading from v3.2.0 or earlier, **this migration is required** and document models must be regenerated.
 :::
 
 ## Overview
 
-Version 3.3.0 introduced a significant refactor of the `PHDocument` structure that consolidates document metadata into a `header` field. This change enables signed and unsigned documents with cryptographic verification capabilities, but requires updating all code that accesses document properties.
+Version 4.0.0 introduced a significant refactor of the `PHDocument` structure that consolidates document metadata into a `header` field. This change enables signed and unsigned documents with cryptographic verification capabilities, but requires updating all code that accesses document properties.
 
 ## What Changed
 
@@ -28,7 +28,7 @@ const document = {
 }
 ```
 
-**After (v3.3.0):**
+**After (v4.0.0):**
 ```javascript
 const document = {
   header: {
@@ -328,11 +328,10 @@ describe('Document Migration', () => {
 
 ## Related Documentation
 
-- [PHDocument Architecture](../05-Architecture/PHDocument.md)
-- [Document Model Creation](../02-MasteryTrack/DocumentModelCreation/WhatIsADocumentModel.md)
-- [GraphQL API Reference](./02-ReactorAPI.md)
-- [React Hooks](./01-ReactHooks.md)
+- [PHDocument Architecture](/academy/Architecture/PowerhouseArchitecture)
+- [Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel)
+- [React Hooks](/academy/APIReferences/ReactHooks)
 
 ---
 
-*This migration guide covers the major changes in v3.3.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 
+*This migration guide covers the major changes in v4.0.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 

package/package.json

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

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-AnalyticsProcessorTutorial/05-AnalyticsTutorial

@@ -1,4 +0,0 @@
-## Start the Reactor & Connect
-
-## Use the analytics modal / Explain the modal
-