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

package/docs/academy/{02-AdvancedTutorial/01-Create/01-SetupBuilderEnvironment.md → 02-MasteryTrack/01-BuilderEnvironment/01-Prerequisites.md}

@@ -1,43 +1,10 @@
-# Setup Builder Environment
+# Prerequisites 
 
 Let's set up your machine to start building your first Document Model. Don't worry if this is your first time setting up a development environment - we'll guide you through each step!
 
 :::info
-If you've already set up Git, Node, and pnpm, your most important step is to install the Powerhouse CLI with the command `pnpm install ph-cmd`. A global install is recommended if you want to use the command from any directory as a power user. In this case use `pnpm install -g ph-cmd`. The Powerhouse CLI is used to create, build, and run your Document Models and gives you direct access to a series of [Powerhouse Builder Tools](../Create/BuilderTools)
+If you've already set up **Git, Node, and pnpm**, your most important step is to install the **Powerhouse CLI** with the command: `pnpm install ph-cmd`. A global install is recommended if you want to use the command from any directory as a power user. In this case use `pnpm install -g ph-cmd`. The Powerhouse CLI is used to create, build, and run your Document Models and gives you direct access to a series of Powerhouse Builder Tools. Move to the end of this page to [verify your installation.](#verify-installation)
 :::
-
-The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse Ecosystem tools by installing them globally using:
-```bash
-pnpm install -g ph-cmd
-``` 
-
-Key commands include:
-- `ph connect` for running the Connect application locally
-- `ph switchboard` or `ph reactor` for starting the API service
-- `ph init` to start a new project and build a document model
-- `ph help` to get an overview of all the available commands
-
-This tool will be fundamental on your journey when creating, building, and running Document Models.
-
-<details>
-<summary> How to make use of different branches? </summary>
-
-When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
-
-| Command | Description |
-|---------|-------------|
-| **pnpm install -g ph-cmd** | Install latest stable version |
-| **pnpm install -g ph-cmd@dev** | Install development version |
-| **pnpm install -g ph-cmd@staging** | Install staging version |
-| **ph init** | Use latest stable version of the boilerplate |
-| **ph init --dev** | Use development version of the boilerplate |
-| **ph init --staging** | Use staging version of the boilerplate |
-| **ph use** | Switch all dependencies to latest production versions |
-| **ph use dev** | Switch all dependencies to development versions |
-| **ph use prod** | Switch all dependencies to production versions |
-
-Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
-</details>
 ___
 
 ## Table of Contents
