@powerhousedao/academy 5.0.0-staging.2 → 5.0.0-staging.21

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md

@@ -1,20 +1,21 @@
 # What is a document model?
 
 :::tip
-This chapter on **Document Model Creation** will help you with an in depth practicial understanding while building an **advanced to-do list** document model. 
+This chapter on **Document Model Creation** will help you with an in depth practicial understanding while building an **advanced to-do list** document model.
 Although not required, if you have completed the 'Get Started' tutorial you will revisit familiar topics and can update your existing document model.
 :::
 
 :::info **Definition: What is a Document Model?**
 A Document Model is a programmable document structure that defines how data is stored, changed, and interpreted in a decentralized system. It acts like a living blueprint—capturing state, tracking changes, and enabling interaction through defined operations.
 
-For instance, an invoice document model might define fields like *issuer*, *lineItems*, and *status*, with operations such as *AddLineItem* and *MarkAsPaid*.
+For instance, an invoice document model might define fields like _issuer_, _lineItems_, and _status_, with operations such as _AddLineItem_ and _MarkAsPaid_.
 :::
 
-A Document Model can be understood as: 
-- A structured software framework that represents and **manages business logic** within a digital environment. 
-- A sophisticated template that **encapsulates the essential aspects of a digital process or a set of data**. 
-- A blueprints that define how data is **captured, manipulated, and visualised** within a system. 
+A Document Model can be understood as:
+
+- A structured software framework that represents and **manages business logic** within a digital environment.
+- A sophisticated template that **encapsulates the essential aspects of a digital process or a set of data**.
+- A blueprints that define how data is **captured, manipulated, and visualised** within a system.
 - A **standardized way to store, modify, and query data** in scalable, decentralized applications.
 
 ### **How does a document model function?**
@@ -27,7 +28,7 @@ Each document model consists of three key components:
 2. **Document Operations** – Defines how the document can be modified.
 3. **Event History** – Maintains an append-only log of changes.
 
-Document models leverage **event sourcing, CQRS (Command Query Responsibility Segregation), and an append-only architecture** to ensure immutability, auditability, and scalability. 
+Document models leverage **event sourcing, CQRS (Command Query Responsibility Segregation), and an append-only architecture** to ensure immutability, auditability, and scalability.
 
 ---
 
@@ -43,19 +44,19 @@ Example of a **GraphQL-like state schema** for an invoice document:
 
 ```graphql
 type InvoiceState {
-  id: OID!                # Unique identifier for the invoice
-  issuer: OID!            # Reference to the issuing entity
-  recipient: OID!         # Reference to the recipient entity
-  status: String          # (value: "DRAFT") # Invoice status
-  dueDate: DateTime       # Payment due date
+  id: OID! # Unique identifier for the invoice
+  issuer: OID! # Reference to the issuing entity
+  recipient: OID! # Reference to the recipient entity
+  status: String # (value: "DRAFT") # Invoice status
+  dueDate: DateTime # Payment due date
   lineItems: [LineItem!]! # List of line items
-  totalAmount: Currency   # Computed field for total invoice value
+  totalAmount: Currency # Computed field for total invoice value
 }
 
 type LineItem {
   id: OID!
   description: String
-  quantity: Int 
+  quantity: Int
   unitPrice: Currency
 }
 ```
@@ -80,7 +81,7 @@ Example operations for modifying an invoice:
 input AddLineItemInput {
   invoiceId: OID!
   description: String
-  quantity: Int 
+  quantity: Int
   unitPrice: Currency
 }
 
