@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

package/docs/academy/01-GetStarted/02-DefineToDoListDocumentModel.md

@@ -1,64 +1,15 @@
 # Write the document specification
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [step-2-generate-todo-list-document-model](https://github.com/powerhouse-inc/todo-tutorial/tree/step-2-generate-todo-list-document-model)
-
-This tutorial step has a corresponding branch. After completing this step, your project will have a generated document model with:
-- Document model specification files (`todo-list.json`, `schema.graphql`)
-- Auto-generated TypeScript types and action creators
-- Reducer scaffolding ready for implementation
-:::
-
-<details>
-<summary>📖 How to use this tutorial</summary>
-
-**Prerequisites**: Complete step 1 and set up the tutorial remote (see previous step).
-
-### Compare your generated code
-
-After running `ph generate TodoList.phdm.zip`, compare with the reference:
-
-```bash
-# Compare all generated files with step-2
-git diff tutorial/step-2-generate-todo-list-document-model
-
-# Compare specific directory
-git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/
-```
-
-### See what was generated
-
-View the complete step-2 reference code:
-
-```bash
-# List files in the tutorial's step-2
-git ls-tree -r --name-only tutorial/step-2-generate-todo-list-document-model document-models/
-
-# View a specific file from step-2
-git show tutorial/step-2-generate-todo-list-document-model:document-models/todo-list/schema.graphql
-```
-
-### Visual comparison with GitHub Desktop
-
-After making a commit, use GitHub Desktop for visual diff:
-1. **Branch** menu → **"Compare to Branch..."**
-2. Select `tutorial/step-2-generate-todo-list-document-model`
-3. Review all file differences in the visual interface
-
-See step 1 for detailed GitHub Desktop instructions.
-
-</details>
-
-In this tutorial, you will learn how to define the specifications for a **To-do List** document model within Vetra Studio using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
+In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
 
-Before you start, make sure you have Vetra Studio running locally with the command:
+Before you start, make sure you have the Connect application running locally with the command:
 
 ```bash
-ph vetra
+ph connect
 ```
 
-Vetra Studio will start and you will see the following output:
+The Connect application will start and you will see the following output:
 
 ```bash
   ➜  Local:   http://localhost:3000/
@@ -66,13 +17,14 @@ Vetra Studio will start and you will see the following output:
   ➜  press h + enter to show help
 ```
 
-## TodoList document specification
+## To-do list document specification
 
-Make sure you have named your document model `TodoList` (PascalCase, no spaces or hyphens).  
-**Pay close attention to capitalization, as it influences our code generation.**
+Likely you have called your project 'ToDoList'.  
+If you've used a different name, please create a new document specification named 'ToDoList'.  
+**Pay close attention to capitalization, as it influences our code.**
 
 We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.  
-Below, you can see the SDL for the `TodoList` document model.
+Below, you can see the SDL for the `To-do List` document model.
 
 :::info
 This schema defines the **data structure** of the document model and the types involved in its operations, which are detailed further as input types.
@@ -80,49 +32,48 @@ Documents in Powerhouse leverage **event sourcing principles**, where every stat
 :::
 
 <details>
-<summary>State schema of our simplified TodoList</summary>
+<summary>State schema of our simplified To-do list</summary>
 
 ```graphql
-# The state of our TodoList - contains an array of todo items
-type TodoListState {
-  items: [TodoItem!]!
+# The state of our ToDoList
+type ToDoListState {
+  items: [ToDoItem!]!
 }
 
-# A single to-do item with its properties
-type TodoItem {
-  id: OID!        # Unique identifier for each to-do item
-  text: String!   # The text description of the to-do item
-  checked: Boolean!  # Status of the to-do item (checked/unchecked)
+# A single to-do item
+type ToDoItem {
+  id: ID!
+  text: String!
+  checked: Boolean!
 }
 ```
 
 </details>
 
 <details>
-<summary>Operations schema of our simplified TodoList</summary>
-
+<summary>Operations schema of our simplified to-do list</summary>
 ```graphql
 # Defines a GraphQL input type for adding a new to-do item
-# Only text is required - ID is generated automatically, checked defaults to false
 input AddTodoItemInput {
-  text: String!  # The text for the new todo item
+  id: ID!
+  text: String!
 }
 
 # Defines a GraphQL input type for updating a to-do item
-# ID is required to identify which item to update
-# text and checked are optional - only provided fields will be updated
+
 input UpdateTodoItemInput {
-  id: OID!       # Required: which item to update
-  text: String   # Optional: new text value
-  checked: Boolean  # Optional: new checked state
+id: ID!
+text: String
+checked: Boolean
 }
 
 # Defines a GraphQL input type for deleting a to-do item
+
 input DeleteTodoItemInput {
-  id: OID!  # The ID of the item to delete
+id: ID!
 }
-```
 
+````
 </details>
 
 ## Define the document model specification
@@ -131,21 +82,22 @@ To be able to define the document model, you need to open the document model edi
 
 ### The steps below show you how to do this:
 
-1. In Vetra Studio, click on **'document model'** to open the document model specification editor.
-2. Name your document model `TodoList` (PascalCase, no spaces or hyphens) in the Connect application. **Pay close attention to capitalization, as it influences code generation.**
+1. In the Connect application, click on **'document model'** to open the document model specification editor.
+2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization.
 3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
 
-    In the **Document Type** field, type `powerhouse/todo-list` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification.
+    In the **Document Type** field, type `powerhouse/todolist`. This defines the new type of document that will be created with this document model specification.
 
-    ![TodoList Document Model Form Metadata](./images/DocumentModelHeader.png)
+    ![ToDoList Document Model Form Metadata](./images/DocumentModelHeader.png)
 
 4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language.
-5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `todos`. Press enter.
+5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `to_do_list`. Press enter.
 6. Now there is a new field, called `Add operation`. Here you will have to add each input operation to the module, one by one.
 7. Inside the `Add operation` field, type `ADD_TODO_ITEM` and press enter. A small editor will appear underneath it, with an empty input type that you have to fill. Copy the first input type from the [Operations Schema](#operations-schema) section and paste it in the editor. The editor should look like this:
 
     ```graphql
     input AddTodoItemInput {
+        id: ID!
         text: String!
     }
     ```
@@ -158,46 +110,7 @@ Check below screenshot for the complete implementation:
 
 ![ToDoList Document Model](./images/DocumentModelOperations.png)
 
-## Verify your document model generation
-
-If you have been watching the terminal in your IDE you will see that Vetra has been tracking your changes and scaffolding your directory. Your project should have the following structure in `document-models/todo-list/`:
-
-```
-document-models/todo-list/
-├── gen/                          # Auto-generated code (don't edit)
-│   ├── actions.ts
-│   ├── creators.ts              # Action creator functions
-│   ├── types.ts                 # TypeScript type definitions
-│   ├── reducer.ts
-│   └── todos/
-│       └── operations.ts        # Operation type definitions
-├── src/                          # Your custom implementation
-│   ├── reducers/
-│   │   └── todos.ts            # Reducer functions (to implement next)
-│   └── tests/
-│       └── todos.test.ts        # Test file scaffolding
-├── todo-list.json               # Document model specification
-└── schema.graphql               # GraphQL schema
-```
-
-:::tip Check your work
-
-To make sure everything works as expected:
-
-```bash
-# Check types compile correctly
-pnpm tsc
-
-# Check linting passes
-pnpm lint
-
-# Compare your generated files with step-2
-git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/
-```
-
-:::
-
 ### Up next: reducers
 
-Up next, you'll learn how to implement the runtime logic and components that will use the `TodoList` document model specification you've just created and exported.
+Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported.
 

package/docs/academy/01-GetStarted/03-ImplementOperationReducers.md

@@ -1,48 +1,8 @@
-# Implement the document model reducers
+# Implement the document model
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [step-3-implement-reducer-operation-handlers](https://github.com/powerhouse-inc/todo-tutorial/tree/step-3-implement-reducer-operation-handlers)
+In this section, we will implement and test the operation reducers for the **To-do List** document model. For this, you have to export the document model specification from the Connect application and import it into your Powerhouse project directory.
 
-This step focuses on implementing the reducer logic for add, update, and delete operations.
-:::
-
-<details>
-<summary>📖 How to use this tutorial</summary>
-
-### Compare your reducer implementation
-
-After implementing your reducers:
-
-```bash
-# Compare your reducers with the reference
-git diff tutorial/step-3-implement-reducer-operation-handlers -- document-models/todo-list/src/reducers/
-
-# View the reference reducer implementation
-git show tutorial/step-3-implement-reducer-operation-handlers:document-models/todo-list/src/reducers/todos.ts
-```
-
-### Visual comparison with GitHub Desktop
-
-After committing your work, compare visually:
-1. **Branch** menu → **"Compare to Branch..."**
-2. Select `tutorial/step-3-implement-reducer-operation-handlers`
-3. Review differences in the visual interface
-
-### If you get stuck
-
-View or reset to a specific step:
-
-```bash
-# View the reducer code
-git show tutorial/step-3-implement-reducer-operation-handlers:document-models/todo-list/src/reducers/todos.ts
-
-# Reset to this step (WARNING: loses your changes)
-git reset --hard tutorial/step-3-implement-reducer-operation-handlers
-```
-
-</details>
-
-In this section, we will implement the operation reducers for the **To-do List** document model. In the previous step Vetra imported our document specification and scaffolded our directory through code generation. If not, you can revisit the [Define TodoList Document Model](/academy/GetStarted/DefineToDoListDocumentModel) section.
+To export the document model specification, follow the steps in the [Define ToDoList Document Model](/academy/GetStarted/DefineToDoListDocumentModel) section.
 
 ## Understanding reducers in document models
 
@@ -53,172 +13,189 @@ Reducers are a core concept in Powerhouse document models. They implement the st
 The reducers provide the actual implementation of what happens when those operations are performed.
 :::
 
-## Explore the generated reducer file
+To import the document model specification into your Powerhouse project, you can either:
 
-Navigate to `/document-models/todo-list/src/reducers/todos.ts` and open it. You should see scaffolding code that needs to be filled for the three operations you specified:
+- Copy and paste the file directly into the root of your Powerhouse project.
+- Or drag and drop the file into the Powerhouse project directory in the VSCode editor as seen in the image below:
 
-```typescript
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    // TODO: Implement "addTodoItemOperation" reducer
-    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
-  },
-  updateTodoItemOperation(state, action) {
-    // TODO: Implement "updateTodoItemOperation" reducer
-    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
-  },
-  deleteTodoItemOperation(state, action) {
-    // TODO: Implement "deleteTodoItemOperation" reducer
-    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-  },
-};
-```
+Either step will import the document model specification into your Powerhouse project.
 
-## Implement the operation reducers
+![vscode image](./images/vscode.png)
 
-Let's implement each reducer one by one.
+## In your project directory
 
-### Step 1: Add the import
+The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well.
 
-First, add the `generateId` import at the top of the file:
+To write the operation reducers of the **To-do List** document model, you need to generate the document model code from the document model specification file you have exported into the Powerhouse project directory.
 
-```typescript
-// added-line
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-```
-
-### Step 2: Implement addTodoItemOperation
+To do this, run the following command in the terminal:
 
-Replace the boilerplate `addTodoItemOperation` with the actual implementation:
-
-```typescript
-export const todoListTodosOperations: TodoListTodosOperations = {
-  // removed-start
-  addTodoItemOperation(state, action) {
-    // TODO: Implement "addTodoItemOperation" reducer
-    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
-  },
-  // removed-end
-  // added-start
-  addTodoItemOperation(state, action) {
-    const id = generateId();
-    state.items.push({ ...action.input, id, checked: false });
-  },
-  // added-end
-  updateTodoItemOperation(state, action) {
-    // ...
-  },
-  deleteTodoItemOperation(state, action) {
-    // ...
-  },
-};
+```bash
+ph generate ToDoList.phdm.zip
 ```
 
-**What's happening here:**
-- We generate a unique ID using `generateId()` from `document-model/core`
-- We push a new item to the `items` array with the input text, new ID, and `checked: false`
-- Under the hood, Powerhouse uses Immer.js, so this "mutation" is actually immutable
+Now you can navigate to `/document-models/to-do-list/src/reducers/to-do-list.ts` and start writing the operation reducers.
 
-### Step 3: Implement updateTodoItemOperation
+Open the `to-do-list.ts` file and you should see the code that needs to be filled for the three operations you have specified earlier. The image below shows the code that needs to be filled:
 
-Replace the boilerplate `updateTodoItemOperation`:
+![to-do-list ts file](./images/reducers.png)
 
-```typescript
-  // removed-start
-  updateTodoItemOperation(state, action) {
-    // TODO: Implement "updateTodoItemOperation" reducer
-    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
-  },
-  // removed-end
-  // added-start
-  updateTodoItemOperation(state, action) {
-    const item = state.items.find((item) => item.id === action.input.id);
-    if (!item) return;
-    item.text = action.input.text ?? item.text;
-    item.checked = action.input.checked ?? item.checked;
-  },
-  // added-end
-```
+## Write the operation reducers
 
-**What's happening here:**
-- We find the item by its ID
-- We return early if the item is not found
-- We use nullish coalescing (`??`) to only update fields that are provided
+1. Copy and paste the code below into the `to-do-list.ts` file in the `reducers` folder.
+2. Save the file.
 
-### Step 4: Implement deleteTodoItemOperation
+<details>
+<summary>Operation Reducers</summary>
+```typescript
+import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
+
+// REMARKS: This is our main reducer object that implements all operations defined in the schema.
+// The ToDoListToDoListOperations type is auto-generated from our SDL and ensures type safety.
+export const reducer: ToDoListToDoListOperations = {
+// REMARKS: The addTodoItemOperation adds a new item to our todolist.
+// - state: The current document state that we can modify
+// - action: Contains the operation type and input data from the client
+// - dispatch: Function to trigger additional operations (not used here)
+addTodoItemOperation(state, action, dispatch) {
+// REMARKS: While this looks like we're directly mutating state, Powerhouse
+// handles immutability behind the scenes, creating a new state object.
+state.items.push({
+id: action.input.id, // Using the client-provided ID
+text: action.input.text, // Setting the todo text from input
+checked: false, // New items always start unchecked
+});
+},
+
+// REMARKS: The updateTodoItemOperation modifies an existing todo item.
+// It handles partial updates, allowing only specific fields to be updated.
+updateTodoItemOperation(state, action, dispatch) {
+// REMARKS: First find the item we want to update by its ID
+const item = state.items.find(item => item.id === action.input.id);
+
+    // REMARKS: Proper error handling if item doesn't exist
+    if (!item) {
+      throw new Error(`Item with id ${action.input.id} not found`);
+    }
+
+    // REMARKS: We only update fields that were included in the input
+    // This allows for partial updates (only update what was provided)
+    if (action.input.text) {
+      item.text = action.input.text;
+    }
+    if (typeof action.input.checked === 'boolean') {
+      item.checked = action.input.checked;
+    }
+
+},
+
+// REMARKS: The deleteTodoItemOperation removes an item from the list.
+// This showcases functional programming with array filters for immutable updates.
+deleteTodoItemOperation(state, action, dispatch) {
+// REMARKS: Create a new array containing only items that don't match the ID
+// This is a common pattern for immutable array updates in JavaScript
+state.items = state.items.filter(item => item.id !== action.input.id);
+},
+};
 
-Replace the boilerplate `deleteTodoItemOperation`:
+````
+</details>
 
-```typescript
-  // removed-start
-  deleteTodoItemOperation(state, action) {
-    // TODO: Implement "deleteTodoItemOperation" reducer
-    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-  },
-  // removed-end
-  // added-start
-  deleteTodoItemOperation(state, action) {
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-  // added-end
-```
+## Write the operation reducers tests
 
-**What's happening here:**
-- We filter out the item with the matching ID
-- This creates a new array without the deleted item
+In order to make sure the operation reducers are working as expected, you need to write tests for them.
 
-## Complete reducer file
+Navigate to `/document-models/to-do-list/src/reducers/tests/to-do-list.test.ts` and copy and paste the code below into the file. Save the file.
 
-Here's the complete implementation:
+Here are the tests for the three operations implemented in the reducers file. This test file creates an empty ToDoList document model, then adds a todo item, updates it and deletes it.
 
 <details>
-<summary>Complete todos.ts</summary>
-
+<summary>Operation Reducers Tests</summary>
 ```typescript
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    const id = generateId();
-    state.items.push({ ...action.input, id, checked: false });
-  },
-  
-  updateTodoItemOperation(state, action) {
-    const item = state.items.find((item) => item.id === action.input.id);
-    if (!item) return;
-    item.text = action.input.text ?? item.text;
-    item.checked = action.input.checked ?? item.checked;
-  },
-  
-  deleteTodoItemOperation(state, action) {
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-};
-```
+import utils from '../../gen/utils.js';
+import { reducer } from '../../gen/reducer.js';
+import * as creators from '../../gen/creators.js';
+import { ToDoListDocument } from '../../gen/types.js';
+
+// REMARKS:
+// These tests demonstrate the event sourcing principles of our document model.
+// Each operation is recorded in the document's operations list and affects the state.
+
+describe('Todolist Operations', () => {
+    let document: ToDoListDocument;
+
+    beforeEach(() => {
+        // REMARKS: We start with a fresh, empty document for each test
+        document = utils.createDocument();
+    });
+
+    it('should handle addTodoItem operation', () => {
+        // REMARKS: We create an input object matching our AddTodoItemInput schema
+        const input = { id: '1', text: 'Buy milk' };
+
+        // REMARKS: We apply the operation to get a new document state
+        // Note how we use the creators to generate the operation action
+        const updatedDocument = reducer(document, creators.addTodoItem(input));
+
+        // REMARKS: We verify that:
+        // 1. The operation was recorded in the document's operation history
+        // 2. The state was updated according to our reducer implementation
+        expect(updatedDocument.operations.global).toHaveLength(1);
+        expect(updatedDocument.operations.global[0].type).toBe('ADD_TODO_ITEM');
+        expect(updatedDocument.state.global.items).toHaveLength(1);
+        expect(updatedDocument.state.global.items[0].text).toBe('Buy milk');
+    });
+
+    it('should handle updateTodoItem operation', () => {
+        // REMARKS: For update, we first need to add an item, then update it
+        // This demonstrates the sequential application of operations
+        const addInput = { id: '1', text: 'Buy milk' };
+        const updateInput = { id: '1', text: 'Buy bread' };
+
+        // REMARKS: Operations are applied in sequence, building up document state
+        const createdDocument = reducer(document, creators.addTodoItem(addInput));
+        const updatedDocument = reducer(createdDocument, creators.updateTodoItem(updateInput));
+
+        // REMARKS: Now we have 2 operations in history, and the state reflects both
+        expect(updatedDocument.operations.global).toHaveLength(2);
+        expect(updatedDocument.state.global.items[0].text).toBe('Buy bread');
+    });
+
+    it('should handle deleteTodoItem operation', () => {
+        // REMARKS: Similar pattern - add an item, then delete it
+        const addInput = { id: '1', text: 'Buy milk' };
+        const deleteInput = { id: '1' };
+
+        const createdDocument = reducer(document, creators.addTodoItem(addInput));
+        const updatedDocument = reducer(createdDocument, creators.deleteTodoItem(deleteInput));
+
+        // REMARKS: After deletion, we still have 2 operations in history,
+        // but the items array is now empty again in the final state
+        expect(updatedDocument.operations.global).toHaveLength(2);
+        expect(updatedDocument.state.global.items).toHaveLength(0);
+    });
+});
+````
 
 </details>
 
-:::tip Check your work
-
-To make sure everything works as expected:
+Now you can run the tests to make sure the operation reducers are working as expected.
 
 ```bash
-# Check types compile correctly
-pnpm tsc
+pnpm run test
+```
 
-# Check linting passes
-pnpm lint
+Output should be as follows:
 
-# Compare with reference implementation
-git diff tutorial/step-3-implement-reducer-operation-handlers -- document-models/todo-list/src/reducers/
+```bash
+ Test Files  2 passed (2)
+      Tests  5 passed (5)
+   Start at  12:04:57
+   Duration  417ms (transform 79ms, setup 0ms, collect 174ms, tests 12ms, environment 0ms, prepare 158ms)
 ```
 
-:::
+If you got the same output, you have successfully implemented the operation reducers and tests for the **To-do List** document model. Congratulations, you've successfully set up the backbone for a simple **To-do List** document.
 
-## Up next: Writing tests
+## Up next: To-do list editor
 
-In the next chapter, you'll write comprehensive tests to verify your reducer implementations work correctly.
+In the next chapter of this introduction track you will learn how to implement an editor for your document model so you can see a simple user interface for the **To-do List** document model in action.