@powerhousedao/academy 5.1.0-dev.9 → 5.1.0

package/docs/academy/03-ExampleUsecases/Chatroom/05-ImplementChatroomEditor.md

@@ -1,122 +1,40 @@
-# Build the ChatRoom editor
+# Implement Chatroom Editor
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
-
-This tutorial covers building the ChatRoom editor:
-1. **Editor Scaffolding**: Generating the editor template with `ph generate --editor`
-2. **Component Implementation**: Building a complete, interactive chat UI with components
-
-Explore the complete implementation in the `editors/chat-room-editor/` directory.
-:::
-
-<details>
-<summary>📖 How to use this tutorial</summary>
-
-This tutorial shows building from **generated scaffolding** to a **complete chat UI**.
-
-### Compare your generated editor
-
-After running `pnpm generate --editor`:
-
-```bash
-# Compare generated scaffolding with the reference
-git diff tutorial/main -- editors/chat-room-editor/
-
-# View the generated editor template
-git show tutorial/main:editors/chat-room-editor/editor.tsx
-```
-
-### Browse the complete implementation
-
-Explore the production-ready component structure:
-
-```bash
-# List all components in the reference
-git ls-tree -r --name-only tutorial/main editors/chat-room-editor/components/
-
-# View a specific component
-git show tutorial/main:editors/chat-room-editor/components/ChatRoom.tsx
-```
-
-### Visual comparison with GitHub Desktop
-
-After committing your editor code:
-1. **Branch** menu → **"Compare to Branch..."**
-2. Select `tutorial/main`
-3. See all your custom components vs. the reference implementation
-
-See step 1 for detailed GitHub Desktop instructions.
-
-</details>
-
-In this chapter we will continue with the interface or editor implementation of the **ChatRoom** document model. This means you will create a user interface for the **ChatRoom** document model which will be used inside the Connect app to visualize your chatroom, send messages, and react with emojis.
+In this section you will implement the `Chatroom` document model editor. This means you will create a simple user interface for the `Chatroom` document model which will be used inside the Connect app to visualise our chatroom, send messages and emoji reactions.
 
 ## Generate the editor template
 
-Run the command below to generate the editor template for the **ChatRoom** document model.  
-This command reads the **ChatRoom** document model definition from the `document-models` folder and generates the editor template in the `editors/chat-room-editor` folder.
-
-```bash
-pnpm generate --editor chat-room-editor --document-types powerhouse/chat-room
-```
+Run below command to generate the editor template for the `Chatroom` document model. This command reads the `Chatroom` document model definition from the `document-models` folder and generates the editor template in the `editors/chat-room/editor.tsx` folder.
 
-Notice the `--editor` flag which specifies the editor name, and the `--document-types` flag defines the document type `powerhouse/chat-room`.
+Notice the `--editor` flag which defines the `chatroom` document model editor. And the `--document-types` flag which defines the document type `powerhouse/chatroom`.
 
