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

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 3.3.0-dev.18 (2025-07-24)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 3.3.0-dev.17 (2025-07-23)
+
+### 🩹 Fixes
+
+- update release notes ([f1b6a8e71](https://github.com/powerhouse-inc/powerhouse/commit/f1b6a8e71))
+- add release notes on correct branch ([a2d60a537](https://github.com/powerhouse-inc/powerhouse/commit/a2d60a537))
+
+### ❤️ Thank You
+
+- Callme-T
+
 ## 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.

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

@@ -1,4 +1,4 @@
-# Using Subgraphs
+# Using 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.
@@ -79,11 +79,11 @@ Initializing Subgraph Manager...
   ➜  Reactor:   http://localhost:4001/d/powerhouse
 ```
 
-## 2. Building a To-do List Subgraph
+## 2. Building a to-do list subgraph
 
 Now that we've generated our subgraph, let's build a complete To-do List subgraph that extends the functionality of our To-do List document model. This subgraph will provide additional querying capabilities and demonstrate how subgraphs work with document models.
 
-### 2.1 Understanding the To-do List Document Model
+### 2.1 Understanding the to-do list document model
 
 Before building our subgraph, let's recall the structure of our To-do List document model from the [DocumentModelCreation tutorial](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema):
 
@@ -111,11 +111,11 @@ The document model has these operations:
 - `UPDATE_TODO_ITEM`: Updates an existing to-do item
 - `DELETE_TODO_ITEM`: Deletes a to-do item
 
-### 2.2 Define the Subgraph Schema
+### 2.2 Define the subgraph schema
 
 Now let's create a subgraph that provides enhanced querying capabilities for our To-do List documents. 
 
-**Step 1: Define the schema in `subgraphs/to-do-list/schema.ts`:**
+**Step 1: Define the schema in `subgraphs/to-do-list/schema.ts` by creating the file:**
 
 ```typescript
 export const typeDefs = `
@@ -148,19 +148,19 @@ export const typeDefs = `
     text: String!    # The task description
     checked: Boolean! # Completion status
   }
-`;
+}`
 ```
 
 
-
-#### Understanding Resolvers
+<details>
+<summary> #### Understanding resolvers </summary>
 
 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"
+1. **Understands the request** - "The user 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"
@@ -187,6 +187,8 @@ Think of resolvers as custom API endpoints that are automatically created based
 - **User Experience**: Different resolvers serve different user needs efficiently
 - **Flexibility**: Users can ask for exactly what they need, nothing more, nothing less
 
+</details>
+
 **Step 2: Create resolvers in `subgraphs/to-do-list/resolvers.ts`:**
 
 ```typescript
@@ -329,7 +331,7 @@ export default class ToDoListSubgraph {
 }
 ```
 
-### 2.3 Understanding the Implementation
+### 2.3 Understanding the implementation
 
 **What this multi-file approach provides:**
 
@@ -344,7 +346,7 @@ 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 Understanding the Document Model Event Integration
+### 2.4 Understanding the document model event integration
 
 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.
 
@@ -394,7 +396,7 @@ if (event.type === "DELETE_TODO_ITEM") {
 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
+### 2.5 Summary of what we've built
 
 Our complete To-do List subgraph includes:
 
@@ -411,7 +413,7 @@ Our complete To-do List subgraph includes:
 - **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
+## 3. Testing the to-do list subgraph
 
 ### 3.1. Start the reactor
 To activate the subgraph, run:
@@ -433,7 +435,7 @@ You should see the subgraph being registered in the console output:
 ### 3.2. Create some test data
 Before testing queries, let's create some To-do List documents with test data:
 
-1. Open Connect at `http://localhost:3001`
+1. Open Connect at `http://localhost:3001` in another terminal
 2. Add the 'remote' drive that is running locally via the (+) 'Add Drive' button. Add 'http://localhost:4001/d/powerhouse'
 3. Create a new To-do List document
 4. Add some test items:
@@ -654,25 +656,12 @@ This demonstrates how the supergraph provides a unified interface to both your d
 
 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:
 
-### What you built:
-- **A custom GraphQL schema** that provides enhanced querying capabilities for To-do List documents
-- **An operational data store** that efficiently stores and retrieves to-do items
-- **Real-time event processing** that keeps your subgraph synchronized with document model changes
-- **Advanced query capabilities** including filtering and counting operations
-- **Integration with the supergraph** for unified API access
-
 ### 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
 - **The supergraph** unifies multiple subgraphs into a single GraphQL endpoint
 
-### Next steps:
-- Explore adding **mutations** to your subgraph for more complex operations
-- Implement **data aggregation** for analytics and reporting
-- Connect to **external APIs** for enhanced functionality
-- Build **processors** that automate workflows between different document models
-
 This tutorial has provided you with a solid foundation for building sophisticated data processing and querying capabilities in the Powerhouse ecosystem.
 
 ## Subgraphs are particularly useful for
@@ -691,10 +680,6 @@ This tutorial has provided you with a solid foundation for building sophisticate
    - 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
 

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-RelationalDbProcessor.md

@@ -0,0 +1,663 @@
+# Relational database processor 
+
+In this chapter, we will implement a **Todo-List** relational database processor. This processor receives processed operations from the reactor and can use the `prevState`, `resultingState`, or data from the operations themselves to populate a database.
+
+**What is a Relational Database Processor?**
+
+A relational database processor is a specialized component that listens to document changes in your Powerhouse application and transforms that data into a traditional relational database format (like PostgreSQL, MySQL, or SQLite). This is incredibly useful for:
+
+- **Analytics and Reporting**: Running complex SQL queries on your document data
+- **Integration**: Connecting with existing business intelligence tools
+
+## Generate the Processor
+
+To generate a relational database processor, run the following command:
+
+```bash
+ph generate --processor todo-indexer --processor-type relationalDb --document-types powerhouse/todolist
+```
+
+**Breaking down this command:**
+- `--processor todo-indexer`: Creates a processor with the name "todo-indexer"
+- `--processor-type relationalDb`: Specifies we want a relational database processor (vs other types like analytics or webhook processors)
+- `--document-types powerhouse/todolist`: Tells the processor to only listen for changes to documents of type "powerhouse/todolist"
+
+This command creates a processor named `todo-indexer` of type `relational database` that listens for changes from documents of type `powerhouse/todolist`.
+
+**What gets generated:**
+- A processor class file (`processors/todo-indexer/index.ts`)
+- A database migration file (`processors/todo-indexer/migrations.ts`)
+- A factory file for configuration (`processors/todo-indexer/factory.ts`)
+- A schema file for TypeScript types (`processors/todo-indexer/schema.ts`)
+
+## Define Your Database Schema
+
+Next, define your database schema in the `processors/todo-indexer/migration.ts` file.
+
+**Understanding Database Migrations**
+
+Migrations are version-controlled database changes that ensure your database schema evolves safely over time. They contain:
+- **`up()` function**: Creates or modifies database structures when the processor starts
+- **`down()` function**: Safely removes changes when the processor is removed
+
+This approach ensures your database schema stays in sync across different environments (development, staging, production).
+
+The migration file contains `up` and `down` functions that are called when the processor is added or removed, respectively.
+
+In the migration.ts file you'll find an example of the todo table default schema:
+
+```ts
+import { type IRelationalDb } from "document-drive/processors/types"
+
+export async function up(db: IRelationalDb<any>): Promise<void> {
+  // Create table - this runs when the processor starts
+  await db.schema
+    .createTable("todo")                           // Creates a new table named "todo"
+    .addColumn("task", "varchar(255)")             // Text column for the task description (max 255 characters)
+    .addColumn("status", "boolean")                // Boolean column for completion status (true/false)
+    .addPrimaryKeyConstraint("todo_pkey", ["task"]) // Makes "task" the primary key (unique identifier)
+    .ifNotExists()                                 // Only create if table doesn't already exist
+    .execute();                                    // Execute the SQL command
+}
+
+export async function down(db: IRelationalDb<any>): Promise<void> {
+  // Drop table - this runs when the processor is removed
+  await db.schema.dropTable("todo").execute();
+}
+```
+
+**Design Considerations:**
+- We're using `task` as the primary key, which means each task description must be unique
+- The `varchar(255)` limit ensures reasonable memory usage
+- The `boolean` status makes it easy to filter completed vs. incomplete tasks
+- Consider adding timestamps (`created_at`, `updated_at`) for audit trails in production applications
+
+## Generate Database Types
+
+After defining your database schema, generate TypeScript types for type-safe queries and better IDE support:
+
+```bash
+ph generate --migration-file processors/todo-indexer/migrations.ts 
+```
+
+**Why Generate Types?**
+
+TypeScript types provide several benefits:
+- **Type Safety**: Catch errors at compile time instead of runtime
+- **IDE Support**: Get autocomplete and IntelliSense for your database queries
+- **Documentation**: Types serve as living documentation of your database structure
+- **Refactoring**: Safe renaming and restructuring of database fields
+
+Check your `processors/todo-indexer/schema.ts` file after generation - it will contain the TypeScript types for your database schema.
+
+**Example of generated types:**
+```ts
+// This is what gets auto-generated based on your migration
+export interface Database {
+  todo: {
+    task: string;
+    status: boolean;
+  };
+}
+```
+
+## Configure the Processor Filter
+
+This give you the opportunity to configure the processor filter in `processors/todo-indexer/factory.ts`:
+
+**Understanding Processor Filters**
+
+Filters determine which document changes your processor will respond to. This is crucial for performance and functionality:
+- **Performance**: Only process relevant changes to avoid unnecessary work
+- **Isolation**: Different processors can handle different document types
+- **Scalability**: Distribute processing load across multiple processors
+
+```ts
+import {
+  type ProcessorRecord,
+  type IProcessorHostModule,
+} from "document-drive/processors/types";
+import { type RelationalDbProcessorFilter } from "document-drive/processors/relational";
+import { TodoIndexerProcessor } from "./index.js";
+
+export const todoIndexerProcessorFactory =
+  (module: IProcessorHostModule) =>
+  async (driveId: string): Promise<ProcessorRecord[]> => {
+    // Create a namespace for the processor and the provided drive id
+    // Namespaces prevent data collisions between different drives
+    const namespace = TodoIndexerProcessor.getNamespace(driveId);
+
+    // Create a namespaced db for the processor
+    // This ensures each drive gets its own isolated database tables
+    const store =
+      await module.relationalDb.createNamespace<TodoIndexerProcessor>(
+        namespace,
+      );
+
+    // Create a filter for the processor
+    // This determines which document changes trigger the processor
+    const filter: RelationalDbProcessorFilter = {
+      branch: ["main"],                    // Only process changes from the "main" branch
+      documentId: ["*"],                   // Process changes from any document ID (* = wildcard)
+      documentType: ["powerhouse/todolist"], // Only process todolist documents
+      scope: ["global"],                   // Process global changes (not user-specific)
+    };
+
+    // Create the processor instance
+    const processor = new TodoIndexerProcessor(namespace, filter, store);
+    return [
+      {
+        processor,
+        filter,
+      },
+    ];
+  };
+```
+
+**Filter Options Explained:**
+- **`branch`**: Which document branches to monitor (usually "main" for production data)
+- **`documentId`**: Specific document IDs to watch ("*" means all documents)
+- **`documentType`**: Document types to process (ensures type safety)
+- **`scope`**: Whether to process global changes or user-specific ones
+
+## Implement the Processor Logic
+
+Now implement the actual processor logic in `processors/todo-indexer/index.ts` by copying the code underneath:
+
+**Understanding the Processor Lifecycle**
+
+The processor has several key methods:
+- **`initAndUpgrade()`**: Runs once when the processor starts (perfect for running migrations)
+- **`onStrands()`**: Runs every time relevant document changes occur (this is where the main logic goes)
+- **`onDisconnect()`**: Cleanup when the processor shuts down
+
+**What are "Strands"?**
+Strands represent a batch of operations that happened to documents. Each strand contains:
+- Document ID and metadata
+- Array of operations (create, update, delete, etc.)
+- Previous and resulting document states
+
+```ts
+import { type IRelationalDb } from "document-drive/processors/types";
+import { RelationalDbProcessor } from "document-drive/processors/relational";
+import { type InternalTransmitterUpdate } from "document-drive/server/listener/transmitter/internal";
+import type { ToDoListDocument } from "../../document-models/to-do-list/index.js";
+
+import { up } from "./migrations.js";
+import { type DB } from "./schema.js";
+
+// Define the document type this processor handles
+type DocumentType = ToDoListDocument;
+
+export class TodoIndexerProcessor extends RelationalDbProcessor<DB> {
+  // Generate a unique namespace for this processor based on the drive ID
+  // This prevents data conflicts between different drives
+  static override getNamespace(driveId: string): string {
+    // Default namespace: `${this.name}_${driveId.replaceAll("-", "_")}`
+    return super.getNamespace(driveId);
+  }
+
+  // Initialize the processor and run database migrations
+  // This method runs once when the processor starts up
+  override async initAndUpgrade(): Promise<void> {
+    await up(this.relationalDb); // Run the database migration to create tables
+  }
+
+  // Main processing logic - handles incoming document changes
+  // This method is called whenever there are new document operations
+  override async onStrands(
+    strands: InternalTransmitterUpdate<DocumentType>[],
+  ): Promise<void> {
+    // Early return if no changes to process
+    if (strands.length === 0) {
+      return;
+    }
+
+    // Process each strand (batch of changes) individually
+    for (const strand of strands) {
+      // Skip strands with no operations
+      if (strand.operations.length === 0) {
+        continue;
+      }
+
+      // Process each operation within the strand
+      for (const operation of strand.operations) {
+        // Insert a record for each operation into the database
+        // This is a simple example - you might want more sophisticated logic
+        await this.relationalDb
+          .insertInto("todo")
+          .values({
+            // Create a unique task identifier combining document ID, operation index, and type
+            task: `${strand.documentId}-${operation.index}: ${operation.type}`,
+            status: true, // Default to completed status
+          })
+          // Handle conflicts by doing nothing if the task already exists
+          // This prevents duplicate entries if operations are replayed
+          .onConflict((oc) => oc.column("task").doNothing())
+          .execute(); // Execute the database query
+      }
+    }
+  }
+
+  // Cleanup method called when the processor disconnects
+  // Use this for closing connections, clearing caches, etc.
+  async onDisconnect() {
+    // Add any cleanup logic here
+    // For example: await this.relationalDb.destroy();
+  }
+}
+```
+
+## Expose Data Through a Subgraph
+
+### Generate a Subgraph
+
+Generate a new subgraph to expose your processor data:
+
+```bash
+ph generate --subgraph todo
+```
+
+**What is a Subgraph?**
+
+A subgraph is a GraphQL schema that exposes your processed data to clients. It:
+- Provides a standardized API for accessing your relational database data
+- Integrates with the Powerhouse supergraph for unified data access
+- Supports both queries (reading data) and mutations (modifying data)
+- Can join data across multiple processors and document types
+
+### Configure the Subgraph
+
+Open `./subgraphs/todo/index.ts` and configure the resolvers:
+
+```ts
+import { Subgraph } from "@powerhousedao/reactor-api";
+import { gql } from "graphql-tag";
+import { TodoIndexerProcessor } from "../../processors/todo-indexer/index.js";
+
+export class TodoSubgraph extends Subgraph {
+  // Human-readable name for this subgraph
+  name = "Todos";
+
+  // GraphQL resolvers - functions that fetch data for each field
+  resolvers = {
+    Query: {
+      todos: {
+        // Resolver function for the "todos" query
+        // Arguments: parent object, query arguments, context, GraphQL info
+        resolve: async (_: any, args: {driveId: string}) => {
+          // Query the database using the processor's static query method
+          // This gives us access to the namespaced database for the specific drive
+          const todos = await TodoIndexerProcessor.query(args.driveId, this.relationalDb)
+            .selectFrom("todo")        // Select from the "todo" table
+            .selectAll()              // Get all columns
+            .execute();               // Execute the query
+
+          // Transform database results to match GraphQL schema
+          return todos.map((todo) => ({
+            task: todo.task,          // Map database "task" column to GraphQL "task" field
+            status: todo.status,      // Map database "status" column to GraphQL "status" field
+          }));
+        },
+      },
+    },
+  };
+
+  // GraphQL schema definition using GraphQL Schema Definition Language (SDL)
+  typeDefs = gql`
+
+  # Define the structure of a todo item as returned by GraphQL
+  type ToDoListEntry {
+    task: String!     # The task description (! means required/non-null)
+    status: Boolean!  # The completion status (true = done, false = pending)
+  }
+
+  # Define available queries
+  type Query {
+    todos(driveId: ID!): [ToDoListEntry]  # Get array of todos for a specific drive
+  }
+  `;
+
+  // Cleanup method called when the subgraph disconnects
+  async onDisconnect() {
+    // Add any cleanup logic here if needed
+  }
+}
+```
+
+## Now query the data via the supergraph.
+
+**Understanding the Supergraph**
+
+The Powerhouse supergraph is a unified GraphQL endpoint that combines:
+- **Document Models**: Direct access to your Powerhouse documents
+- **Subgraphs**: Custom data views from your processors
+- **Built-in APIs**: System functionality like authentication and drives
+
+This unified approach means you can query document state AND processed data in a single request, which is perfect for building rich user interfaces.
+
+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:
+
+  ```bash
+  ph reactor
+  ```
+
+- Open the GraphQL editor in your browser:
+
+  ```
+  http://localhost:4001/graphql
+  ```
+The supergraph allows you to both query & mutate data from the same endpoint. 
+Read more about [subgraphs](/academy/MasteryTrack/WorkWithData/UsingSubgraphs)
+
+<details>
+<summary>**Example: Complete Data Flow from Document Operations to Relational Database**</summary>
+
+**Understanding the Complete Data Pipeline**
+
+This comprehensive example demonstrates the **entire data flow** in a Powerhouse application:
+1. **Storage Layer**: Create a drive (document storage container)
+2. **Document Layer**: Create a todo document and add operations
+3. **Processing Layer**: Watch the relational database processor automatically index changes
+4. **API Layer**: Query both original document state AND processed relational data
+5. **Analysis**: Compare the different data representations
+
+---
+
+### **Step 1: Create a Drive (Storage Container)**
+
+**What's Happening**: Every document needs a "drive" - think of it as a folder or database that contains related documents. This is where your todo documents will live.
+
+```graphql
+mutation DriveCreation($name: String!) {
+  addDrive(name: $name) {
+    name
+  }
+}
+```
+
+Variables: 
+```json
+{
+  "driveId": "powerhouse",
+  "name": "tutorial"
+}
+```
+
+💡 **Behind the Scenes**: This creates a new drive namespace. Your relational database processor will create isolated tables for this drive using the namespace pattern we defined earlier.
+
+---
+
+### **Step 2: Create a Todo Document**
+
+**What's Happening**: Now we're creating an actual todo list document inside our drive. This uses the document model we built in previous chapters.
+
+```graphql
+mutation Mutation($driveId: String, $name: String) {
+  ToDoList_createDocument(driveId: $driveId, name: $name)
+}
+```
+
+Variables:
+```json
+{
+  "driveId": "powerhouse",
+  "name": "tutorial"
+}
+```
+
+Result:
+```json
+{
+  "data": {
+    "ToDoList_createDocument": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b"
+  }
+}
+```
+
+💡 **Key Insight**: The returned UUID (`72b73d31-4874-4b71-8cc3-289ed4cfbe2b`) is crucial - this is the document ID that will appear in our processor's database records, linking operations back to their source document. You will receive a different UUID.
+
+---
+
+### **Step 3: Add Todo Items (Generate Operations)**
+
+**What's Happening**: Each time we add a todo item, we're creating a new **operation** in the document's history. Our relational database processor is listening for these operations in real-time.
+
+```graphql
+mutation Mutation($driveId: String, $docId: PHID, $input: ToDoList_AddTodoItemInput) {
+  ToDoList_addTodoItem(driveId: $driveId, docId: $docId, input: $input)
+}
+```
+
+Variables:
+```json
+{
+  "driveId": "powerhouse",
+  "name": "tutorial",
+  "docId": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b",
+  "input": {
+    "id": "1",
+    "text": "complete mutation"
+  }
+}
+```
+
+Result:
+```json
+{
+  "data": {
+    "ToDoList_addTodoItem": 1
+  }
+}
+```
+
+💡 **What Happens Next**: 
+1. **Document Model**: Stores the operation and updates document state
+2. **Reactor**: Broadcasts the operation to all listening processors
+3. **Our Processor**: Automatically receives the operation and creates a database record
+4. **Database**: Now contains: `"72b73d31-4874-4b71-8cc3-289ed4cfbe2b-0: ADD_TODO_ITEM"`
+
+🔄 **Repeat this step 2-3 times** with different todo items to see multiple operations get processed. Each operation will have an incrementing index (0, 1, 2...).
+
+---
+
+### **Step 4: Query Both Data Sources**
+
+**The Power of Dual Data Access**: Now we can query BOTH the original document state AND our processed relational data in a single GraphQL request. This demonstrates the flexibility of the Powerhouse architecture.
+
+```graphql
+query Query($driveId: ID!) {
+  todos(driveId: $driveId) {
+    task
+    status
+  }
+  ToDoList {
+    getDocuments {
+      state {
+        items {
+          text
+        }
+      }
+    }
+  }
+}
+```
+
+Variables:
+```json
+{
+  "driveId": "powerhouse"
+}
+```
+
+Response:
+```json
+{
+  "data": {
+    "todos": [
+      {
+        "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-0: ADD_TODO_ITEM",
+        "status": true
+      },
+      {
+        "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-1: ADD_TODO_ITEM",
+        "status": true
+      },
+      {
+        "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-2: ADD_TODO_ITEM",
+        "status": true
+      }
+    ],
+    "ToDoList": {
+      "getDocuments": [
+        {
+          "state": {
+            "items": [
+              {
+                "text": "complete mutation"
+              },
+              {
+                "text": "add another todo"
+              },
+              {
+                "text": "Now check the data"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### **🔍 Data Analysis: Understanding What You're Seeing**
+
+**Document Model Data (`ToDoList.getDocuments`):**
+- ✅ **Current State**: Shows the final todo items as they exist in the document
+- ✅ **User-Friendly**: Displays actual todo text like "complete mutation"
+- ✅ **Real-Time**: Always reflects the latest document state
+- ❌ **Limited History**: Doesn't show how the document changed over time
+
+**Processed Relational Data (`todos`):**
+- ✅ **Operation History**: Shows each individual operation that occurred
+- ✅ **Audit Trail**: You can see the sequence (0, 1, 2) of operations
+- ✅ **Analytics Ready**: Perfect for counting operations, tracking changes
+- ✅ **Integration Friendly**: Standard SQL database that other tools can access
+- ❌ **Less User-Friendly**: Shows operation metadata rather than final state
+
+---
+
+**Key Differences:**
+- **Document Query**: Gets the current state directly from the document model
+- **Subgraph Query**: Gets processed/transformed data from your relational database
+- **Combined Power**: You can query both in a single GraphQL request for rich UIs
+
+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.  
+</details>
+
+## Use the Data in Frontend Applications
+
+**Integration Options**
+
+Your processed data can now be consumed by any GraphQL client:
+- **React**: Using Apollo Client, urql, or Relay
+- **Next.js**: API routes, getServerSideProps, or app router
+- **Mobile Apps**: React Native, Flutter, or native iOS/Android
+- **Desktop Apps**: Electron, Tauri, or other frameworks
+- **Third-party Tools**: Any tool that supports GraphQL APIs
+
+### React Hooks
+
+**Coming Soon**: This section will cover how to use React hooks to consume your subgraph data in React applications. For now, you can use standard GraphQL clients like Apollo or urql to query your supergraph endpoint.
+
+### Next.js API Route Example
+
+**Why API Routes?**
+
+Next.js API routes are useful when you need to:
+- Add server-side authentication or authorization
+- Transform data before sending to the client
+- Implement caching or rate limiting
+- Proxy requests to avoid CORS issues
+- Add logging or monitoring
+
+```ts
+// pages/api/todos.ts
+import { type NextApiRequest, type NextApiResponse } from "next"
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  // Only allow GET requests for this endpoint
+  if (req.method !== "GET") {
+    return res.status(405).json({ message: "Method not allowed" });
+  }
+
+  // Extract driveId from query parameters, default to "powerhouse"
+  const { driveId = "powerhouse" } = req.query;
+
+  try {
+    // Query your subgraph or database directly
+    // In production, you might want to add authentication headers here
+    const response = await fetch("http://localhost:4001/graphql", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: `
+          query GetTodoList($driveId: String) {
+            todoList(driveId: $driveId) {
+              id
+              name
+              completed
+              createdAt
+              updatedAt
+            }
+          }
+        `,
+        variables: { driveId },
+      }),
+    });
+
+    const data = await response.json();
+    
+    // Return the todos array from the GraphQL response
+    res.status(200).json(data.data.todoList);
+  } catch (error) {
+    // Log the error for debugging (in production, use proper logging)
+    console.error("Failed to fetch todos:", error);
+    
+    // Return a generic error message to the client
+    res.status(500).json({ error: "Failed to fetch todos" });
+  }
+}
+```
+
+## Summary
+
+You've successfully created a relational database processor that:
+
+1. ✅ **Listens for document changes** - Automatically detects when todo documents are modified
+2. ✅ **Stores data in a structured database** - Transforms document operations into relational data
+3. ✅ **Provides type-safe database operations** - Uses TypeScript for compile-time safety
+4. ✅ **Exposes data through GraphQL** - Makes processed data available via a unified API
+5. ✅ **Can be consumed by frontend applications** - Ready for integration with any GraphQL client
+
+
+This processor will automatically sync your document changes to the relational database, making the data available for complex queries, reporting, and integration with other systems.
+
+**Real-World Applications:**
+
+This pattern is commonly used for:
+- **Analytics dashboards** showing document usage patterns
+- **Business intelligence** reports on document data
+- **Integration** with existing enterprise systems
+- **Search and filtering** with complex SQL queries
+- **Data archival** and compliance requirements
+
+

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-drive-analytics.md

@@ -1,4 +1,4 @@
-# Drive Analytics
+# Drive analytics
 
 Drive Analytics provides automated monitoring and insights into document drive operations within Powerhouse applications. This system tracks user interactions, document modifications, and drive activity to help developers understand usage patterns and system performance.
 

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

@@ -173,28 +173,28 @@ The returned hook accepts:
 
 </details>
 
-### 2. useOperationalStore()
+### 2. useRelationalDb()
 
 <details>
-<summary>`useOperationalStore<Schema>()`: Access the enhanced database instance directly</summary>
+<summary>`useRelationalDb<Schema>()`: Access the enhanced database instance directly</summary>
 
 ### Hook Name and Signature
 
 ```typescript