@@ -55,11 +22,17 @@ ___
   - [For macOS](#for-macos-2)
   - [For Linux (Ubuntu/Debian)](#for-linux-ubuntudebian-2)
 - [Configure Git](#configure-git-all-systems)
+- [Install Powerhouse CLI](#install-powerhouse-cli)
 - [Verify Installation](#verify-installation)
 
-## Prerequisites
+## Overview
+
+Before we begin building our Document Model, we need to install some software on your machine. We'll need three main tools: 
+- Node.js 22, which helps us run our code.
+- Visual Studio Code (VS Code), which is where we'll write our code
+- Git, which helps us manage our code. 
 
-Before we begin building our Document Model, we need to install some software on your machine. We'll need three main tools: node.js 22, which helps us run our code, Visual Studio Code (VS Code), which is where we'll write our code, and Git, which helps us manage our code. Follow the steps below based on your computer's operating system.
+Follow the steps below based on your computer's operating system.
 
 ### Installing node.js 22
 
@@ -83,14 +56,21 @@ node.js 22 is a tool that lets us run our application. Let's install it step by
    - Once the installer downloads, double-click it to start installation
    - Click "Next" through the installation wizard, leaving all settings at their defaults
 
-3. **Verify Installation:**
+3. **Install pnpm:**
+   - Open PowerShell (no need for admin mode)
+   - Type this command and press Enter:
+   ```powershell
+   npm install -g pnpm
+   ```
+
+4. **Verify Installation:**
    - Open PowerShell (no need for admin mode)
    - Type these commands one at a time and press Enter after each:
    ```powershell
    node --version
    pnpm --version
    ```
-   - You should see version numbers appear after each command (e.g., v18.17.0). If you do, congratulations - node.js 22 is installed!
+   - You should see version numbers appear after each command (e.g., v18.17.0). If you do, congratulations - Node.js and pnpm are installed!
 
 > **Note**: If node.js 22 commands don't work in VS Code, restart VS Code to refresh environment variables.
 
@@ -106,7 +86,11 @@ node.js 22 is a tool that lets us run our application. Let's install it step by
 2. **Install node.js 22:**
    - In the same Terminal window, type this command and press Enter:
    ```bash
-   brew install node
+   brew install node@22
+   ```
+   - Then, install pnpm:
+   ```bash
+   brew install pnpm
    ```
 
 3. **Verify Installation:**
@@ -115,7 +99,7 @@ node.js 22 is a tool that lets us run our application. Let's install it step by
    node --version
    pnpm --version
    ```
-   - If you see version numbers, you've successfully installed node.js 22!
+   - If you see version numbers, you've successfully installed Node.js and pnpm!
 
 #### For Linux (Ubuntu/Debian):
 1. **Open Terminal:**
@@ -163,7 +147,7 @@ VS Code is the editor we'll use to write our code. Here's how to install it:
 6. To make VS Code available in your terminal:
    - Open VS Code
    - Press Command + Shift + P
-   - Type "shell command" and select "Install 'code' command in PATH"
+   - Type "shell command" and select "Shell Command: Install 'code' command in PATH"
 
 #### For Linux (Ubuntu/Debian):
 1. Open Terminal (Ctrl + Alt + T)
@@ -235,6 +219,41 @@ git config --global user.name "Your Name"
 git config --global user.email "your.email@example.com"
 ```
 
+### Install the Powerhouse CLI
+
+The Powerhouse CLI (installed via the `ph-cmd` package) is a command-line interface tool. It provides the `ph` command, which is essential for managing Powerhouse projects. You can get access to the Powerhouse Ecosystem tools by installing them globally using:
+```bash
+pnpm install -g ph-cmd
+``` 
+
+Key commands include:
+- `ph connect` for running the Connect application locally
+- `ph switchboard` or `ph reactor` for starting the API service
+- `ph init` to start a new project and build a document model
+- `ph help` to get an overview of all the available commands
+
+This tool will be fundamental on your journey when creating, building, and running Document Models.
+
+<details>
+<summary> How to use different branches? </summary>
+
+When installing or using the Powerhouse CLI commands you can use the dev & staging branches. These branches contain more experimental features than the latest stable release the PH CLI uses by default. They can be used to get access to a bug fix or features under development.
+
+| Command | Description |
+|---------|-------------|
+| **pnpm install -g ph-cmd** | Install latest stable version |
+| **pnpm install -g ph-cmd@dev** | Install development version |
+| **pnpm install -g ph-cmd@staging** | Install staging version |
+| **ph init** | Use latest stable version of the boilerplate |
+| **ph init --dev** | Use development version of the boilerplate |
+| **ph init --staging** | Use staging version of the boilerplate |
+| **ph use** | Switch all dependencies to latest production versions |
+| **ph use dev** | Switch all dependencies to development versions |
+| **ph use prod** | Switch all dependencies to production versions |
+
+Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
+</details>
+
 ### Verify Installation
 
 Open your terminal (command prompt) and run the following commands to verify your setup:
@@ -242,6 +261,22 @@ Open your terminal (command prompt) and run the following commands to verify you
 node --version
 pnpm --version
 git --version
+ph --version
+```
+
+You should see version numbers displayed for all commands, similar to the example output below (your versions might be higher). The output for `ph --version` includes its version and may also show additional messages if further setup like `ph setup-globals` is needed.
+You're now ready to start building your first Document Model!
+
+```bash
+% node --version
+v22.16.0
+% pnpm --version
+10.10.0
+% git --version
+git version 2.39.3 
+% ph --version
+PH CMD version:  0.43.18
+-------------------------------------
+PH CLI is not available, please run `ph setup-globals` to generate the default global project
 ```
 
-You should see version numbers displayed for all commands. You're now ready to start building your first Document Model!

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/02-StandardDocumentModelWorkflow.md

@@ -0,0 +1,253 @@
+# Creating Powerhouse packages
+
+This tutorial guides you through creating a Powerhouse Document Model, from initial setup to publishing a distributable package. We'll leverage the Powerhouse CLI and Connect Studio Mode for a streamlined development experience.
+
+<details>
+<summary>Key Commands</summary>
+
+-   `pnpm install -g ph-cmd`: Installs the Powerhouse CLI globally.
+-   `ph init`: Initializes a new Powerhouse project or sets up the local environment.
+-   `ph connect`: Runs Connect in Studio Mode for local development and testing.
+-   `ph generate <YourModelName.phdm.zip>`: Generates scaffolding code from an exported document model specification.
+-   `ph generate --editor YourModelName --document-types powerhouse/YourModelName`: Generates an editor template for a document model.
+-   `pnpm build`: Builds the project for production.
+-   `pnpm run test`: Runs unit tests.
+-   `npm login`: Logs into your NPM account.
+-   `npm publish`: Publishes your package to NPM.
+-   `ph install @your-org-ph/your-package-name`: Installs a published package into a local Powerhouse environment.
+
+</details>
+
+## Phase 1: Setup and Initialization
+
+### 1.1. Install Powerhouse CLI
+Ensure you have the Powerhouse Command Line Interface (`ph-cmd`) installed. This tool is crucial for managing your Powerhouse projects.
+```bash
+pnpm install -g ph-cmd
+```
+:::info
+Refer to the [Prerequisites](/academy/MasteryTrack/BuilderEnvironment/StandardDocumentModelWorkflow) guide for detailed installation instructions for Node.js, pnpm, and Git if you haven't set them up yet.
+:::
+
+### 1.2. Initialize Your Project Environment
+Before creating a specific project, or if you're setting up your environment for the first time to use Connect Studio Mode, initialize the Powerhouse environment. This command prepares your local setup, including a local Reactor configuration.
+```bash
+ph init
+```
+If you are starting a new project to be packaged, this command will also prompt you for a project name. This name will be used for your package.
+
+<details>
+<summary> How to make use of different branches? </summary>
+
+When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
+
+| Command | Description |
+|---------|-------------|
+| **pnpm install -g ph-cmd** | Install latest stable version |
+| **pnpm install -g ph-cmd@dev** | Install development version |
+| **pnpm install -g ph-cmd@staging** | Install staging version |
+| **ph init** | Use latest stable version of the boilerplate |
+| **ph init --dev** | Use development version of the boilerplate |
+| **ph init --staging** | Use staging version of the boilerplate |
+| **ph use** | Switch all dependencies to latest production versions |
+| **ph use dev** | Switch all dependencies to development versions |
+| **ph use prod** | Switch all dependencies to production versions |
+
+Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
+</details>
+
+### 1.3. Launch Connect in Studio Mode
+Connect is your local development hub. Running it in Studio Mode spins up a local instance with a local Reactor, allowing you to define, build, and test document models.
+```bash
+ph connect
+```
+This command typically opens Connect in your browser at `http://localhost:3000/`.
+
+:::info
+**Powerhouse Reactors** are essential nodes in the Powerhouse network. They store documents, manage versions, resolve conflicts, and verify document operation histories by rerunning them. Reactors can be configured for local storage (as in Studio Mode), centralized cloud storage, or decentralized storage networks.
+:::
+
+## Phase 2: Document Model Specification
+
+### 2.1. Define the Document Model Schema
+Within Connect Studio Mode, navigate to the Document Model Editor. Here, you'll specify the structure of your document model using GraphQL Schema Definition Language (SDL).
+-   **State Schema:** Describes the data fields and types within your document (e.g., `ToDoItem` with `id`, `text`, `checked` fields).
+-   This schema is the blueprint for your document model's data.
+
+### 2.2. Define Document Model Operations
+In the same editor, specify the operations (state transitions) for your document model. These are also defined using GraphQL, specifically input types.
+-   **Operations Schema:** Specifies the actions that can be performed on the document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`).
+-   Each input type details the parameters required for an operation.
+-   **Best Practices:**
+    *   Clearly define operations (often aligning with CRUD principles).
+    *   Use GraphQL input types for operation parameters.
+    *   Ensure operations reflect user intent for a clean API.
+
+### 2.3. Export Document Model Specification
+Once your schema and operations are defined in Connect, export the specification. This will download a `.phdm.zip` file (e.g., `YourModelName.phdm.zip`). Save this file in the root of your Powerhouse project directory.
+
+## Phase 3: Implementation and Testing
+
+### 3.1. Generate Scaffolding Code
+Use the Powerhouse CLI to process the exported `.phdm.zip` file and generate the necessary boilerplate code for your document model.
+```bash
+ph generate YourModelName.phdm.zip
+```
+This command creates a new directory under `document-models/YourModelName/` containing:
+-   A JSON file with the document model specification.
+-   A GraphQL file with the state and operation schemas.
+-   A `gen/` folder with autogenerated TypeScript types, action creators, and utility functions based on your schema.
+-   A `src/` folder where you'll implement your custom logic (reducers, utils).
+
+### 3.2. Implement Reducer Logic
+Reducers are pure functions that implement the state transition logic for each operation defined in your schema. Navigate to `document-models/YourModelName/src/reducers/to-do-list.ts` (or similar, based on your model name).
+-   Implement the functions for each operation (e.g., `addTodoItemOperation`, `updateTodoItemOperation`).
+-   These functions take the current state and an action (containing input data) and return the new state.
+-   Powerhouse handles immutability behind the scenes.
+
+### 3.3. Write Unit Tests for Reducers
+It's crucial to test your reducer logic. Write unit tests in the `document-models/YourModelName/src/reducers/tests/` directory.
+-   Verify that each operation correctly transforms the document state.
+-   Use the auto-generated action creators from the `gen/` folder to create operation actions for your tests.
+Run tests using:
+```bash
+pnpm run test
+```
+
+### 3.4. Implement the Document Editor
+A document editor provides the user interface for interacting with your document model in Connect. Generate an editor template:
+```bash
+ph generate --editor YourModelName --document-types powerhouse/YourModelName
+```
+-   The `--editor YourModelName` flag specifies the document model this editor is for.
+-   The `--document-types powerhouse/YourModelName` flag links the editor to the specific document type defined in your model specification (ensure this matches what you set in Connect).
+
+This creates a template file, typically at `editors/your-model-name/editor.tsx`.
+-   Customize this React component to build your UI.
+-   You can use standard HTML, Tailwind CSS (available in Connect), or import custom CSS.
+-   Utilize components from `@powerhousedao/document-engineering` for consistency and rapid development. @Callmet Reference back to document engineering
+
+
+### 3.5. Test the Editor
+Run Connect locally to see your editor in action:
+```bash
+ph connect
+```
+Create a new document of your defined type. Interact with your editor, test all functionalities, and ensure it correctly dispatches actions to the reducers and reflects state changes.
+
+## Phase 4: Packaging and Publishing
+
+Once your document model and editor are implemented and tested, you can package them for distribution. A Powerhouse Package is a modular unit that can group document models, editors, scripts, and processors.
+
+### 4.1. Prepare Project for Packaging
+If you didn't initialize your project with `ph init` intending it as a package, ensure your project structure is set up correctly. The `ph init` command is designed to create this structure.
+-   `document-models/`: Contains your document models.
+-   `editors/`: Contains your editor components.
+-   `src/`: Often used for shared utilities or can be part of the model/editor structure.
+-   (Optional) `processors/`, `scripts/` for advanced functionalities.
+
+### 4.2. Specify Package Details in `package.json`
+Navigate to the `package.json` file in your project root. This file is crucial for NPM publishing.
+-   **`name`**: Follow a scoped naming convention, e.g., `@your-org-ph/your-package-name`. The `-ph` suffix helps identify Powerhouse ecosystem packages.
+-   **`version`**: Use semantic versioning (e.g., `1.0.0`).
+-   **`author`**: Your name or organization.
+-   **`license`**: e.g., `AGPL-3.0-only`.
+-   **`main`**: The entry point of your package (e.g., `index.js` or `dist/index.js`).
+-   **`publishConfig`**: For scoped packages intended to be public, add:
+    ```json
+    "publishConfig": {
+      "access": "public"
+    }
+    ```
+
+Example `package.json` snippet:
+```json
+{
+  "name": "@your-org-ph/your-package-name",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "license": "AGPL-3.0-only",
+  "main": "index.js",
+  "files": [ // Ensure your build output and necessary files are included
+    "dist",
+    "manifest.json", 
+    "document-models",
+    "editors"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+### 4.3. Add a Manifest File (`manifest.json`)
+Create a `manifest.json` file in your project root. This file describes your package's contents (document models, editors) and helps host applications like Connect understand and integrate your package.
+
+Example `manifest.json`:
+```json
+{
+  "name": "@yourorg-ph/your-package-name", // it's recommended to use an organization-specific NPM account (e.g., `yourorg-ph`).
+  "description": "A brief description of your package and its document models.",
+  "category": "your-category", // e.g., "Finance", "People Ops", "Legal"
+  "publisher": {
+    "name": "your-publisher-name", // Your organization or name
+    "url": "your-publisher-url"   // Link to your website or repository
+  },
+  "documentModels": [
+    {
+      "id": "powerhouse/YourModelName", // Document type string as defined in Connect
+      "name": "YourModelName"          // Human-readable name
+    }
+  ],
+  "editors": [
+    {
+      "id": "your-editor-id",          // A unique ID for the editor component
+      "name": "YourModelName Editor",  // Human-readable name
+      "documentTypes": ["powerhouse/YourModelName"] // Links editor to document type(s)
+    }
+  ]
+}
+```
+Update your project's main `index.js` or entry point to export your document models and editors so they can be discovered by Powerhouse applications.
+
+### 4.4. Build Your Project
+Compile and optimize your project for production:
+```bash
+pnpm build
+```
+This command typically creates a `dist/` or `build/` directory with the compiled assets. Ensure your `package.json`'s `files` array includes this directory and other necessary assets like `manifest.json`, `document-models`, and `editors` if they are not part of the build output but need to be in the package.
+
+### 4.5. Version Control
+Store your project in a Git repository for versioning and collaboration.
+```bash
+git init
+git add .
+git commit -m "Initial commit of document model package"
+# git remote add origin <your-remote-repository-url>
+# git push -u origin main
+```
+
+### 4.6. Publish to NPM
+To share your package with others or deploy it to different environments, publish it to the NPM registry.
+
+1.  **Login to NPM:**
+    If you haven't already, log into your NPM account. It's recommended to use an organization-specific NPM account (e.g., `yourorg-ph`).
+    ```bash
+    npm login
+    ```
+    Follow the prompts in your terminal or browser.
+
+2.  **Publish the Package:**
+    ```bash
+    npm publish
+    ```
+    If your package is scoped and public, NPM will use the `publishConfig` from your `package.json`. If not set there, you might need `npm publish --access public`.
+
+### 4.7. Using Your Published Package
+Once published, your package can be installed and used in any Powerhouse environment (like another local Connect instance or a deployed Reactor setup).
+```bash
+ph install @your-org-ph/your-package-name
+```
+This command makes the document models and editors defined in your package available within that Powerhouse instance.
+
+Congratulations! You've successfully created, packaged, and published a Powerhouse Document Model. This enables modularity, reusability, and collaboration within the Powerhouse ecosystem.

package/docs/academy/{02-AdvancedTutorial/01-Create/00-BuilderTools.md → 02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md}

@@ -178,7 +178,7 @@ The Powerhouse Design System is a collection of reusable front-end components ba
 - Automatic inclusion as a dependency in new Document Model projects
 - Customization options using CSS variables
 
-Read more about the [design system here](/docs/academy/ComponentLibrary/PowerhouseDesignSystem)
+We cover some of these topics in our design system documentation. Read more about the [design system here](/academy/ComponentLibrary/DocumentEngineering)
 
 ## Reactor Libraries
 ___

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/_category_.json

@@ -0,0 +1,7 @@
+{
+    "label": "Builder Environment",
+    "link": {
+      "type": "doc",
+      "id": "academy/MasteryTrack/BuilderEnvironment/Prerequisites"
+    }
+  }

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

@@ -0,0 +1,188 @@
+# What is a Document Model?
+
+A Document Model is: 
+- 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?**
+
+#### **Structure and Composition**
+
+Each document model consists of three key components:
+
+1. **State Schema** – Defines the structure of the document.
+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. 
+
+---
+
+## **1. Structure of a Document Model**
+
+A document model consists of the following key components:
+
+### **1.1 State Schema**
+
+The **state schema** defines the structure of the document, including its fields and data types. It serves as a blueprint for how data is stored and validated.
+
+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 @default(value: "DRAFT") # Invoice status
+  dueDate: DateTime    # Payment due date
+  lineItems: [LineItem!]! # List of line items
+  totalAmount: Currency  # Computed field for total invoice value
+}
+
+type LineItem {
+  id: OID!
+  description: String
+  quantity: Int @default(value: 1)
+  unitPrice: Currency
+}
+```
+
+### **State Schema Features:**
+
+- Uses **GraphQL-like definitions** for a **clear, structured schema**.
+- Supports **custom scalar types** like `OID`, `Currency`, and `DateTime`. Or other Web3 specific scalars
+- Allows **default values** using `@default(value: "DRAFT")`.
+- Defines **relationships** using object references (`OID!`).
+
+The state schema acts as a **template** for document instances. Every new invoice created will follow this structure.
+
+---
+
+### **1.2 Document Operations**
+
+Document models are **append-only**, meaning changes are not made directly to the document state. Instead, **document operations** define valid state transitions.
+
+Example operations for modifying an invoice:
+
+```graphql
+input AddLineItemInput {
+  invoiceId: OID!
+  description: String
+  quantity: Int @default(value: 1)
+  unitPrice: Currency
+}
+
+input UpdateRecipientInput {
+  invoiceId: OID!
+  newRecipient: OID!
+}
+
+input MarkAsPaidInput {
+  invoiceId: OID!
+}
+```
+
+Each operation **modifies the document state** without altering past data. Instead, a new event is appended to the document history.
+
+---
+
+### **1.3 Event History (Append-Only Log)**
+
+Every operation applied to a document is **stored as an event** in an append-only log.
+
+#### **Example event log for an invoice document:**
+
+```json
+[
+  { "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": {} 
+```
+
+### **Event History Benefits:**
+
+- Provides a **transparent audit trail** of changes.
+- Enables **time travel debugging** by reconstructing past states.
+- Supports **event sourcing**, allowing developers to **replay events** to restore state.
+
+---
+
+## **2. How Document Models Work Technically**
+
+Document models in Powerhouse rely on **event-driven architecture, event sourcing, and CQRS principles**. Here’s a step-by-step breakdown:
+
+### **2.1 Document Creation**
+
+1. A user (or system) **submits an operation** to create a new document.
+2. The document model **validates** the input data against the state schema.
+3. The system **appends the operation** as an event in the document history.
+4. The **initial state is computed** by applying the recorded events.
+
+**Example:**
+
+```json
+{
+  "operation": "CREATE_INVOICE",
+  "data": { "id": "inv-001", "issuer": "company-123", "recipient": "client-456" }
+}
+```
+
+---
+
+### **2.2 Document Modification**
+
+1. A user submits an **operation** (e.g., `ADD_LINE_ITEM`).
+2. The **event is appended** to the document history.
+3. The **state transition logic updates the computed state**.
+4. The UI re-renders the updated document.
+
+**Example:**
+Adding a line item:
+
+```json
+{
+  "operation": "ADD_LINE_ITEM",
+  "data": { "description": "Software Development", "quantity": 10, "unitPrice": 100 }
+}
+```
+
+Since changes are **not applied directly**, this model is **highly scalable and auditable**.
+
+---
+
+### **2.3 Querying Document Models**
+
+Powerhouse uses **GraphQL queries** to fetch document states efficiently. Because documents store structured data, developers can instantly query:
+
+```graphql
+query {
+  invoice(id: "inv-001") {
+    issuer
+    recipient
+    status
+    lineItems {
+      description
+      quantity
+      unitPrice
+    }
+  }
+}
+```
+
+This removes the need for **complex database joins** and allows for **fast, structured access to data**.
+
+---
+
+### **What do document models unlock?**
+
+Document Models offer a range of features that can be leveraged to create sophisticated, automated, and data-driven solutions:
+
+- **API Integration**: Document Models can be integrated with Switchboard API or external APIs, allowing for the exchange of data between Connect and other systems or services.
+
+- **Data Analysi**s**: The structured nature of Document Models makes them ideal for data analysis and reporting. Users can extract insights and generate reports based on the data captured within the models which is accessible through read models. (Operational data + Analytics data which takes into account time series of the data). 
+
+- **Version Control**: Similar to how Git manages changes to source code, Document Models in Connect will support version control, enabling users to track changes, compare different versions, and ensure data integrity over time.
+
+Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data.