-Once complete, you'll have a new directory structure:
-
-```
-editors/chat-room-editor/
-├── components/
-│   └── EditName.tsx          # Auto-generated component for editing document name
-├── editor.tsx                # Main editor component (to be customized)
-└── module.ts                 # Editor module configuration
+```bash
+ph generate --editor ChatRoomEditor --document-types powerhouse/chat-room
 ```
 
-Navigate to the `editors/chat-room-editor/editor.tsx` file and open it in your editor. You'll see a basic template ready for customization.
-
-### Editor implementation options
-
-When building your editor component within the Powerhouse ecosystem, you have several options for styling:
-
-1. **Default HTML Styling:** Standard HTML tags will render with default styles offered through the boilerplate.
-2. **Tailwind CSS:** Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes.
-3. **Custom CSS Files:** You can import traditional CSS files to apply custom styles.
-
-Connect Studio provides a dynamic local environment. By running `ph connect`, you can visualize your components instantly as you build them.
+Once complete, navigate to the `editors/chat-room/editor.tsx` file and open it in your editor.
 
-## Build the editor with components
+As you'll see you will need to add more complex logic to make the chatroom functional and interact with our document model.
 
-We'll build the editor using a component-based approach for better organization and reusability.
+## Add the necessary components for your editor first
 
-### Component-based architecture
+Download the repository of the chatroom-demo as a zip file https://github.com/powerhouse-inc/chatroom-demo
+and navigate to .../chatroom-demo-main/editors/chat-room-editor to copy both the components folder & utils function. In this repository you will also find all of the other code snippets we've been using in this tutorial.
 
-The ChatRoom editor structure includes several components that you can either build yourself or copy from the reference repository:
-
-- `editor.tsx` - Main editor wrapper (imports ChatRoom)
-- `ChatRoom.tsx` - Main container component that orchestrates all other components
-- `Message.tsx` - Individual message component with reactions
-- `EmojiReaction.tsx` - Emoji reaction UI component
-- `TextInput.tsx` - Input component for sending messages
-- `Avatar.tsx` - User avatar component
-
-### Option 1: Copy components from the reference
-
-Download the repository of the chatroom-demo as a zip file from https://github.com/powerhouse-inc/chatroom-demo and navigate to `editors/chat-room-editor` to copy both the `components` folder and `utils.ts` file.
+Drag the folder with react components & utils functions into your VSCode of your chat-room-editor.
 
 In this folder you'll find:
-- An avatar component for chat room participants
+
+- An avatar to be set for each chat room participant
 - The chatroom environment itself
 - A header for the chatroom
-- The UI for rendering messages, usernames, and reaction popups
+- The UI for rendering the message, username and reaction popup.
 - The emoji reaction interface
-- A text input field component
+- A UI for a text input field
 
-The utils function will help you with mapping information from the document model to your chatroom components, such as mapping emoji values to the relevant emoji to be displayed.
+The utils function will help you with mapping information from the document model to your chatroom components. Such as your emoji values to the relevant emoji to be displayed.
 
-### Option 2: Build the main editor file
-
-If you want to understand how everything connects, here's the main `editor.tsx` implementation:
+Now, let's copy & paste the code below into the `editor.tsx` file located at `editors/chat-room-editor`and save the file.
 
 ```typescript
 import { generateId } from "document-model/core";
@@ -146,7 +64,6 @@ export default function Editor() {
     return <div>Loading...</div>;
   }
 