-function useOperationalStore<Schema>(): IOperationalStore<Schema>
+function useRelationalDb<Schema>(): IRelationalDb<Schema>
 ```
 
 ### Description
 
-Provides direct access to the enhanced Kysely database instance with live query capabilities. Use this when you need to perform operational database operations outside of the typical query patterns.
+Provides direct access to the enhanced Kysely database instance with live query capabilities. Use this when you need to perform relational database operations outside of the typical query patterns.
 
 ### Usage Example
 
 ```typescript
-import { useOperationalStore } from '@powerhousedao/reactor-browser/operational';
+import { useRelationalDb } from '@powerhousedao/reactor-browser/relational';
 
 function DatabaseOperations() {
-  const { db, isLoading, error } = useOperationalStore<MyDatabase>();
+  const { db, isLoading, error } = useRelationalDb<MyDatabase>();
   
   const createUser = async (name: string, email: string) => {
     if (!db) return;
@@ -241,19 +241,19 @@ function DatabaseOperations() {
 ### Related Hooks
 
 - [`createProcessorQuery`](#1-createprocessorquery) - For optimized queries
-- [`useOperationalQuery`](#3-useoperationalquery) - For manual query control
+- [`useRelationalQuery`](#3-userelationalquery) - For manual query control
 
 </details>
 
-### 3. useOperationalQuery()
+### 3. useRelationalQuery()
 
 <details>
-<summary>`useOperationalQuery<Schema, T, TParams>()`: Lower-level hook for manual query control</summary>
+<summary>`useRelationalQuery<Schema, T, TParams>()`: Lower-level hook for manual query control</summary>
 
 ### Hook Name and Signature
 
 ```typescript
-function useOperationalQuery<Schema, T, TParams>(
+function useRelationalQuery<Schema, T, TParams>(
   queryCallback: (db: EnhancedKysely<Schema>, parameters?: TParams) => QueryCallbackReturnType,
   parameters?: TParams
 ): QueryResult<T>
@@ -266,10 +266,10 @@ Lower-level hook for creating live queries with manual control over the query ca
 ### Usage Example
 
 ```typescript
-import { useOperationalQuery } from '@powerhousedao/reactor-browser/operational';
+import { useRelationalQuery } from '@powerhousedao/reactor-browser/relational';
 
 function UserCount() {
-  const { result, isLoading, error } = useOperationalQuery<MyDatabase, { count: number }>(
+  const { result, isLoading, error } = useRelationalQuery<MyDatabase, { count: number }>(
     (db) => {
       return db
         .selectFrom('users')
@@ -309,7 +309,7 @@ function UserCount() {
 ### Related Hooks
 
 - [`createProcessorQuery`](#1-createprocessorquery) - Recommended higher-level API
-- [`useOperationalStore`](#2-useoperationalstore) - For direct database access
+- [`useRelationalDb`](#2-usedelationaldb) - For direct database access
 
 </details>
 

package/package.json

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

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-OperationalDbProcessorTutorial/01-TodoList-example.md

@@ -1,383 +0,0 @@
-# Build a Todo-List Processor
-
-## 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.
-
-## 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.
-
-```bash
-ph generate --processor todo-processor --processor-type relational-db --document-types 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
-
----
-
-## Step 2: Define Your Database Schema
-
-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.
-
-**File location:** `processors/todo-processor/migration.ts`
-
-### 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"
-
-export async function up(db: IBaseRelationalDb): Promise<void> {
-  // Create table
-  await db.schema
-    .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> {
-  // Clean up: drop the table when processor is removed
-  await db.schema.dropTable("todo").execute();
-}
-```
-
-**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
-
----
-
-## Step 3: Generate TypeScript Types
-
-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
-```
-
-**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;
-}
-```
-
-These types will be available in `processors/todo-processor/schema.ts` and ensure your database queries are type-safe.
-
----
-
-## 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 =
-  (module: IProcessorHostModule) =>
-  async (driveId: string): Promise<ProcessorRecord[]> => {
-    // Create a namespace for the processor and the provided drive id
-    const namespace = TodoProcessorProcessor.getNamespace(driveId);
-
-    // Create a filter for the processor
-    const filter: RelationalDbProcessorFilter = {
-      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
-    const store = await createNamespacedDb<TodoProcessorProcessor>(
-      namespace,
-      module.relationalStore,
-    );
-
-    // Create the processor
-    const processor = new TodoProcessorProcessor(namespace, filter, store);
-    return [
-      {
-        processor,
-        filter,
-      },
-    ];
-  };
-```
-
-**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.
-
----
-
-## 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;
-
-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,              // Use document ID as task name
-            status: true,                         // Default to completed
-          })
-          .execute();
-      }
-    }
-  }
-
-  async onDisconnect() {
-    // Cleanup logic when processor shuts down
-    // Could include closing connections, saving state, etc.
-  }
-}
-```
-
-### Understanding Strands and Operations
-
-**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
-
-**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.
-}
-```
-
-3. **Use transactions for consistency:**
-```ts
-await this.relationalDb.transaction().execute(async (trx) => {
-  // Multiple operations that should all succeed or all fail
-});
-```
-
----
-
-## 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.
-
-### 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",        // Default drive if none specified
-              this.relationalDb                    // Database connection from processor
-          )
-            .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!                              # Todo text (required)
-        completed: Boolean!                        # Completion status (required)
-      }
-
-      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

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