@powerhousedao/academy 0.1.0-dev.3 → 0.1.0-dev.5

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

@@ -0,0 +1,72 @@
+# 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.
+
+## 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).
+
+### 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.
+
+### 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.
+
+## Example: ToDoList State Schema
+
+Let's revisit the `ToDoList` example from the "Define the ToDoList document specification" tutorial.
+
+```graphql
+# The state of our ToDoList
+type ToDoListState {
+  items: [ToDoItem!]!
+}
+
+# A single to-do item
+type ToDoItem {
+  id: ID!
+  text: String!
+  checked: Boolean!
+}
+```
+
+### 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.
+
+*   **`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.
+
+## Best Practices for Designing Your State Schema
+
+1.  **Start Simple, Iterate**: Begin with the core entities and properties. You can always expand and refine your schema as your understanding of the document's requirements grows.
+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.
+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.

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

@@ -0,0 +1,119 @@
+# Specify Document Operations
+
+In the previous section, we defined the state schema for our document model. Now, we turn our attention to a critical aspect of document model creation: **specifying document operations**. These operations are the heart of your document's behavior, dictating how its state can be modified.
+
+## What are Document Operations?
+
+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 `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).
+*   `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.
+
+## Connecting Operations to the Schema
+
+In the "Define ToDoList Document Model" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
+
+```graphql
+# From 02-DefineToDoListDocumentModel.md
+# 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!
+  text: String
+  checked: Boolean
+}
+
+# Defines a GraphQL input type for deleting a to-do item
+input DeleteTodoItemInput {
+  id: ID!
+}
+```
+
+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.
+
+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`).
+
+## Designing Effective Document Operations
+
+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.
+
+### 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`.
+
+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`.
+
+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.
+
+## 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.
+
+## From Specification to Implementation
+
+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`).
+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`.
+
+```typescript
+// From 03-ImplementOperationReducers.md
+import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
+
+export const reducer: ToDoListToDoListOperations = {
+  addTodoItemOperation(state, action, dispatch) {
+    // Implementation uses action.input which matches AddTodoItemInput
+  },
+  updateTodoItemOperation(state, action, dispatch) {
+    // Implementation uses action.input which matches UpdateTodoItemInput
+  },
+  deleteTodoItemOperation(state, action, dispatch) {
+    // Implementation uses action.input which matches DeleteTodoItemInput
+  },
+};
+```
+
+## Conclusion
+
+Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the "what" (the operation and its input) before implementing the "how" (the reducer logic), you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.
+
+In the next section, we will dive deeper into the implementation of the reducer functions for these specified operations.

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

@@ -0,0 +1,116 @@
+# 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.
+
+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.
+
+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.
+
+## Prerequisites
+
+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."
+
+## The Command
+
+The core command to invoke the Document Model Generator is:
+
+```bash
+ph generate <YourModelName.phdm.zip>
+```
+
+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:
+
+```bash
+ph generate Invoice.phdm.zip
+```
+
+When executed, this command reads and parses the specification file and generates a set of files and directories within your Powerhouse project.
+
+## What Happens Under the Hood? A Deep Dive into the Generated Artifacts
+
+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>/`
+
+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.
+
+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.
+
+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.
+
+    *   **`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.
+
+    *   **`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.
+
+## Benefits of Using the Document Model Generator
+
+Leveraging the `ph generate` command offers numerous advantages:
+
+1.  **Reduced Boilerplate:** Automates the creation of repetitive code (type definitions, action creators), saving significant development time and effort.
+2.  **Consistency:** Enforces a standardized project structure and coding patterns across different document models, making projects easier to understand and maintain.
+3.  **Type Safety:** The generation of TypeScript types from your GraphQL schema is a massive boon for catching errors early in the development cycle and improving code quality.
+4.  **Accelerated Development:** By providing a ready-to-use scaffold, developers can immediately focus on implementing the core business logic in the reducers, rather than setting up the foundational plumbing.
+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.
+
+## Example Workflow Snippet
+
+Let's assume you have defined a `ProjectTask` document model and exported `ProjectTask.phdm.zip`.
+
+1.  **Navigate to your Powerhouse project root in the terminal.**
+2.  **Run the generator:**
+    ```bash
+    ph generate ProjectTask.phdm.zip
+    ```
+3.  **Explore the generated files:**
+    You would now find a new directory `document-models/project-task/` containing:
+    *   `project-task/spec.json`
+    *   `project-task/schema.graphql`
+    *   `project-task/gen/types.ts` (with `ProjectTaskState`, `AssignUserInput`, etc.)
+    *   `project-task/gen/operations.ts` (with `creators.assignUser(...)`, `creators.completeTask(...)`, etc.)
+    *   `project-task/src/reducers/project-task.ts` (with empty functions like `assignUserOperation`, `completeTaskOperation` awaiting your implementation).
+
+## 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.
+
+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.
+
+By understanding the role and output of the Document Model Generator, you are well-equipped to efficiently build robust and maintainable document models within the Powerhouse framework.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/05-ImplementDocumentReducers.md