-  // Map document messages to component props
   const messages: ChatRoomProps["messages"] =
     document.state.global.messages.map((message) => ({
       id: message.id,
@@ -158,9 +75,10 @@ export default function Editor() {
       reactions: mapReactions(message.reactions),
     }));
 
-  // Handler for sending messages
   const onSendMessage: ChatRoomProps["onSendMessage"] = (message) => {
-    if (!message) return;
+    if (!message) {
+      return;
+    }
 
     dispatch(
       addMessage({
@@ -176,7 +94,6 @@ export default function Editor() {
     );
   };
 
-  // Handler for adding reactions
   const addReaction = (
     messageId: string,
     userId: string,
@@ -191,7 +108,6 @@ export default function Editor() {
     );
   };
 
-  // Handler for removing reactions
   const removeReaction = (
     messageId: string,
     userId: string,
@@ -206,13 +122,14 @@ export default function Editor() {
     );
   };
 
-  // Handler for clicking on reactions (toggle behavior)
   const onClickReaction: MessageProps["onClickReaction"] = (reaction) => {
     const message = messages.find(
       (message) => message.id === reaction.messageId,
     );
 
-    if (!message) return;
+    if (!message) {
+      return;
+    }
 
     const messageId = reaction.messageId;
     const reactionType = reactionKeyToReactionType(reaction.type);
@@ -233,7 +150,6 @@ export default function Editor() {
     }
   };
 
-  // Handlers for editing chat metadata
   const onSubmitTitle: ChatRoomProps["onSubmitTitle"] = (title) => {
     dispatch(editChatName({ name: title }));
   };
@@ -245,7 +161,11 @@ export default function Editor() {
   };
 
   return (
-    <div style={{ height: "calc(100vh - 140px)" }}>
+    <div
+      style={{
+        height: "calc(100vh - 140px)",
+      }}
+    >
       <ChatRoom
         description={
           document.state.global.description || "This is a chat room demo"
@@ -263,91 +183,18 @@ export default function Editor() {
 }
 ```
 
-**What's happening here:**
-
-- We use `useSelectedChatRoomDocument` hook to get the document state and dispatch function
-- We use `useUser` to get the current user information (for authentication)
-- We map the document's messages to props that our ChatRoom component expects
-- We create handlers for sending messages, adding/removing reactions, and editing metadata
-- We dispatch operations (`addMessage`, `addEmojiReaction`, etc.) from our generated creators
-
-:::info Key Concept: useSelectedChatRoomDocument hook
-The `useSelectedChatRoomDocument` hook is generated by the Powerhouse CLI. It provides:
-1. The current document state (`document`)
-2. A dispatch function to send actions to the reducer
-
-This hook connects your React components to the document model's state and operations.
-:::
-
-## Test your editor
-
-Now you can run the Connect app and see the **ChatRoom** editor in action:
+Now you can run the Connect app and see the `Chatroom` editor in action.
 
 ```bash
 ph connect
 ```
 
-In Connect, in the bottom right corner you'll find a new Document Model that you can create: **ChatRoom**. Click on it to create a new ChatRoom document.
-
-:::warning Authentication Required
-A warning will prompt you to login before you can send messages. Login with an Ethereum address via Renown to start sending messages.
-:::
-
-![Chatroom Editor](./images/ChatRoomTest.gif)
-
-**Try it out:**
-1. Create a new ChatRoom document
-2. Login with your Ethereum wallet
-3. Send messages using the input field
-4. React to messages with emoji reactions
-5. Click the chat name or description to edit them
-
-Congratulations! 🎉  
-If you managed to follow this tutorial until this point, you have successfully implemented the **ChatRoom** document model with its reducer operations and editor.
-
-## Compare with the reference implementation
-
-The tutorial repository includes the complete ChatRoom editor with all components:
-
-```
-editors/chat-room-editor/
-├── components/
-│   ├── Avatar.tsx            # User avatar display
-│   ├── ChatRoom.tsx          # Main chat container
-│   ├── Header.tsx            # Chat header with title/description
-│   ├── Message.tsx           # Individual message display
-│   ├── EmojiReaction.tsx     # Reaction UI
-│   ├── TextInput.tsx         # Message input field
-│   └── index.ts              # Component exports
-├── editor.tsx                # Main editor component
-├── utils.ts                  # Utility functions for data mapping
-└── module.ts                 # Editor module configuration
-```
-
-**View individual components from the reference:**
+In connect, in the bottom right corner you'll find a new Document Model that you can create: `ChatRoom`. Click on it to create a new Chat Room document. A warning will prompt you to login before you are able to send messages.
 
-```bash
-# See the ChatRoom component implementation
-git show tutorial/main:editors/chat-room-editor/components/ChatRoom.tsx
-
-# Explore the Message component
-git show tutorial/main:editors/chat-room-editor/components/Message.tsx
-
-# Compare your implementation with the reference
-git diff tutorial/main -- editors/chat-room-editor/
-```
+Login with an ethereum address via Renown to start sending messages.
 
-## Key concepts learned
+Below GIF shows the `Chatroom` editor in action.
 
-In this tutorial you've learned:
-
-✅ **Component-based architecture** - Breaking down complex UIs into reusable components  
-✅ **Document model hooks** - Using `useSelectedChatRoomDocument` to connect React to your document state  
-✅ **User authentication** - Using `useUser` hook for wallet-based authentication  
-✅ **Action dispatching** - How to dispatch operations from your UI  
-✅ **Type-safe development** - Leveraging TypeScript with generated types from your SDL  
-✅ **Real-time collaboration** - Building features that work across multiple users
-
-## Up next: Local Reactor
+![Chatroom Editor](./images/ChatRoomTest.gif)
 
-In the next section, you'll learn how to run a local Reactor to test real-time synchronization between multiple users.
+If you managed to follow this tutorial until this point, you have successfully implemented the `ChatRoom` document model with its reducer operations and editor.

package/docs/academy/03-ExampleUsecases/Chatroom/06-LaunchALocalReactor.md

@@ -1,103 +1,15 @@
 # Launch a local Reactor
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
+Now we'll create a local Reactor instance to simulate the behaviour of the chatroom synchronising messages between two nodes or users in the network.
 
-This final step demonstrates real-time collaboration by running a local Reactor instance.
-:::
+Wind down connect and run the following command in your terminal.
 
-In this final section, we'll create a local Reactor instance to test the real-time synchronization capabilities of your ChatRoom. This simulates how messages would sync between multiple users in a production environment.
+`ph reactor`
 
-## What is a Reactor?
+This spins up a reactor, which represents a node that is usally hosted as a remote server, but in our case we run it locally on our machine. The reactor you've created will become available as a public drive in your left hand side bar.
 
-A Reactor is a node in the Powerhouse network that:
-- Hosts and synchronizes documents across multiple clients
-- Manages document state and operations
-- Enables real-time collaboration between users
+If you would now open up two different browser windows you will be able to login into two version of connect, with two different ethereum addresses to start validating the functionality of your chatroom.
 
-In production, Reactors are typically hosted as remote servers. For development and testing, we can run a local Reactor.
+Please go ahead now and send a message to yourself, give yourself a thumbs up or try to make your ENS name appear as your profile when logging in. Also remind yourself that you are able to see the revision history of your document and all it's operation history in the top right corner.
 
-## Start the local Reactor
-
-First, stop the Connect application if it's running. Then start the Reactor:
-
-```bash
-ph reactor
-```
-
-This spins up a Reactor that:
-- Runs locally on your machine
-- Creates a public drive accessible from your Connect sidebar
-- Enables synchronization between multiple browser sessions
-
-## Test real-time collaboration
-
-To validate the real-time functionality of your ChatRoom:
-
-1. **Open two browser windows** with the Connect application
-2. **Navigate to the Reactor drive** in the left sidebar (it will appear as a public drive)
-3. **Login with different Ethereum addresses** in each window
-4. **Create a ChatRoom document** in one window
-5. **Open the same document** in the other window
-
-Now you can:
-- Send messages from one window and see them appear in the other
-- React to messages with emojis and watch the reactions sync
-- Edit the chat name or description and see updates propagate
-
-:::info Real-time Sync
-The Reactor ensures that all operations are synchronized across connected clients. Each message and reaction is recorded as an operation, maintaining a complete history that can be replayed to reconstruct the document state.
-:::
-
-## Additional features to explore
-
-While testing your ChatRoom, try these features:
-
-1. **Operation History**: Click on the revision history in the top right corner to see all operations performed on the document
-
-2. **ENS Integration**: If you login with an Ethereum address that has an ENS name, your name and avatar will appear in your messages
-
-3. **Reaction Toggling**: Click on an existing reaction to toggle it on/off for your user
-
-## Running Connect alongside Reactor
-
-You can also run Connect and Reactor together. In separate terminal windows:
-
-```bash
-# Terminal 1: Start the Reactor
-ph reactor
-
-# Terminal 2: Start Connect (in a separate terminal)
-ph connect
-```
-
-This allows you to:
-- Use Connect's local drive for development
-- Access the Reactor's public drive for collaboration testing
-- Switch between local and synchronized documents
-
-## What you've accomplished
-
-Congratulations! 🎉 You've now completed the ChatRoom tutorial and learned how to:
-
-✅ **Create a Powerhouse project** - Initialize and configure a new project  
-✅ **Define a document model** - Design schemas using GraphQL SDL  
-✅ **Implement reducers** - Write the business logic for state transitions  
-✅ **Build an editor** - Create a React-based UI for your document  
-✅ **Test with a Reactor** - Validate real-time collaboration features
-
-## Next steps
-
-Now that you've completed this tutorial, you can:
-
-1. **Explore the Mastery Track** - Dive deeper into [Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) for advanced concepts
-
-2. **Try Vetra Studio** - Use AI-assisted development with [Vetra Studio](/academy/GetStarted/VetraStudio) for faster iteration
-
-3. **Build your own project** - Apply what you've learned to create your own document models and editors
-
-4. **Join the community** - Connect with other Powerhouse builders and share your creations
-
----
-
-*This tutorial demonstrated one of the many ways to use document models within the Powerhouse ecosystem. The patterns you've learned here apply to any collaborative application you want to build.*
+Congratulations! You've now explored one of the many ways to use document models within the powerhouse ecosystem.

package/docs/academy/03-ExampleUsecases/Chatroom/_category_.json

@@ -3,6 +3,6 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "Build a real-time ChatRoom application with Powerhouse. This tutorial guides you through creating a document model for a chat application where users can post messages and react with emojis. You'll learn to define schemas, implement reducers, build a React editor, and test real-time synchronization using a local Reactor."
+    "description": "Get started with the Chatroom tutoria: Jump into creating a new Powerhouse project if you have NodeJs, VSCode, and Git installed. Whe are going to create a new document model that represents a chat.  So you as a user can post messages into that chat room, react to the messages. This chatroom will be synchronized between different connect instances. Let's explore the potential of the tools available in the powerhouse toolkit"
   }
 }

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -8,7 +8,7 @@ The **Powerhouse CLI tool** is the only essential tool to install on this page.
 You can find all of the commands on this page, similar to what would displayed when using ph --help or ph _command_ --help.
 Use the table of content or the search function to find what you are looking for.
 
-The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse Vetra projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
+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.
 
 ```bash
 pnpm install -g ph-cmd
@@ -16,11 +16,7 @@ pnpm install -g ph-cmd
 
 :::
 
-<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n
-
-### ph-cmd Commands
-
-- [Checkout](#checkout)
+<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n### ph-cmd Commands\n\n- [Checkout](#checkout)
 - [Init](#init)
 - [Setup Globals](#setup-globals)
 - [Update](#update)