@powerhousedao/academy 5.1.0-dev.1 → 5.1.0-dev.10

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/00-DocumentToolbar.mdx

@@ -1,5 +1,9 @@
 # Document Toolbar
 
+:::warning Work in Progress
+This documentation is still being written and may be incomplete.
+:::
+
 The Document Toolbar is a central component in Powerhouse Connect, appearing at the top of every document view. It provides quick access to a variety of tools and functions designed to streamline your workflow and enhance document management.
 
 <figure className="image-container">

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/01-OperationHistory.md

@@ -63,6 +63,10 @@ You can also view the committer's address for each revision, supporting full tra
 
 ![Committer Address Popup](./images/committer-address-popup.png)
 
+
+:::warning Work in Progress
+This remainder of this documentation is still being written and may be incomplete.
+:::
 ## Replay, branch, and merge (under development)
 
 - **Replay:** When you load a document, the system replays all operations to build its state.

package/docs/academy/02-MasteryTrack/05-Launch/04-ConfigureEnvironment.md

@@ -75,7 +75,7 @@ PH_CONNECT_ARBITRUM_ALLOW_LIST=""
 PH_CONNECT_RWA_ALLOW_LIST=""
 PH_CONNECT_HIDE_DOCUMENT_MODEL_SELECTION_SETTINGS="true"
 
-PH_CONNECT_RENOWN_URL="https://auth.renown.id"
+PH_CONNECT_RENOWN_URL="https://www.renown.id"
 PH_CONNECT_RENOWN_NETWORK_ID="eip155"
 PH_CONNECT_RENOWN_CHAIN_ID=1
 PH_CONNECT_DISABLED_EDITORS="powerhouse/document-drive"

package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md

@@ -1,46 +1,112 @@
-# Create New Powerhouse Project
+# Create a new chatroom project
 
-:::tip **Prerequisites**
+:::tip Tutorial Repository
+📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
 
-- Powerhouse CLI installed: `pnpm install -g ph-cmd`
-- node.js 22 and pnpm installed
-- Visual Studio Code (or your preferred IDE)
-- Terminal/Command Prompt access
-
-If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
+This tutorial has a complete reference implementation available. You can:
+- View the complete code for each step
+- Clone and compare your implementation
+- Use `git diff` to compare your code with the reference
 :::
 
-To create a new Powerhouse Document Model Library project, you can use the `ph init` command in your terminal. This command will create a new project in the current directory.
-This command will create a new project in the current directory. You can run the command in the terminal window of your OS or you open the newly installed VSCode and run the command in the terminal window of VSCode.Make sure the terminal reflects the directory where you want to create the new project.
+<details>
+<summary>📖 How to use this tutorial</summary>
+
+This tutorial is designed for you to **build your own project from scratch** while having access to reference code.
+
+### Setup: Create your project and connect to tutorial repo
+
+1. **Create your project** following the tutorial:
+   ```bash
+   mkdir ph-projects
+   cd ph-projects
+   ph init
+   # When prompted, enter project name: ChatRoom
+   cd ChatRoom
+   ```
+
+2. **Add the tutorial repository as a remote** to access reference code:
+   ```bash
+   git remote add tutorial https://github.com/powerhouse-inc/chatroom-demo.git
+   git fetch tutorial --prune
+   ```
+
+3. **Create your own branch** to keep your work organized:
+   ```bash
+   git checkout -b my-chatroom-project
+   ```
+
+Now you have access to the complete reference implementation while working on your own code!
+
+### Compare your work with the reference
+
+At any point, compare what you've built with the reference:
 
 ```bash
-mkdir ph-projects
-cd ph-projects
+# Compare your current work with the reference
+git diff tutorial/main
+
+# Compare specific files
+git diff tutorial/main -- package.json
 ```
 
-This essentially opens that folder and places you in it.
+### If you get stuck
 
-Once you've navigated to the directory where you want to create the new project and in your terminal, run the following command:
+Reset your code to match the reference:
 
 ```bash
-ph init
+# Reset to reference (WARNING: loses your changes)
+git reset --hard tutorial/main
 ```
 
-In the terminal, you will be asked to enter the project name. Fill in the project name and press enter. Make sure to pay attention to the capitalization of our name `ChatRoom` as it will influence your code generation.
+</details>
 
