@powerhousedao/academy 5.1.0-dev.4 → 5.1.0-dev.5

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 5.1.0-dev.5 (2025-12-04)
+
+### 🚀 Features
+
+- connect crypto signer and verifier ([918fb1fab](https://github.com/powerhouse-inc/powerhouse/commit/918fb1fab))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+
 ## 5.1.0-dev.4 (2025-12-03)
 
 ### 🚀 Features

package/blog/BeyondCommunication-ABlueprintForDevelopment.md

@@ -1,7 +1,8 @@
 ---
 title: Beyond Communication - A Blueprint for Development
-description: GraphQL Schema’s as a common language for software design
+description: GraphQL Schema's as a common language for software design
 slug: Graphql-schema-as-a-common-language
+date: 2024-12-02
 authors:
   - name: Call me T.
     title: Product Manager at Powerhouse

package/blog/TheChallengeOfChange.md

@@ -2,6 +2,7 @@
 title: The Challenge of Change
 description: Rapid Application Development with document models.
 slug: Rapid-Application-Development-with-document-models.
+date: 2024-12-02
 authors:
   - name: Call me T.
     title: Product Manager at Powerhouse

package/docs/academy/01-GetStarted/00-ExploreDemoPackage.mdx

@@ -2,13 +2,13 @@
 
 ## Let's get started
 
-To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package?
+To give you a quick idea of how the Powerhouse Vetra builder platform operates on document models and packages, why don't you try installing a package?
 We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package containing a document model, an editor, and a drive app.
 
 ## Step 1: Install the Powerhouse CLI
 
 You will use the Powerhouse CLI to launch a local environment with a "To-do List Demo Package" installed.
-This is also the package that you'll recreate during the tutorials and gets you familiar with Powerhouse.
+This is also the package that you'll recreate during the tutorials and gets you familiar with Powerhouse Vetra.
 
 ```bash
 pnpm install -g ph-cmd

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md

@@ -1,6 +1,6 @@
-# Powerhouse builder tooling
+# Vetra builder tooling
 
-This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.  
+This page provides an overview of all the builder tooling offered in the Vetra ecosystem by Powerhouse.  
 This list will be maintained and updated as our toolkit grows.
 
 ## Powerhouse command line interface

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/02-SpecifyTheStateSchema.md

@@ -1,19 +1,19 @@
 # Specify the state schema
 
-The state schema is the backbone of your document model. It defines the structure, data types, and relationships of the information your document will hold. In Powerhouse, we use the GraphQL Schema Definition Language (SDL) to define this schema. A well-defined state schema is crucial for ensuring data integrity, consistency, and for enabling powerful querying and manipulation capabilities.
+The state schema is the backbone of your document model. It defines the structure, data types, and relationships of the information your document will hold. In Powerhouse, we use the **GraphQL Schema Definition Language (SDL)** to define this schema. A well-defined state schema is crucial for ensuring data integrity, consistency, and for enabling powerful querying and manipulation capabilities.
 
 ## Core concepts
 
 ### Types
 
-At the heart of GraphQL SDL are **types**. Types define the shape of your data. You can define custom object types that represent the entities in your document. For example, in a `ToDoList` document, you might have a `ToDoListState` type and a `ToDoItem` type.
+At the heart of GraphQL SDL are **types**. Types define the shape of your data. You can define custom object types that represent the entities in your document. For example, in a `TodoList` document, you might have a `TodoListState` type and a `TodoItem` type.
 
-- **`ToDoListState`**: This could be the root type representing the overall state of the to-do list. It might contain a list of `ToDoItem` objects.
-- **`ToDoItem`**: This type would represent an individual to-do item, with properties like an `id`, `text` (the task description), and `checked` (a boolean indicating if the task is completed).
+- **`TodoListState`**: This could be the root type representing the overall state of the to-do list. It might contain a list of `TodoItem` objects.
+- **`TodoItem`**: This type would represent an individual to-do item, with properties like an `id`, `text` (the task description), and `checked` (a boolean indicating if the task is completed).
 
 ### Fields
 
-Each type has **fields**, which represent the properties of that type. Each field has a name and a type. For instance, the `ToDoItem` type would have an `id` field of type `ID!`, a `text` field of type `String!`, and a `checked` field of type `Boolean!`.
+Each type has **fields**, which represent the properties of that type. Each field has a name and a type. For instance, the `TodoItem` type would have an `id` field of type `OID!`, a `text` field of type `String!`, and a `checked` field of type `Boolean!`.
 
 ### Scalars
 
@@ -27,32 +27,61 @@ GraphQL has a set of built-in **scalar types**:
 
 In addition to these standard types, the Powerhouse Document-Engineering system introduces custom scalars that are linked to reusable front-end components. These scalars are tailored for the web3 ecosystem and will be explored in the Component Library section of the documentation.
 
+:::tip Custom Scalar: OID
+Powerhouse provides the `OID` (Object ID) scalar type, which is a custom scalar specifically designed for unique identifiers in document models. It provides automatic ID generation capabilities when used with the `generateId()` function from the document-model core library.
+:::
+
 ### Lists and non-null
 
 You can modify types using lists and non-null indicators:
 
-- **Lists**: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[ToDoItem!]!`. This means the field `items` in `ToDoListState` will be a list of `ToDoItem` objects.
-- **Non-Null**: To indicate that a field cannot be null, you add an exclamation mark `!` after the type name, e.g., `String!`. This means that the `text` field of a `ToDoItem` must always have a value. The outer `!` in `[ToDoItem!]!` means the list itself cannot be null (it must be at least an empty list), and the inner `!` on `ToDoItem!` means that every item within that list must also be non-null.
+- **Lists**: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[TodoItem!]!`. This means the field `items` in `TodoListState` will be a list of `TodoItem` objects.
+- **Non-Null**: To indicate that a field cannot be null, you add an exclamation mark `!` after the type name, e.g., `String!`. This means that the `text` field of a `TodoItem` must always have a value. The outer `!` in `[TodoItem!]!` means the list itself cannot be null (it must be at least an empty list), and the inner `!` on `TodoItem!` means that every item within that list must also be non-null.
+
+## Example: TodoList state schema
 
-## Example: ToDoList state schema
+Let's revisit the `TodoList` example from the "Define the TodoList document specification" tutorial in Get Started.
 
-Let's revisit the `ToDoList` example from the "Define the ToDoList document specification" tutorial.
-Only this time, we'll also add a 'Stats' type. Since we want to keep track of the number of completed To-Do's.
+### Basic schema (matching Get Started tutorial)
+
+This is the same schema you built in the Get Started tutorial:
 
 ```graphql
-# The state of our ToDoList
-type ToDoListState {
-  items: [ToDoItem!]!
+# The state of our TodoList
+type TodoListState {
+  items: [TodoItem!]!
 }
 
 # A single to-do item
-type ToDoItem {
-  id: ID!
+type TodoItem {
+  id: OID!
   text: String!
   checked: Boolean!
 }
-# The statistics on our to-do's
-type ToDoListStats {
+```
+
+### Advanced schema (with statistics tracking)
+
+:::info Advanced Feature
+In this Mastery Track, we'll extend the basic schema with a `stats` field to demonstrate how you can add computed statistics to your document model. This is an **optional enhancement** that builds on the foundation from Get Started.
+:::
+
+```graphql
+# The state of our TodoList (advanced version with stats)
+type TodoListState {
+  items: [TodoItem!]!
+  stats: TodoListStats!
+}
+
+# A single to-do item
+type TodoItem {
+  id: OID!
+  text: String!
+  checked: Boolean!
+}
+
+# The statistics on our to-do's (advanced feature)
+type TodoListStats {
   total: Int!
   checked: Int!
   unchecked: Int!
@@ -61,18 +90,19 @@ type ToDoListStats {
 
 ### Breakdown:
 
-- **`ToDoListState` type**:
-  - `items: [ToDoItem!]!`: This field defines that our `ToDoListState` contains a list called `items`.
-    - `[ToDoItem!]`: This signifies that `items` is a list of `ToDoItem` objects.
-    - `ToDoItem!`: The `!` after `ToDoItem` means that no item in the list can be null. Each entry must be a valid `ToDoItem`.
-    - The final `!` after `[ToDoItem!]` means that the `items` list itself cannot be null. It can be an empty list `[]`, but it cannot be absent.
+- **`TodoListState` type**:
+  - `items: [TodoItem!]!`: This field defines that our `TodoListState` contains a list called `items`.
+    - `[TodoItem!]`: This signifies that `items` is a list of `TodoItem` objects.
+    - `TodoItem!`: The `!` after `TodoItem` means that no item in the list can be null. Each entry must be a valid `TodoItem`.
+    - The final `!` after `[TodoItem!]` means that the `items` list itself cannot be null. It can be an empty list `[]`, but it cannot be absent.
+  - `stats: TodoListStats!` *(advanced)*: Holds aggregated statistics about the to-do items.
 
-- **`ToDoItem` type**:
-  - `id: ID!`: Each `ToDoItem` has a unique identifier that cannot be null. This is crucial for referencing specific items, for example, when updating or deleting them.
+- **`TodoItem` type**:
+  - `id: OID!`: Each `TodoItem` has a unique identifier using Powerhouse's custom `OID` scalar. This is crucial for referencing specific items, for example, when updating or deleting them.
   - `text: String!`: The textual description of the to-do item. It cannot be null, ensuring every to-do has a description.
   - `checked: Boolean!`: Indicates whether the to-do item is completed. It defaults to a boolean value (true or false) and cannot be null.
 
-- **`ToDoListStats` type**: This type holds the summary statistics for the to-do list.
+- **`TodoListStats` type** *(advanced)*: This type holds the summary statistics for the to-do list.
   - `total: Int!`: The total count of all to-do items. This field must be an integer and cannot be null.
   - `checked: Int!`: The number of to-do items that are marked as completed. This must be an integer and cannot be null.
   - `unchecked: Int!`: The number of to-do items that are still pending. This also must be an integer and cannot be null.
@@ -83,17 +113,17 @@ type ToDoListStats {
 2.  **Clarity and Explicitness**: Name your types and fields clearly and descriptively. This makes the schema easier to understand and maintain.
 3.  **Use Non-Null Wisely**: Enforce data integrity by using non-null (`!`) for fields that must always have a value. However, be mindful not to over-constrain if a field can genuinely be optional.
 4.  **Normalize vs. Denormalize**:
-    - **Normalization**: Similar to relational databases, you can normalize your data by having distinct types and linking them via IDs. This can reduce data redundancy. For example, if you had `User` and `ToDoItem` and wanted to assign tasks, you might have an `assigneeId` field in `ToDoItem` that links to a `User`'s `id`.
-    - **Denormalization**: Sometimes, for performance or simplicity, you might embed data directly. For instance, if user information associated with a to-do item was very simple and only used in that context, you might embed user fields directly in `ToDoItem`.
+    - **Normalization**: Similar to relational databases, you can normalize your data by having distinct types and linking them via IDs. This can reduce data redundancy. For example, if you had `User` and `TodoItem` and wanted to assign tasks, you might have an `assigneeId` field in `TodoItem` that links to a `User`'s `id`.
+    - **Denormalization**: Sometimes, for performance or simplicity, you might embed data directly. For instance, if user information associated with a to-do item was very simple and only used in that context, you might embed user fields directly in `TodoItem`.
     - The choice depends on your specific use case, query patterns, and how data is updated.
-5.  **Consider Future Needs**: While you shouldn't over-engineer, think a little about potential future enhancements. For example, adding a `createdAt: String` or `dueDate: String` field to `ToDoItem` might be useful later.
-6.  **Root State Type**: It's a common pattern to have a single root type for your document state (e.g., `ToDoListState`). This provides a clear entry point for accessing all document data.
+5.  **Consider Future Needs**: While you shouldn't over-engineer, think a little about potential future enhancements. For example, adding a `createdAt: String` or `dueDate: String` field to `TodoItem` might be useful later.
+6.  **Root State Type**: It's a common pattern to have a single root type for your document state (e.g., `TodoListState`). This provides a clear entry point for accessing all document data.
 
 By carefully defining your state schema, you lay a solid foundation for your Powerhouse document model, making it robust, maintainable, and easy to work with. The schema dictates not only how data is stored but also how it can be queried and mutated through operations, which will be covered in the next section.
 
 ## Practical implementation: defining the state schema in Connect
 
-Now that you understand the concepts behind the state schema, let's put it into practice. This section will guide you through creating a document model specification for the advanced ToDoList example discussed above.
+Now that you understand the concepts behind the state schema, let's put it into practice. This section will guide you through creating a document model specification for the TodoList example discussed above.
 
 <details>
 <summary>Tutorial: The state schema specification</summary>
@@ -110,28 +140,29 @@ Now that you understand the concepts behind the state schema, let's put it into
     - At the bottom of the page in the 'New Document' section, click the `DocumentModel` button to create a new document model specification.
 
 2.  **Define Document Metadata**:
-    - **Name**: Give your document model a descriptive name, for example, `ToDoList`. **Pay close attention to capitalization, as it influences our code.**
-    - **Document Type**: In the 'Document Type' field, enter a unique identifier for this document type: `powerhouse/todolist`.
+    - **Name**: Give your document model a descriptive name: `TodoList`. **Pay close attention to capitalization, as it influences our code generation.**
+    - **Document Type**: In the 'Document Type' field, enter a unique identifier for this document type: `powerhouse/todo-list`.
 
 3.  **Specify the State Schema**:
     - In the code editor provided, you'll see a template for a GraphQL schema.
-    - Replace the entire content of the editor with the advanced `ToDoList` schema we've designed in this chapter:
+    - Replace the entire content of the editor with the advanced `TodoList` schema we've designed in this chapter:
 
     ```graphql
-    # The state of our ToDoList
-    type ToDoListState {
-      items: [ToDoItem!]!
-      stats: ToDoListStats!
+    # The state of our TodoList (advanced version with stats)
+    type TodoListState {
+      items: [TodoItem!]!
+      stats: TodoListStats!
     }
 
     # A single to-do item
-    type ToDoItem {
-      id: ID!
+    type TodoItem {
+      id: OID!
       text: String!
       checked: Boolean!
     }
-    # The statistics on our to-do's
-    type ToDoListStats {
+    
+    # The statistics on our to-do's (advanced feature)
+    type TodoListStats {
       total: Int!
       checked: Int!
       unchecked: Int!
@@ -140,12 +171,12 @@ Now that you understand the concepts behind the state schema, let's put it into
 
 4.  **Sync Schema and View Initial State**:
     - After pasting the schema, click the **'Sync with schema'** button.
-    - This action processes your schema and generates an initial JSON state for your document model based on the `ToDoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly.
+    - This action processes your schema and generates an initial JSON state for your document model based on the `TodoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly.
 
     For now, you can ignore the "Modules & Operations" section. We will define and implement the operations that modify this state in the upcoming sections of this Mastery Track.
 
-By completing these steps, you have successfully specified the data structure for the advanced ToDoList document model. The next step is to define the operations that will allow users to interact with and change this state.
+By completing these steps, you have successfully specified the data structure for the advanced TodoList document model. The next step is to define the operations that will allow users to interact with and change this state.
 
 </details>
 
-For a complete, working example, you can always have a look at the [Example ToDoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
+For a complete, working example, you can always have a look at the [Example TodoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/03-SpecifyDocumentOperations.md

@@ -6,7 +6,7 @@ In the previous section, we defined the state schema for our document model. Now
 
 In Powerhouse, document models adhere to event sourcing principles. This means that every change to a document's state is the result of a sequence of operations (or events). Instead of directly mutating the state, you define specific, named operations that describe the intended change.
 
-For example, in our `To-do List` document model, operations might include:
+For example, in our `TodoList` document model, operations might include:
 
 - `ADD_TODO_ITEM`: To add a new task.
 - `UPDATE_TODO_ITEM`: To modify an existing task (e.g., change its text or mark it as completed).
@@ -16,35 +16,38 @@ Each operation acts as a command that, when applied, transitions the document fr
 
 ## Connecting operations to the schema
 
-In the "Define To-do List Document Model" chapter in the "Get Started" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
+In the "Define TodoList Document Model" chapter in the "Get Started" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
 
 ```graphql
 # Defines a GraphQL input type for adding a new to-do item
 input AddTodoItemInput {
-  id: ID!
   text: String!
 }
 
 # Defines a GraphQL input type for updating a to-do item
 input UpdateTodoItemInput {
-  id: ID!
+  id: OID!
   text: String
   checked: Boolean
 }
 
 # Defines a GraphQL input type for deleting a to-do item
 input DeleteTodoItemInput {
-  id: ID!
+  id: OID!
 }
 ```
 
 These `input` types are not just abstract definitions; they are the **specifications for our document operations**.
 
-- **`AddTodoItemInput`** specifies that to execute an `ADD_TODO_ITEM` operation, we need an `id` and `text` for the new item.
+- **`AddTodoItemInput`** specifies that to execute an `ADD_TODO_ITEM` operation, we only need the `text` for the new item. The `id` is automatically generated by the reducer using Powerhouse's `generateId()` function.
 - **`UpdateTodoItemInput`** specifies that for an `UPDATE_TODO_ITEM` operation, we need the `id` of the item to update, and optionally new `text` or a `checked` status.
 - **`DeleteTodoItemInput`** specifies that a `DELETE_TODO_ITEM` operation requires the `id` of the item to be removed.
 
-The Powerhouse Connect application uses these GraphQL input types when you define operations within a module (e.g., the `to_do_list` module with operations `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`).
+:::tip ID Generation
+Notice that `AddTodoItemInput` only requires `text` — not an `id`. This is because the ID is generated automatically in the reducer using `generateId()` from `document-model/core`. This ensures unique, consistent IDs and follows the pattern used in the [todo-demo repository](https://github.com/powerhouse-inc/todo-demo).
+:::
+
+The Powerhouse Connect application uses these GraphQL input types when you define operations within a module (e.g., the `todos` module with operations `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`).
 
 ## Designing effective document operations
 
@@ -56,7 +59,7 @@ Operations should be granular enough to represent distinct user intentions or lo
 
 - **Too coarse:** An operation like `MODIFY_TODOLIST` that takes a whole new list of items would be too broad. It would be hard to track specific changes and could lead to complex reducer logic.
 - **Too fine:** While possible, having separate operations like `SET_TODO_ITEM_TEXT` and `SET_TODO_ITEM_CHECKED_STATUS` might be overly verbose if these are often updated together. `UPDATE_TODO_ITEM` with optional fields offers a good balance.
-- **Just right:** The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `ToDoList` are good examples. They represent clear, atomic changes.
+- **Just right:** The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `TodoList` are good examples. They represent clear, atomic changes.
 
 ### 2. Naming conventions
 
@@ -90,25 +93,25 @@ While not specified in the operation definition itself, remember that the _imple
 
 Specifying your document operations is the bridge between defining your data structure (the state schema) and implementing the logic that changes that data (the reducers).
 
-1.  **You define the state schema** (e.g., `ToDoListState`, `ToDoItem`).
+1.  **You define the state schema** (e.g., `TodoListState`, `TodoItem`).
 2.  **You specify the operations** that can alter this state, along with their required input data (e.g., `ADD_TODO_ITEM` with `AddTodoItemInput`).
 3.  **Next, you will implement reducers** for each specified operation. Each reducer will take the current state and an operation's input, and produce a new state.
 
 The generated code from `ph generate` (as seen in `03-ImplementOperationReducers.md`) will create a structure for your reducers based on the operations you specified in the Connect application (which, in turn, were based on your GraphQL input types).
 
-For example, the `ToDoListToDoListOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
+For example, the `TodoListTodosOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
 
 ```typescript
-import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js";
+import type { TodoListTodosOperations } from "../../gen/todos/operations.js";
 
-export const reducer: ToDoListToDoListOperations = {
-  addTodoItemOperation(state, action, dispatch) {
+export const todoListTodosOperations: TodoListTodosOperations = {
+  addTodoItemOperation(state, action) {
     // Implementation uses action.input which matches AddTodoItemInput
   },
-  updateTodoItemOperation(state, action, dispatch) {
+  updateTodoItemOperation(state, action) {
     // Implementation uses action.input which matches UpdateTodoItemInput
   },
-  deleteTodoItemOperation(state, action, dispatch) {
+  deleteTodoItemOperation(state, action) {
     // Implementation uses action.input which matches DeleteTodoItemInput
   },
 };
@@ -116,16 +119,16 @@ export const reducer: ToDoListToDoListOperations = {
 
 ## Practical implementation: Defining operations in Connect
 
-Now that you understand the theory, let's walk through the practical steps of defining these operations for our `To-do List` document model within the Powerhouse Connect application.
+Now that you understand the theory, let's walk through the practical steps of defining these operations for our `TodoList` document model within the Powerhouse Connect application.
 
 <details>
-<summary>Tutorial: Specifying To-do List operations</summary>
+<summary>Tutorial: Specifying TodoList operations</summary>
 
-Assuming you have already defined the state schema for the `To-do List` as covered in the previous section, follow these steps to add the operations:
+Assuming you have already defined the state schema for the `TodoList` as covered in the previous section, follow these steps to add the operations:
 
 1.  **Create a Module for Operations:**
     Below the schema editor in Connect, find the input field labeled `Add module`. Modules help organize your operations.
-    - Type `to_do_list` into the field and press Enter.
+    - Type `todos` into the field and press Enter.
 
 2.  **Add the `ADD_TODO_ITEM` Operation:**
     A new field, `Add operation`, will appear under your new module.
@@ -135,11 +138,14 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```graphql
     # Defines a GraphQL input type for adding a new to-do item
     input AddTodoItemInput {
-      id: ID!
       text: String!
     }
     ```
 
+    :::info
+    Notice we don't include `id` in the input — the reducer will generate it automatically using `generateId()` from `document-model/core`.
+    :::
+
 3.  **Add the `UPDATE_TODO_ITEM` Operation:**
     - In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
     - Paste the corresponding `input` definition into its editor:
@@ -147,7 +153,7 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```graphql
     # Defines a GraphQL input type for updating a to-do item
     input UpdateTodoItemInput {
-      id: ID!
+      id: OID!
       text: String
       checked: Boolean
     }
@@ -160,7 +166,7 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```graphql
     # Defines a GraphQL input type for deleting a to-do item
     input DeleteTodoItemInput {
-      id: ID!
+      id: OID!
     }
     ```
 

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/04-UseTheDocumentModelGenerator.md

@@ -1,8 +1,8 @@
 # Use the document model generator
 
-In the Powerhouse Document Model development workflow, after specifying your document model's state schema and operations within the Connect application and exporting it as a `.phdm.zip` file, the next crucial step is to translate this specification into a tangible codebase. This is where the Powerhouse Document Model Generator comes into play.
+In the Powerhouse Document Model development workflow, after specifying your document model's state schema and operations within the Connect application and exporting it as a `.phd` file, the next crucial step is to translate this specification into a tangible codebase. This is where the Powerhouse Document Model Generator comes into play.
 
-The Document Model Generator is a powerful command-line tool (`ph generate`) that processes your exported `.phdm.zip` file and scaffolds the necessary directory structure and foundational code for your document model. It automates the creation of boilerplate code, ensuring consistency, type safety, and adherence to Powerhouse conventions, thereby significantly accelerating the development process.
+The Document Model Generator is a powerful command-line tool (`ph generate`) that processes your exported `.phd` file and scaffolds the necessary directory structure and foundational code for your document model. It automates the creation of boilerplate code, ensuring consistency, type safety, and adherence to Powerhouse conventions, thereby significantly accelerating the development process.
 
 This document provides a deep dive into using the Document Model Generator, understanding its output, and appreciating its role in the broader context of document model creation.
 
@@ -11,20 +11,20 @@ This document provides a deep dive into using the Document Model Generator, unde
 Before you can use the Document Model Generator, ensure you have the following:
 
 1.  **Powerhouse CLI (`ph-cmd`) Installed:** The generator is part of the Powerhouse CLI. If you haven't installed it, refer to the [Builder Tools documentation](/academy/MasteryTrack/BuilderEnvironment/BuilderTools#installing-the-powerhouse-cli).
-2.  **Document Model Specification File (`.phdm.zip`):** You must have already defined your document model in Connect and exported it. This file (e.g., `YourModelName.phdm.zip`) contains the GraphQL schema for your document's state and operations. This process is typically covered in a preceding step, such as "Define [YourModelName] Document Model."
+2.  **Document Model Specification File (`.phd`):** You must have already defined your document model in Connect and exported it. This file (e.g., `TodoList.phd`) contains the GraphQL schema for your document's state and operations. This process is typically covered in a preceding step, such as "Define TodoList Document Model."
 
 ## The command
 
 The core command to invoke the Document Model Generator is:
 
 ```bash
-ph generate <YourModelName.phdm.zip>
+ph generate <YourModelName.phd>
 ```
 
-Replace `<YourModelName.phdm.zip>` with the actual filename of your exported document model specification. For instance, if your exported file is named `Invoice.phdm.zip`, the command would be:
+Replace `<YourModelName.phd>` with the actual filename of your exported document model specification. For instance, if your exported file is named `TodoList.phd`, the command would be:
 
 ```bash
-ph generate Invoice.phdm.zip
+ph generate TodoList.phd
 ```
 
 When executed, this command reads and parses the specification file and generates a set of files and directories within your Powerhouse project.
@@ -34,12 +34,12 @@ When executed, this command reads and parses the specification file and generate
 Running `ph generate` triggers a series of actions that lay the groundwork for your document model's implementation. Let's explore the typical output structure and the significance of each generated component.
 
 The generator creates a new directory specific to your document model, usually located at:
-`document-models/<YourModelName>/`
+`document-models/<your-model-name>/`
 
-For example, using `Invoice.phdm.zip` would result in a directory structure under `document-models/invoice/`. Inside this directory, you will find:
+For example, using `TodoList.phd` would result in a directory structure under `document-models/todo-list/`. Inside this directory, you will find:
 
-1.  **`spec.json` (or similar JSON representation):**
-    - **Purpose:** This file is a JSON representation of your document model specification, derived directly from the `.phdm.zip` file. It contains the parsed schema, operation definitions, document type, and other metadata.
+1.  **`todo-list.json` (or similar JSON representation):**
+    - **Purpose:** This file is a JSON representation of your document model specification, derived directly from the `.phd` file. It contains the parsed schema, operation definitions, document type, and other metadata.
     - **Significance:** It serves as the canonical, machine-readable definition of your model within the project, which other tools or processes might reference.
 
 2.  **`schema.graphql`:**
@@ -50,12 +50,12 @@ For example, using `Invoice.phdm.zip` would result in a directory structure unde
     This directory is pivotal as it houses all the code automatically generated by the tool. **You should generally avoid manually editing files within the `gen/` directory**, as they will be overwritten if you regenerate the model.
     Key files within `gen/` include:
     - **`types.ts`:**
-      - **Purpose:** Contains TypeScript interfaces and type definitions derived from your GraphQL schema. This includes types for your document's state (e.g., `InvoiceState`), any complex types used within the state (e.g., `LineItem`), and types for the inputs of each defined operation (e.g., `AddLineItemInput`).
+      - **Purpose:** Contains TypeScript interfaces and type definitions derived from your GraphQL schema. This includes types for your document's state (e.g., `TodoListState`), any complex types used within the state (e.g., `TodoItem`), and types for the inputs of each defined operation (e.g., `AddTodoItemInput`).
       - **Significance:** This is the cornerstone of type safety in your document model implementation. By using these generated types, you ensure that your reducer logic and any client-side interactions adhere to the defined data structures, catching errors at compile-time rather than runtime.
 
-    - **`operations.ts` (or `creators.ts`, `actions.ts`):**
+    - **`creators.ts` (or `actions.ts`):**
       - **Purpose:** This file exports "action creator" functions for each operation defined in your schema. These functions take the input parameters for an operation and return a correctly structured action object that can be processed by the reducer system.
-      - **Significance:** Action creators simplify the process of creating and dispatching operations, reduce the likelihood of errors in action formatting, and improve code readability. For example, instead of manually constructing an action object like `{ type: "ADD_LINE_ITEM", input: { ... } }`, you'd use a function like `creators.addLineItem({ ... })`.
+      - **Significance:** Action creators simplify the process of creating and dispatching operations, reduce the likelihood of errors in action formatting, and improve code readability. For example, instead of manually constructing an action object like `{ type: "ADD_TODO_ITEM", input: { ... } }`, you'd use a function like `addTodoItem({ text: 'Buy groceries' })`.
 
     - **`utils.ts`:**
       - **Purpose:** Often includes utility functions related to your document model. A common utility is a function to create an empty or initial instance of your document (e.g., `utils.createDocument()`). This is based on the default values and structure defined in your state schema.
@@ -68,14 +68,11 @@ For example, using `Invoice.phdm.zip` would result in a directory structure unde
 4.  **The `src/` Directory (Source Code for Your Implementation):**
     This directory is where you, the developer, will write the custom logic for your document model. Unlike the `gen/` directory, files here are meant to be manually edited.
     - **`reducers/`:**
-      - **`your-model-name.ts` (e.g., `invoice.ts`):** This is the most important file you'll work with after generation. It's where you implement the **reducer functions** for each operation. The generator usually creates a skeleton file with function stubs for each operation, which you then fill in with the actual state transition logic.
+      - **`todos.ts`:** This is the most important file you'll work with after generation. It's where you implement the **reducer functions** for each operation. The generator usually creates a skeleton file with function stubs for each operation, which you then fill in with the actual state transition logic.
       - **Significance:** This is the heart of your document model's behavior, defining how the state changes in response to each operation. The next step in the Mastery Track will typically focus on implementing these reducers.
-    - **`reducers/tests/`:**
-      - **`your-model-name.test.ts` (e.g., `invoice.test.ts`):** A placeholder or basic test file is often generated here, encouraging you to write unit tests for your reducer logic.
+    - **`tests/`:**
+      - **`todos.test.ts`:** A placeholder or basic test file is often generated here, encouraging you to write unit tests for your reducer logic.
       - **Significance:** Emphasizes the importance of testing your document model's core logic to ensure correctness and reliability.
-    - **`utils/` (optional):**
-      - **Purpose:** You can create this directory for any custom utility functions specific to your document model's implementation that don't fit directly into the reducers.
-      - **Significance:** Helps in organizing shared logic or complex computations that might be used across multiple reducers or other parts of your model's ecosystem.
 
 ## Benefits of using the document model generator
 
@@ -88,39 +85,39 @@ Leveraging the `ph generate` command offers numerous advantages:
 5.  **Alignment with Powerhouse Ecosystem:** The generated code is designed to integrate seamlessly with other parts of the Powerhouse ecosystem, such as the reducer execution engine and UI components.
 6.  **Single Source of Truth:** Ensures that your codebase (especially types and action creators) stays synchronized with the document model specification defined in Connect. If the specification changes, regenerating the model will update these components accordingly.
 
-## Practical implementation: Generating the `To-do List` model
+## Practical implementation: Generating the `TodoList` model
 
-Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `To-do List` example.
+Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `TodoList` example.
 
 <details>
-<summary>Tutorial: Generating the `To-do List` document model</summary>
+<summary>Tutorial: Generating the TodoList document model</summary>
 
-This tutorial assumes you have completed the previous steps in this Mastery Track, where you defined the state schema and operations for the `To-do List` model in Connect and exported it.
+This tutorial assumes you have completed the previous steps in this Mastery Track, where you defined the state schema and operations for the `TodoList` model in Connect and exported it.
 
 ### Prerequisites
 
-- **`ToDoList.phdm.zip` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
+- **`TodoList.phd` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
 
 ### Steps
 
 1.  **Place the Specification File in Your Project**:
     - Navigate to the root directory of your Powerhouse project.
-    - Move or copy your `ToDoList.phdm.zip` file into this directory.
+    - Move or copy your `TodoList.phd` file into this directory.
 
 2.  **Run the Generator Command**:
     - Open your terminal in the root directory of your Powerhouse project.
     - Execute the `ph generate` command, pointing to your specification file:
 
     ```bash
-    ph generate ToDoList.phdm.zip
+    ph generate TodoList.phd
     ```
 
 3.  **Explore the Generated Files**:
-    - After the command completes successfully, you will find a new directory: `document-models/to-do-list/`.
+    - After the command completes successfully, you will find a new directory: `document-models/todo-list/`.
     - Take a moment to explore its contents, which will match the structure described earlier in this document:
-      - `spec.json` and `schema.graphql`: The definition of your model.
-      - `gen/`: Type-safe, generated code including `types.ts`, `operations.ts`, etc.
-      - `src/`: The skeleton for your implementation, most importantly `src/reducers/to-do-list.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
+      - `todo-list.json` and `schema.graphql`: The definition of your model.
+      - `gen/`: Type-safe, generated code including `types.ts`, `creators.ts`, etc.
+      - `src/`: The skeleton for your implementation, most importantly `src/reducers/todos.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
 
 With these files generated, you have successfully scaffolded your document model. The project is now set up for you to implement the core business logic.
 
@@ -128,7 +125,7 @@ With these files generated, you have successfully scaffolded your document model
 
 ## Next steps
 
-Once the Document Model Generator has successfully scaffolded your project, the immediate next step is to implement the logic for each operation within the generated reducer files (e.g., `document-models/YourModelName/src/reducers/your-model-name.ts`). This involves taking the current state and the action input, and returning the new state of the document.
+Once the Document Model Generator has successfully scaffolded your project, the immediate next step is to implement the logic for each operation within the generated reducer files (e.g., `document-models/todo-list/src/reducers/todos.ts`). This involves taking the current state and the action input, and returning the new state of the document.
 
 Subsequently, you will write unit tests for these reducers to ensure they behave as expected under various conditions. This iterative process of defining, generating, implementing, and testing forms the core loop of document model development in Powerhouse.