@@ -0,0 +1,282 @@
+# Implement Document Reducers
+
+## The Heart of Document Logic
+
+In our journey through Powerhouse Document Model creation, we've defined the "what" – the structure of our data ([State Schema](02-SpecifyTheStateSchema.md)) and the ways it can be changed ([Document Operations](03-SpecifyDocumentOperations.md)). We've also seen how the [Document Model Generator](04-UseTheDocumentModelGenerator.md) translates these specifications into a coded scaffold. Now, we arrive at the "how": implementing **Document Reducers**.
+
+Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the *new* state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
+
+## Recap: The Journey to Reducer Implementation
+
+Before diving into the specifics of writing reducers, let's recall the preceding steps:
+
+1.  **State Schema Definition**: You designed the GraphQL `type` definitions for your document's data structure (e.g., `ToDoListState`, `ToDoItem`).
+2.  **Document Operation Specification**: You defined the GraphQL `input` types that specify the parameters for each allowed modification to your document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`). These were then associated with named operations (e.g., `ADD_TODO_ITEM`) in the Connect application.
+3.  **Code Generation**: You used `ph generate <YourModelName.phdm.zip>` to create the necessary TypeScript types, action creators, and, crucially, the skeleton file for your reducers (typically `document-models/<YourModelName>/src/reducers/<your-model-name>.ts`).
+
+This generated reducer file is our starting point. It will contain function stubs or an object structure expecting your reducer implementations, all typed according to your schema.
+
+## What is a Reducer? The Core Principles
+
+In the context of Powerhouse and inspired by patterns like Redux, a reducer is a **pure function** with the following signature (conceptually):
+
+`(currentState, action) => newState`
+
+Let's break down its components and principles:
+
+*   **`currentState`**: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as **immutable**.
+*   **`action`**: This is an object describing the operation to be performed. It typically has:
+    *   A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`).
+    *   An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
+*   **`newState`**: The reducer must return a *new* state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
+
+### Key Principles Guiding Reducer Implementation:
+
+1.  **Purity**:
+    *   **Deterministic**: Given the same `currentState` and `action`, a reducer must *always* produce the same `newState`.
+    *   **No Side Effects**: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state.
+
+2.  **Immutability**:
+    *   **Never Mutate `currentState`**: You must never directly modify the `currentState` object or any of its nested properties.
+    *   **Always Return a New Object for Changes**: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object.
+    *   This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. We'll explore techniques for immutability shortly.
+
+3.  **Single Source of Truth**: The document state managed by reducers is the single source of truth for that document instance. All UI rendering and data queries are derived from this state.
+
+4.  **Delegation to Specific Operation Handlers**:
+    While you can write one large reducer that uses a `switch` statement or `if/else if` blocks based on `action.type`, Powerhouse's generated code typically encourages a more modular approach. You'll often implement a separate function for each operation, which are then combined into a main reducer object or map. The `ph generate` command usually sets up this structure for you. For example, in your `document-models/to-do-list/src/reducers/to-do-list.ts`, you'll find an object structure like this:
+
+    ```typescript
+    // Example structure from 01-GetStarted/03-ImplementOperationReducers.md
+    import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated type for operations
+    import { ToDoListState } from '../../gen/types.js'; // Generated type for state
+
+    export const reducer: ToDoListToDoListOperations = {
+      addTodoItemOperation(state: ToDoListState, action, dispatch) {
+        // Your logic for ADD_TODO_ITEM
+        // ...
+        return newState;
+      },
+      updateTodoItemOperation(state: ToDoListState, action, dispatch) {
+        // Your logic for UPDATE_TODO_ITEM
+        // ...
+        return newState;
+      },
+      deleteTodoItemOperation(state: ToDoListState, action, dispatch) {
+        // Your logic for DELETE_TODO_ITEM
+        // ...
+        return newState;
+      },
+      // ... other operations
+    };
+    ```
+    The `ToDoListToDoListOperations` type (or similar, depending on your model name) is generated by Powerhouse and ensures your reducer object correctly implements all defined operations. The `state` and `action` parameters within these methods will also be strongly typed based on your schema.
+
+    The `dispatch` parameter is an advanced feature allowing a reducer to trigger subsequent operations. While powerful for complex workflows, it's often not needed for basic operations and can be ignored if unused.
+
+## Implementing Reducer Logic: A Practical Guide
+
+Let's use our familiar `ToDoList` example (as detailed in `01-GetStarted/03-ImplementOperationReducers.md`) to illustrate common patterns.
+
+Assume our `ToDoListState` is:
+```typescript
+interface ToDoItem {
+  id: string;
+  text: string;
+  checked: boolean;
+}
+
+interface ToDoListState {
+  items: ToDoItem[];
+}
+```
+
+And our action creators (from `../../gen/creators` or `../../gen/operations.js`) provide actions like:
+*   `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
+*   `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
+*   `actions.deleteTodoItem({ id: 'item-id' })`
+
+### 1. Adding an Item (e.g., `addTodoItemOperation`)
+
+To add a new item to the `items` array immutably:
+
+```typescript
+addTodoItemOperation(state: ToDoListState, action: /* AddTodoItemActionType */ any, dispatch) {
+  const newItem: ToDoItem = {
+    id: action.input.id,
+    text: action.input.text,
+    checked: false, // New items default to unchecked
+  };
+
+  // Return a new state object
+  return {
+    ...state, // Copy all existing properties from the current state
+    items: [...state.items, newItem], // Create a new items array: spread existing items, add the new one
+  };
+}
+```
+**Explanation**:
+*   We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
+*   For the `items` array, we create a *new* array by spreading the existing `state.items` and then appending the `newItem`.
+
+### 2. Updating an Item (e.g., `updateTodoItemOperation`)
+
+To update an existing item in the `items` array immutably:
+
+```typescript
+updateTodoItemOperation(state: ToDoListState, action: /* UpdateTodoItemActionType */ any, dispatch) {
+  const { id, text, checked } = action.input;
+
+  // Return a new state object
+  return {
+    ...state,
+    items: state.items.map(item => {
+      if (item.id === id) {
+        // This is the item to update. Return a *new* item object.
+        return {
+          ...item, // Copy existing properties of the item
+          // Update only fields that are provided in the action input
+          ...(text !== undefined && { text: text }),
+          ...(checked !== undefined && { checked: checked }),
+        };
+      }
+      // This is not the item we're looking for, return it unchanged.
+      return item;
+    }),
+  };
+}
+```
+**Explanation**:
+*   We use the `map` array method, which always returns a *new* array.
+*   For the item that matches `action.input.id`, we create a new item object using the spread operator (`...item`) and then overwrite the properties (`text`, `checked`) that are present in `action.input`.
+*   The conditional spread (`...(condition && { property: value })`) is a concise way to only include a property in the new object if its corresponding input value is provided. This elegantly handles partial updates.
+*   If an item doesn't match the ID, it's returned as is.
+
+**Error Handling Note**: In a real application, you might want to add a check to see if an item with `action.input.id` actually exists. If not, you could throw an error or handle it according to your application's requirements:
+```typescript
+// Inside updateTodoItemOperation, before returning:
+const itemToUpdate = state.items.find(item => item.id === action.input.id);
+if (!itemToUpdate) {
+  // Option 1: Throw an error (Powerhouse runtime might catch this)
+  throw new Error(`Item with id ${action.input.id} not found.`);
+  // Option 2: Return current state (no change)
+  // return state;
+}
+// ... proceed with map
+```
+
+### 3. Deleting an Item (e.g., `deleteTodoItemOperation`)
+
+To remove an item from the `items` array immutably:
+
+```typescript
+deleteTodoItemOperation(state: ToDoListState, action: /* DeleteTodoItemActionType */ any, dispatch) {
+  const { id } = action.input;
+
+  // Return a new state object
+  return {
+    ...state,
+    items: state.items.filter(item => item.id !== id), // Create a new array excluding the item to delete
+  };
+}
+```
+**Explanation**:
+*   We use the `filter` array method, which returns a *new* array containing only the elements for which the callback function returns `true`.
+
+## Leveraging Generated Types
+
+As highlighted in [Using the Document Model Generator](04-UseTheDocumentModelGenerator.md), `ph generate` produces TypeScript types for your state (e.g., `ToDoListState`, `ToDoItem`) and the inputs for your operations (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`).
+
+**Always use these generated types in your reducer implementations!**
+
+```typescript
+import {
+  ToDoListState,
+  AddTodoItemInput, // Generated input type
+  // ... other types
+} from '../../gen/types.js';
+import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated operations type
+
+// Define the type for the action more explicitly if needed, or rely on inferred types
+// from ToDoListToDoListOperations. For complex actions, defining specific action types can be beneficial.
+// For example:
+// interface AddTodoItemAction {
+//   type: 'ADD_TODO_ITEM'; // Or the specific string constant used by the action creator
+//   input: AddTodoItemInput;
+// }
+
+export const reducer: ToDoListToDoListOperations = {
+  addTodoItemOperation(state: ToDoListState, action: { input: AddTodoItemInput /* plus type property */ }, dispatch) {
+    // Now 'action.input.text' and 'action.input.id' are type-checked
+    const newItem = {
+      id: action.input.id,
+      text: action.input.text,
+      checked: false,
+    };
+    return {
+      ...state,
+      items: [...state.items, newItem],
+    };
+  },
+  // ... other reducers
+};
+```
+Using these types provides:
+*   **Compile-time safety**: Catch errors related to incorrect property names or data types before runtime.
+*   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
+*   **Clearer code**: Types serve as documentation for the expected data structures.
+
+## Testing Your Reducers
+
+Reducers, being pure functions, are inherently easy to test. For each reducer:
+1.  Set up an initial state.
+2.  Create an action object (ideally using the generated action creators from `../../gen/creators.js` or `../../gen/operations.js`).
+3.  Call the reducer function with the initial state and the action.
+4.  Assert that the returned new state is what you expect it to be.
+5.  Crucially, also assert that the *original* state object was not modified.
+
+The `01-GetStarted/03-ImplementOperationReducers.md` document provides excellent examples of reducer tests:
+
+```typescript
+// Example from 01-GetStarted/03-ImplementOperationReducers.md (simplified)
+import utils from '../../gen/utils'; // For createDocument
+import { reducer } from '../../gen/reducer'; // The combined reducer
+import * as creators from '../../gen/creators'; // Action creators
+import { ToDoListDocument, ToDoListState } from '../../gen/types';
+
+describe('Todolist Operations', () => {
+  let document: ToDoListDocument; // Assuming ToDoListDocument wraps ToDoListState
+
+  beforeEach(() => {
+    document = utils.createDocument(); // Gets initial state
+  });
+
+  it('should handle addTodoItem operation', () => {
+    const input = { id: '1', text: 'Buy milk' };
+    const action = creators.addTodoItem(input); // Use action creator
+
+    // Assuming your main reducer takes the whole document and action
+    const updatedDocument = reducer(document, action);
+
+    expect(updatedDocument.state.global.items).toHaveLength(1);
+    expect(updatedDocument.state.global.items[0].text).toBe('Buy milk');
+    // Also check that document.state.global.items is different from updatedDocument.state.global.items (immutability)
+  });
+});
+```
+
+The generator typically creates a test file skeleton (e.g., `document-models/<YourModelName>/src/reducers/tests/<your-model-name>.test.ts`) to get you started. **Thoroughly testing your reducers is paramount for a robust document model.**
+
+## Reducers and the Event Sourcing Model
+
+Every time a reducer processes an operation and returns a new state, Powerhouse records the original operation (the "event") in an append-only log associated with the document instance. The current state of the document is effectively a "fold" or "reduction" of all past events, applied sequentially by the reducers.
+
+This is why purity and immutability are so critical:
+*   **Purity** ensures that replaying the same sequence of events will always yield the exact same final state.
+*   **Immutability** ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history.
+
+## Conclusion
+
+Implementing document reducers is where you breathe life into your document model's specification. By adhering to the principles of purity and immutability, and by leveraging the type safety provided by Powerhouse's code generation, you can build predictable, testable, and maintainable business logic. These reducers form the immutable backbone of your document's state management, perfectly aligning with the event sourcing architecture that underpins Powerhouse.
+
+With your reducers implemented and tested, your document model is now functionally complete from a data manipulation perspective. The next stages often involve building user interfaces or integrations that interact with this model by dispatching the operations you've now so carefully implemented.