-```bash
-you@yourmachine:~/Powerhouse$ ph init
+## Overview
+
+This tutorial guides you through creating a **ChatRoom** application using Powerhouse.  
+A Powerhouse project primarily consists of a document model and its editor. The ChatRoom demonstrates real-time collaboration features where users can post messages and react with emojis.
+
+## Prerequisites
+
+- Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd`
+- node.js 22 and a package manager (pnpm or npm) installed
+- Visual Studio Code (or your preferred IDE)
+- Terminal/Command Prompt access
 
-? What is the project name? ‣ ChatRoom
+If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
+
+## Quick start
+
+Create a new Powerhouse project with a single command:
+
+```bash
+ph init
 ```
 
+## Before you begin
+
+1. Open your terminal (either your system terminal or IDE's integrated terminal)
+2. Optionally, create a folder first to keep your Powerhouse projects:
+
+   ```bash
+   mkdir ph-projects
+   cd ph-projects
+   ```
+
+3. Ensure you're in the correct directory before running the `ph init` command.  
+   In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
+
+   ```bash
+   you@yourmachine:~/ph-projects % ph init
+
+   ? What is the project name? ‣ ChatRoom
+   ```
+
 Once the project is created, you will see the following output:
 
 ```bash
- The installation is done!
-
- You can start by typing:
-    cd ChatRoom
+Initialized empty Git repository in /Users/you/ph-projects/ChatRoom/.git/
+The installation is done!
 ```
 
 Navigate to the newly created project directory:
@@ -49,9 +115,9 @@ Navigate to the newly created project directory:
 cd ChatRoom
 ```
 
-Once you are in the project directory, now you can run the `ph connect` command to instantiate a local version of the Connect application to start building your document model.
+## Develop your document model in Connect
 
-Run the following command to start the Connect application:
+Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
 
 ```bash
 ph connect
@@ -60,26 +126,36 @@ ph connect
 The Connect application will start and you will see the following output:
 
 ```bash
-you@yourmachine:~/Powerhouse/chatroom$ ph run connect
-
-> Chatroom@1.0.0 connect
-> connect --config-file ./powerhouse.config.json
-
-Watching local document models at '/home/you/Powerhouse/ChatRoom/document-models'...
-Watching local document editors at '/home/you/Powerhouse/ChatRoom/editors'...
   ➜  Local:   http://localhost:3000/
+  ➜  Network: http://192.168.5.110:3000/
   ➜  press h + enter to show help
 ```
 
 A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
 
-If you don't have a local drive created yet, create one using the Generic Drive Explorer app.
+:::tip 
+If your local drive is not present, navigate to Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
+Clear the storage of your localhost application as it might have an old session cached.
+:::
 
-Open your Local Drive and create a new document model by clicking the `DocumentModel` button in the "New Document" section. The GIF below shows where to click.
+4. Move into your local drive.  
+   Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. Name your document `ChatRoom` (PascalCase, no spaces or hyphens).
 
+   **Pay close attention to capitalization, as it influences code generation.**
 
 ![Create New Document Model](./images/ChatRoomConnectApp.gif)
 
-If you followed the steps correctly, you should have an empty document model created called `ChatRoom`.
+If you've followed the steps correctly, you'll have an empty `ChatRoom` document where you can define the **'Document Specifications'**.
+
+## Verify your setup
+
+At this point, your project structure should include:
+
+- Empty `document-models/`, `editors/`, `processors/`, and `subgraphs/` directories
+- Configuration files: `powerhouse.config.json`, `powerhouse.manifest.json`
+- Package management files: `package.json`, `pnpm-lock.yaml`
+- Build configuration: `tsconfig.json`, `vite.config.ts`, `vitest.config.ts`
+
+## Up next
 
 In the next tutorial, you will learn how to design your document model and export it to be later used in your Powerhouse project.

package/docs/academy/03-ExampleUsecases/Chatroom/03-DefineChatroomDocumentModel.md

@@ -1,54 +1,100 @@
-# Define the chatroom document model
+# Write the document specification
 
-In this tutorial, you will learn how to design your document model and export it to be later used in your Powerhouse project.
-If you don't have a document model created yet, have a look at the previous steps of this tutorial to create a new document model.
+:::tip Tutorial Repository
+📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
 
-Before you start, make sure you have the Connect application running.
+This tutorial step has a corresponding implementation in the repository. After completing this step, your project will have a document model specification with:
+- Document model specification files (`chat-room.json`, `schema.graphql`)
+- Auto-generated TypeScript types and action creators
+- Reducer scaffolding ready for implementation
+:::
+
+<details>
+<summary>📖 How to use this tutorial</summary>
+
+**Prerequisites**: Complete step 1 and set up the tutorial remote (see previous step).
+
+### Compare your generated code
+
+After running `ph generate ChatRoom.phd`, compare with the reference:
+
+```bash
+# Compare all generated files with the reference
+git diff tutorial/main -- document-models/chat-room/
+
+# View a specific file from the reference
+git show tutorial/main:document-models/chat-room/schema.graphql
+```
+
+### Visual comparison with GitHub Desktop
+
+After making a commit, use GitHub Desktop for visual diff:
+1. **Branch** menu → **"Compare to Branch..."**
+2. Select `tutorial/main`
+3. Review all file differences in the visual interface
+
+See step 1 for detailed GitHub Desktop instructions.
 
-## Chatroom document model schema
+</details>
 
-We use GraphQL Schema Definition Language (SDL) to define the document model schema. Below, you can see the SDL for the `ChatRoom` document model.
+In this tutorial, you will learn how to define the specifications for a **ChatRoom** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 
-:::info **The State Schema**
-This schema contains the data structure of the document model and the basic operations that can be performed on the document model. For more in depth information please visit [State Schema](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
+If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
+
+Before you start, make sure you have the Connect application running locally with the command:
+
+```bash
+ph connect
+```
+
+## ChatRoom document specification
+
+Make sure you have named your document model `ChatRoom` (PascalCase, no spaces or hyphens).  
+**Pay close attention to capitalization, as it influences code generation.**
+
+We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model. Below, you can see the SDL for the `ChatRoom` document model.
+
+:::info
+This schema defines the **data structure** of the document model and the types involved in its operations. Documents in Powerhouse leverage **event sourcing principles**, where every state transition is represented by an operation. GraphQL input types describe operations, ensuring that user intents are captured effectively.
 :::
 
-## State schema (See next steps)
+<details>
+<summary>State schema of our ChatRoom</summary>
 
 ```graphql
-# Defines a GraphQL type for the state of the chatroom document
+# The state of our ChatRoom
 type ChatRoomState {
-  id: OID! # Unique identifier for the chat-room
-  name: String! # Name of the chat-room
-  description: String # Optional description of the chat-room
-  createdAt: DateTime! # Timestamp of when the chat-room was created
-  createdBy: ID! # Agent ID of the user who created the chat-room
+  id: OID!              # Unique identifier for the chat-room
+  name: String!         # Name of the chat-room
+  description: String   # Optional description of the chat-room
+  createdAt: DateTime!  # Timestamp of when the chat-room was created
+  createdBy: ID!        # Agent ID of the user who created the chat-room
   messages: [Message!]! # List of messages in the chat-room
 }
 
-# Defines a GraphQL type for the state of a message
+# A single message in the chat-room
 type Message {
-  id: OID! # Unique identifier for the message
-  sender: Sender! # Agent details of the message sender
-  content: String # Message content
-  sentAt: DateTime! # Timestamp of when the message was sent
+  id: OID!              # Unique identifier for the message
+  sender: Sender!       # Agent details of the message sender
+  content: String       # Message content
+  sentAt: DateTime!     # Timestamp of when the message was sent
   reactions: [Reaction!] # Reactions to the message
 }
 
-# Defines a GraphQL type for the state of a sender
+# The sender of a message
 type Sender {
-  id: ID! # Unique identifier for the sender
+  id: ID!               # Unique identifier for the sender
   name: String
-  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
+  avatarUrl: URL        # Allows us to pull the ENS and/or NFT of the person's profile
 }
 
-# Defines a GraphQL type for the state of a reaction to a message
+# A reaction to a message
 type Reaction {
-  type: ReactionType! # Type of reaction (one of the predefined emoji)
-  reactedBy: [ID!]! # Agent ID of the user who reacted
+  type: ReactionType!   # Type of reaction (one of the predefined emoji)
+  reactedBy: [ID!]!     # Agent IDs of users who reacted
 }
 
-# Defines the various predefined emojis to react to a message
+# The predefined emoji reactions
 enum ReactionType {
   THUMBS_UP
   THUMBS_DOWN
@@ -56,38 +102,72 @@ enum ReactionType {
   HEART
   CRY
 }
-```
 
-## Operations schema (See next steps)
+type ChatRoomState {
+  id: OID!
+  name: String!
+  description: String
+  createdAt: DateTime
+  createdBy: ID
+  messages: [Message!]!
+}
 
-```graphql
-# add_message
+type Message {
+  id: OID!
+  sender: Sender!
+  content: String
+  sentAt: DateTime!
+  reactions: [Reaction!]
+}
+
+type Sender {
+  id: ID!
+  name: String
+  avatarUrl: URL
+}
+
+type Reaction {
+  type: ReactionType!
+  reactedBy: [ID!]!
+}
+
+enum ReactionType {
+  THUMBS_UP
+  THUMBS_DOWN
+  LAUGH
+  HEART
+  CRY
+}
+
+# messages
 
 input AddMessageInput {
-  messageId: OID! # ID of the message that is being added
-  sender: SenderInput! # ID of the user sending the message
-  content: String! # Content of the message
+  messageId: OID!
+  sender: SenderInput!
+  content: String!
   sentAt: DateTime!
 }
 
 input SenderInput {
-  id: ID! # Unique identifier for the sender
+  id: ID!
   name: String
-  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
+  avatarUrl: URL
 }
 
 input AddEmojiReactionInput {
-  messageId: OID! # ID of the message to which the reaction is being added
-  reactedBy: ID! # ID of the user adding the reaction
-  type: ReactionType! # Type of the reaction (emoji)
+  messageId: OID!
+  reactedBy: ID!
+  type: ReactionType!
 }
 
 input RemoveEmojiReactionInput {
-  messageId: OID! # ID of the message to which the reaction is being removed
-  senderId: ID! # ID of the user that is removing the reaction
-  type: ReactionType! # Type of the reaction (emoji)
+  messageId: OID!
+  senderId: ID!
+  type: ReactionType!
 }
 
+# settings
+
 input EditChatNameInput {
   name: String
 }
@@ -97,55 +177,154 @@ input EditChatDescriptionInput {
 }
 ```
 
-## Define the document model
+</details>
 
-To be able to define the document model, you need to open the Chatroom document model editor in Connect.
+<details>
+<summary>Messages Module: Operations schema of our ChatRoom Messages</summary>
 
-The steps below show you how to do this:
+```graphql
+# Add a new message to the chat-room
+input AddMessageInput {
+  messageId: OID!       # ID of the message being added
+  sender: SenderInput!  # Sender information
+  content: String!      # Content of the message
+  sentAt: DateTime!     # Timestamp when the message was sent
+}
 
-1. In the Connect application, click on the `ChatRoom` document model you've created in the previous step, to open the document model editor.
-2. You'll be welcomed with a form to fill, this is metadata about the document model, fill in the details in the fields.
+# Sender information for a message
+input SenderInput {
+  id: ID!               # Unique identifier for the sender
+  name: String
+  avatarUrl: URL        # Avatar URL for the sender
+}
 
-   In the `Document Type` field, type `powerhouse/chat-room`. This defines the new type of document that will be created with this document model.
+# Add an emoji reaction to a message
+input AddEmojiReactionInput {
+  messageId: OID!       # ID of the message to react to
+  reactedBy: ID!        # ID of the user adding the reaction
+  type: ReactionType!   # Type of the reaction (emoji)
+}
 
-   ![Chatroom Document Model Form Metadata](image-2.png)
+# Remove an emoji reaction from a message
+input RemoveEmojiReactionInput {
+  messageId: OID!       # ID of the message to remove reaction from
+  senderId: ID!         # ID of the user removing the reaction
+  type: ReactionType!   # Type of the reaction (emoji)
+}
 
-3. In the code editor, you can see the SDL for the document model. Replace the existing SDL with the SDL defined in the [State Schema](#state-schema) section above. Only copy and paste the types, leaving the inputs for the next step. You can however already press 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language. Verify that your Global State Initial Value looks like this.
 
-```json
-{
-  "id": "",
-  "name": "",
-  "description": null,
-  "createdAt": null,
-  "createdBy": null,
-  "messages": []
-}
-```
+</details>
 
-4. Below the editor, there is an input field **'Add module'**. You need to create and name a module that the input operations will be added to. In this case, we will name the module **'general_operations'**. Press enter.
-5. Now there is a new field, called **'Add operation'**. Here you will have to add each input operation to the module, one by one.
-6. Inside the **'Add operation'** field, type **'ADD_MESSAGE'** and press enter. A small editor will appear under with an empty input type that you have to fill. Copy the first input type from the [Operations Schema](#operations-schema) section and paste it in the editor. The editor should look like this:
 
-```graphql
-input AddMessageInput {
-  messageId: OID!
-  sender: SenderInput!
-  content: String!
-  sentAt: DateTime!
-}
+<details>
+<summary>Settings Module: Operations schema of our ChatRoom Settings</summary>
 
-input SenderInput {
-  id: ID! # Unique identifier for the sender
+# Edit the chat-room name
+input EditChatNameInput {
   name: String
-  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
+}
+
+# Edit the chat-room description
+input EditChatDescriptionInput {
+  description: String
 }
 ```
 
-7. Repeat step 6 for the other input operations based on the [Operations Schema](#operations-schema). If you noticed, you only need to add the name `(ADD_EMOJI_REACTION, EDIT_CHAT_NAME, etc)` of the operation without the `input` suffix. Then it will be generated once you press enter.
-8. Let's just add a couple more reducer exceptions to the `ADD_MESSAGE` operation which we'll be using later to avoid empty messages or messages exceeding a maximum lenght. Add `MessageContentCannotBeEmpty` and `MessageContentExceedsTheMaximumLenght` to the reducer exceptions of `ADD_MESSAGE`
-9. Once you have added all the input operations, click on the `Export` button, at the top right of the editor, to save the document model on your local machine. Ideally you already save your file in the root of your powerhouse project on your machine.
+</details>
+
+## Define the document model specification
+
+To define the document model, you need to open the document model editor in Connect.
+
+### Steps to define your document model:
+
+1. In the Connect application, click on **'ChatRoom' Document** to open the document model specification editor.
+
+2. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
+
+   In the **Document Type** field, type `powerhouse/chat-room` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification.
+
+   ![Chatroom Document Model Form Metadata](image-2.png)
+
+3. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the **State Schema** section above. Only copy and paste the types, leaving the inputs for the next step. You can press the 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language.
+
+4. Verify that your **Global State Initial Value** looks like this:
+
+   ```json
+    {
+      "name": "",
+      "description": null,
+      "createdAt": null,
+      "createdBy": null,
+      "messages": []
+    }
+   ```
+
+5. Below the editor, find the input field `Add module`. Create and name a module for organizing your input operations. Name the module `general_operations`. Press enter.
+
+6. Now there is a new field, called `Add operation`. Here you will add each input operation to the module, one by one.
+
+7. Inside the `Add operation` field, type `ADD_MESSAGE` and press enter. A small editor will appear underneath with an empty input type that you need to fill. Copy the `AddMessageInput` and `SenderInput` from the **Operations Schema** section and paste them in the editor:
+
+   ```graphql
+   input AddMessageInput {
+     messageId: OID!
+     sender: SenderInput!
+     content: String!
+     sentAt: DateTime!
+   }
+
+   input SenderInput {
+     id: ID!
+     name: String
+     avatarUrl: URL
+   }
+   ```
+
+8. Repeat step 7 for the other input operations: `ADD_EMOJI_REACTION`, `REMOVE_EMOJI_REACTION`, `EDIT_CHAT_NAME`, and `EDIT_CHAT_DESCRIPTION`. Note that you only need to add the operation name (e.g., `ADD_EMOJI_REACTION`) without the `Input` suffix—it will be generated automatically.
+
+9. Add reducer exceptions to the `ADD_MESSAGE` operation for validation: `MessageContentCannotBeEmpty` and `MessageContentExceedsTheMaximumLength`. These will be used later to validate messages.
+
+10. Once you have added all the input operations, click the `Export` button at the top right of the editor to save the document model specification to your local machine. Save the file in the root of your Powerhouse project.
 
 Check the screenshot below to verify the complete implementation:
 
 ![Chatroom Document Model](image-3.png)
+
+## Verify your document model generation
+
+After running `ph generate ChatRoom.phd`, your project should have the following structure in `document-models/chat-room/`:
+
+```
+document-models/chat-room/
+├── gen/                              # Auto-generated code (don't edit)
+│   ├── actions.ts
+│   ├── creators.ts                   # Action creator functions
+│   ├── types.ts                      # TypeScript type definitions
+│   ├── reducer.ts
+│   └── general-operations/
+│       └── operations.ts             # Operation type definitions
+├── src/                              # Your custom implementation
+│   ├── reducers/
+│   │   └── general-operations.ts     # Reducer functions (to implement next)
+│   └── tests/
+│       └── general-operations.test.ts # Test file scaffolding
+├── chat-room.json                    # Document model specification
+└── schema.graphql                    # GraphQL schema
+```
+
+### Compare with reference
+
+Verify your generated files match the expected structure:
+
+```bash
+# Compare your generated files with the reference
+git diff tutorial/main -- document-models/chat-room/
+
+# List what was generated in the reference
+git ls-tree -r --name-only tutorial/main document-models/chat-room/
+```
+
+## Up next: Reducers
+
+In the next step, you'll learn how to implement the runtime logic that will use the `ChatRoom` document model specification you've just created and exported.