@@ -94,7 +95,7 @@ input MarkAsPaidInput {
 }
 ```
 
-Each operation **modifies the document state** without altering past data.    
+Each operation **modifies the document state** without altering past data.  
 Instead, a new event is appended to the document history.
 
 ---
@@ -109,7 +110,7 @@ Every operation applied to a document is **stored as an event** in an append-onl
 [
   { "timestamp": 1700000001, "operation": "CREATE_INVOICE", "data": { "id": "inv-001", "issuer": "company-123", "recipient": "client-456" } },
   { "timestamp": 1700000100, "operation": "ADD_LINE_ITEM", "data": { "description": "Software Development", "quantity": 10, "unitPrice": 100 } },
-  { "timestamp": 1700000200, "operation": "MARK_AS_PAID", "data": {} 
+  { "timestamp": 1700000200, "operation": "MARK_AS_PAID", "data": {}
 ```
 
 ### **Event history benefits:**
@@ -136,7 +137,11 @@ Document models in Powerhouse rely on **event-driven architecture, event sourcin
 ```json
 {
   "operation": "CREATE_INVOICE",
-  "data": { "id": "inv-001", "issuer": "company-123", "recipient": "client-456" }
+  "data": {
+    "id": "inv-001",
+    "issuer": "company-123",
+    "recipient": "client-456"
+  }
 }
 ```
 
@@ -155,7 +160,11 @@ Adding a line item:
 ```json
 {
   "operation": "ADD_LINE_ITEM",
-  "data": { "description": "Software Development", "quantity": 10, "unitPrice": 100 }
+  "data": {
+    "description": "Software Development",
+    "quantity": 10,
+    "unitPrice": 100
+  }
 }
 ```
 
@@ -198,8 +207,8 @@ Document Models offer a range of features that can be leveraged to create sophis
 - **Collaboration**: Empower decentralized teams to build, modify, and share documents asynchronously.
 - **Extensibility**: Add new fields, operations, and integrations over time without rewriting logic.
 
-Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data. 
+Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data.
 
 ### Up next: How to build a document model
 
-In the next chapters, we'll teach you how to build a To-do List document model while explaining all of the theory that is involved.
+In the next chapters, we'll teach you how to build a To-do List document model while explaining all of the theory that is involved.

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

@@ -5,29 +5,34 @@ The state schema is the backbone of your document model. It defines the structur
 ## 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.
 
-*   **`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!`.
 
 ### Scalars
+
 GraphQL has a set of built-in **scalar types**:
-*   `String`: A UTF‐8 character sequence.
-*   `Int`: A signed 32‐bit integer.
-*   `Float`: A signed double-precision floating-point value.
-*   `Boolean`: `true` or `false`.
-*   `ID`: A unique identifier, often used as a key for a field. It is serialized in the same way as a String; however, it is not intended to be human-readable.
+
+- `String`: A UTF‐8 character sequence.
+- `Int`: A signed 32‐bit integer.
+- `Float`: A signed double-precision floating-point value.
+- `Boolean`: `true` or `false`.
+- `ID`: A unique identifier, often used as a key for a field. It is serialized in the same way as a String; however, it is not intended to be human-readable.
 
 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.
 
 ### 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
 
@@ -56,21 +61,21 @@ 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.
 
-*   **`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.
-    *   `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.
+- **`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.
+  - `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.
-    *   `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.
+- **`ToDoListStats` type**: 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.
 
 ## Best practices for designing your state schema
 
@@ -78,9 +83,9 @@ 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`.
-    *   The choice depends on your specific use case, query patterns, and how data is updated.
+    - **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.
 
@@ -91,26 +96,26 @@ By carefully defining your state schema, you lay a solid foundation for your Pow
 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.
 
 <details>
-<summary>Tutorial: The state schema specification</summary> 
+<summary>Tutorial: The state schema specification</summary>
 
 ### Prerequisites
 
--   You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](../../GetStarted/CreateNewPowerhouseProject) tutorial.
--   Connect Studio is running. If not, navigate to your project directory in the terminal and run `ph connect`.
+- You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](../../GetStarted/CreateNewPowerhouseProject) tutorial.
+- Connect Studio is running. If not, navigate to your project directory in the terminal and run `ph connect`.
 
 ### Steps
 
 1.  **Create a New Document Model**:
-    -   With Connect Studio open in your browser, navigate into your local drive.
-    -   At the bottom of the page in the 'New Document' section, click the `DocumentModel` button to create a new document model specification.
+    - With Connect Studio open in your browser, navigate into your local drive.
+    - 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, 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`.
 
 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:
+    - 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:
 
     ```graphql
     # The state of our ToDoList
@@ -134,8 +139,8 @@ 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.
+    - 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.
 
     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.
 
@@ -144,4 +149,3 @@ By completing these steps, you have successfully specified the data structure fo
 </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.
-

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

@@ -8,9 +8,9 @@ In Powerhouse, document models adhere to event sourcing principles. This means t
 
 For example, in our `To-do List` 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).
-*   `DELETE_TODO_ITEM`: To remove a task.
+- `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).
+- `DELETE_TODO_ITEM`: To remove a task.
 
 Each operation acts as a command that, when applied, transitions the document from one state to the next. The complete history of these operations defines the document's journey to its current state.
 
@@ -40,9 +40,9 @@ input DeleteTodoItemInput {
 
 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.
-*   **`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.
+- **`AddTodoItemInput`** specifies that to execute an `ADD_TODO_ITEM` operation, we need an `id` and `text` for the new item.
+- **`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`).
 
@@ -51,36 +51,40 @@ The Powerhouse Connect application uses these GraphQL input types when you defin
 Careful design of your document operations is crucial for a robust and maintainable document model. Here are some key considerations:
 
 ### 1. Granularity
+
 Operations should be granular enough to represent distinct user intentions or logical changes.
 
-*   **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.
+- **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.
 
 ### 2. Naming conventions
+
 Clear and consistent naming makes your operations understandable. A common convention is `VERB_NOUN` or `VERB_NOUN_SUBJECT`.
 
-*   Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`.
-*   In our case: `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`.
+- Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`.
+- In our case: `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`.
 
 The name you provide in the Connect UI (e.g., `ADD_TODO_ITEM`) directly corresponds to the operation type that will be recorded and that your reducers will handle.
 
 ### 3. Input types (payloads)
+
 The input type for an operation (its payload) should contain all the necessary information to perform that operation, and nothing more.
 
-*   **Completeness:** If an operation needs a user ID to authorize a change, include it in the input.
-*   **Conciseness:** Avoid including data that isn't directly used by the operation.
-*   **Clarity:** Use descriptive field names within your input types. `action.input.text` is clearer than `action.input.t`.
+- **Completeness:** If an operation needs a user ID to authorize a change, include it in the input.
+- **Conciseness:** Avoid including data that isn't directly used by the operation.
+- **Clarity:** Use descriptive field names within your input types. `action.input.text` is clearer than `action.input.t`.
 
 The GraphQL `input` types we defined earlier (`AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`) serve precisely this purpose. They ensure that whoever triggers an operation provides the correct data in the correct format.
 
 ### 4. Immutability and pure functions
-While not specified in the operation definition itself, remember that the *implementation* of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions.
+
+While not specified in the operation definition itself, remember that the _implementation_ of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions.
 
 ## Role in event sourcing and CQRS
 
-*   **Events:** Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved.
-*   **Commands:** Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated.
+- **Events:** Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved.
+- **Commands:** Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated.
 
 ## From specification to implementation
 
@@ -95,7 +99,7 @@ The generated code from `ph generate` (as seen in `03-ImplementOperationReducers
 For example, the `ToDoListToDoListOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
 
 ```typescript
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js";
 
 export const reducer: ToDoListToDoListOperations = {
   addTodoItemOperation(state, action, dispatch) {
@@ -121,12 +125,12 @@ Assuming you have already defined the state schema for the `To-do List` as cover
 
 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 `to_do_list` into the field and press Enter.
 
 2.  **Add the `ADD_TODO_ITEM` Operation:**
     A new field, `Add operation`, will appear under your new module.
-    *   Type `ADD_TODO_ITEM` into this field and press Enter.
-    *   An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
+    - Type `ADD_TODO_ITEM` into this field and press Enter.
+    - An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
 
     ```graphql
     # Defines a GraphQL input type for adding a new to-do item
@@ -137,8 +141,8 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```
 
 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:
+    - In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
+    - Paste the corresponding `input` definition into its editor:
 
     ```graphql
     # Defines a GraphQL input type for updating a to-do item
@@ -150,8 +154,8 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```
 
 4.  **Add the `DELETE_TODO_ITEM` Operation:**
-    *   Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
-    *   Paste its `input` definition:
+    - Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
+    - Paste its `input` definition:
 
     ```graphql
     # Defines a GraphQL input type for deleting a to-do item

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

@@ -39,45 +39,43 @@ The generator creates a new directory specific to your document model, usually l
 For example, using `Invoice.phdm.zip` would result in a directory structure under `document-models/invoice/`. 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.
-    *   **Significance:** It serves as the canonical, machine-readable definition of your model within the project, which other tools or processes might reference.
+    - **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.
+    - **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`:**
-    *   **Purpose:** This file contains the raw GraphQL Schema Definition Language (SDL) for both the state and operations of your document model, exactly as you defined it in Connect.
-    *   **Significance:** Provides a human-readable reference of the schema and can be useful for quick checks or for tools that might directly consume GraphQL SDL.
+    - **Purpose:** This file contains the raw GraphQL Schema Definition Language (SDL) for both the state and operations of your document model, exactly as you defined it in Connect.
+    - **Significance:** Provides a human-readable reference of the schema and can be useful for quick checks or for tools that might directly consume GraphQL SDL.
 
 3.  **The `gen/` Directory (Generated Code):**
     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`).
+      - **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.
 
-    *   **`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`).
-        *   **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`):**
+      - **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({ ... })`.
 
-    *   **`operations.ts` (or `creators.ts`, `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({ ... })`.
+    - **`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.
+      - **Significance:** Provides convenient helpers for common tasks, particularly for initializing new documents in tests or application code.
 
-    *   **`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.
-        *   **Significance:** Provides convenient helpers for common tasks, particularly for initializing new documents in tests or application code.
-
-    *   **`reducer.ts` (or similar, defining the reducer interface/skeleton):**
-        *   **Purpose:** This file might contain a TypeScript interface or a skeleton object that your actual reducer implementation (in the `src/` directory) will need to conform to. It outlines the expected shape of the reducer map, ensuring that you provide an implementation for every defined operation.
-        *   **Significance:** Guides the implementation of your reducers and helps maintain consistency, ensuring that all defined operations are accounted for.
+    - **`reducer.ts` (or similar, defining the reducer interface/skeleton):**
+      - **Purpose:** This file might contain a TypeScript interface or a skeleton object that your actual reducer implementation (in the `src/` directory) will need to conform to. It outlines the expected shape of the reducer map, ensuring that you provide an implementation for every defined operation.
+      - **Significance:** Guides the implementation of your reducers and helps maintain consistency, ensuring that all defined operations are accounted for.
 
 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.
-        *   **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.
-        *   **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.
+    - **`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.
+      - **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.
+      - **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
 
@@ -101,27 +99,28 @@ This tutorial assumes you have completed the previous steps in this Mastery Trac
 
 ### 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.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.
 
 ### 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.
+    - Navigate to the root directory of your Powerhouse project.
+    - Move or copy your `ToDoList.phdm.zip` 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:
+    - 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
     ```
 
 3.  **Explore the Generated Files**:
-    *   After the command completes successfully, you will find a new directory: `document-models/to-do-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.
+    - After the command completes successfully, you will find a new directory: `document-models/to-do-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.
 
 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.