@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/01-SetupBuilderEnvironment.md

@@ -0,0 +1,216 @@
+
+# Setup Builder Environment
+
+Let's set up your computer 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!
+
+:::warning
+If you've already setup git, node, and npm, your most important step is to install the Powerhouse CLI with the command `npm install ph-cmd`. A global install is recommended if you want to use the command from any directory as a power user. The Powerhouse CLI is used to create, build, and run your Document Models and give you direct access to a series of Powerhouse ecosystem tools.
+:::
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installing node.js 22](#installing-nodejs)
+  - [For Windows](#for-windows)
+  - [For macOS](#for-macos)
+  - [For Linux (Ubuntu/Debian)](#for-linux-ubuntudebian)
+- [Installing Visual Studio Code](#installing-visual-studio-code)
+  - [For Windows](#for-windows-1)
+  - [For macOS](#for-macos-1)
+  - [For Linux (Ubuntu/Debian)](#for-linux-ubuntudebian-1)
+- [Install Git](#install-git)
+  - [For Windows](#for-windows-2)
+  - [For macOS](#for-macos-2)
+  - [For Linux (Ubuntu/Debian)](#for-linux-ubuntudebian-2)
+- [Configure Git](#configure-git-all-systems)
+- [Verify Installation](#verify-installation)
+
+## Prerequisites
+
+Before we begin building our Document Model, we need to install some software on your computer. 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.
+
+### Installing node.js 22
+
+node.js 22 is a tool that lets us run our application. Let's install it step by step.
+
+#### For Windows:
+1. **Set up PowerShell for running commands:**
+   - Press the Windows key
+   - Type "PowerShell"
+   - Right-click on "Windows PowerShell" and select "Run as administrator"
+   - In the PowerShell window, type this command and press Enter:
+   ```powershell
+   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+   ```
+   - Type 'A' when prompted to confirm
+   - You can now close this window and open PowerShell normally for the remaining steps
+
+2. **Install node.js 22:**
+   - Visit the [node.js 22 official website](https://nodejs.org/)
+   - Click the big green button that says "LTS" (this means Long Term Support - it's the most stable version)
+   - 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:**
+   - 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!
+
+> **Note**: If node.js 22 commands don't work in VS Code, restart VS Code to refresh environment variables.
+
+#### For macOS:
+1. **Install Homebrew:**
+   - Open Terminal (press Command + Space and type "Terminal")
+   - Copy and paste this command into Terminal and press Enter:
+   ```bash
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+   - Follow any additional instructions that appear
+
+2. **Install node.js 22:**
+   - In the same Terminal window, type this command and press Enter:
+   ```bash
+   brew install node
+   ```
+
+3. **Verify Installation:**
+   - In Terminal, type these commands one at a time and press Enter after each:
+   ```bash
+   node --version
+   pnpm --version
+   ```
+   - If you see version numbers, you've successfully installed node.js 22!
+
+#### For Linux (Ubuntu/Debian):
+1. **Open Terminal:**
+   - Press Ctrl + Alt + T on your keyboard, or
+   - Click the Activities button and type "Terminal"
+
+2. **Update Package List:**
+   ```bash
+   sudo apt update
+   ```
+
+3. **Install node.js 22 and npm:**
+   ```bash
+   sudo apt install nodejs npm
+   ```
+
+4. **Verify Installation:**
+   - Type these commands one at a time and press Enter after each:
+   ```bash
+   node --version
+   pnpm --version
+   ```
+   - If you see version numbers, you're all set!
+
+### Installing Visual Studio Code
+
+VS Code is the editor we'll use to write our code. Here's how to install it:
+
+#### For Windows:
+1. Visit the [Visual Studio Code website](https://code.visualstudio.com/)
+2. Click the blue "Download for Windows" button
+3. Once the installer downloads, double-click it
+4. Accept the license agreement and click "Next"
+5. Leave the default installation location and click "Next"
+6. In the Select Additional Tasks window, make sure "Add to PATH" is checked
+7. Click "Next" and then "Install"
+8. When installation is complete, click "Finish"
+
+#### For macOS:
+1. Visit the [Visual Studio Code website](https://code.visualstudio.com/)
+2. Click the blue "Download for Mac" button
+3. Once the .zip file downloads, double-click it to extract
+4. Drag Visual Studio Code.app to the Applications folder
+5. Double-click the app to launch 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"
+
+#### For Linux (Ubuntu/Debian):
+1. Open Terminal (Ctrl + Alt + T)
+2. First, update the packages list:
+   ```bash
+   sudo apt update
+   ```
+3. Install the dependencies needed to add Microsoft's repository:
+   ```bash
+   sudo apt install software-properties-common apt-transport-https wget
+   ```
+4. Import Microsoft's GPG key:
+   ```bash
+   wget -q https://packages.microsoft.com/keys/microsoft.asc -O- | sudo apt-key add -
+   ```
+5. Add the VS Code repository:
+   ```bash
+   sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main"
+   ```
+6. Install VS Code:
+   ```bash
+   sudo apt install code
+   ```
+7. Once installed, you can launch VS Code by:
+   - Typing `code` in the terminal, or
+   - Finding it in your Applications menu
+
+### Install Git
+
+#### Windows
+1. Open PowerShell (press Windows key, type "PowerShell", and press Enter)
+2. Visit the [Git website](https://git-scm.com/)
+3. Download the latest version for Windows
+4. Run the installer and use the recommended settings
+5. Verify installation by opening PowerShell:
+   ```powershell
+   git --version
+   ```
+
+#### macOS
+1. Install using Homebrew:
+   ```bash
+   brew install git
+   ```
+2. Verify installation:
+   ```bash
+   git --version
+   ```
+
+#### Linux (Ubuntu/Debian)
+1. Update package list:
+   ```bash
+   sudo apt update
+   ```
+2. Install Git:
+   ```bash
+   sudo apt install git
+   ```
+3. Verify installation:
+   ```bash
+   git --version
+   ```
+
+### Configure Git (All Systems)
+
+Open your terminal (command prompt) and run the following commands to set up Git:
+
+After installation, set up your identity:
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+### Verify Installation
+
+Open your terminal (command prompt) and run the following commands to verify your setup:
+```bash
+node --version
+pnpm --version
+git --version
+```
+
+You should see version numbers displayed for all commands. You're now ready to start building your Document Model!

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/02-CreateNewPowerhouseProject.md

@@ -0,0 +1,78 @@
+# Create New Powerhouse Project
+
+## Create New Powerhouse Document Model Library Project
+
+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.
+
+:::info
+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.
+You will need VSCode later in the tutorial once you have generated the document model.
+Make sure the terminal reflects the directory where you want to create the new project.
+To open a directory in a terminal, you use the cd command to change your current directory. The cd command takes an argument, usually the name of the folder you want to move to, so the full command is 
+```bash
+cd your-directory
+```
+This essentially opens that folder and places you in it.
+:::
+
+Once you've navigated to the directory where you want to create the new project and in your terminal, run the following command:
+
+```bash
+ph init
+```
+
+In the terminal, you will be asked to enter the project name. Fill in the project name and press enter. Make sure to use the name `ChatRoom` as the project name with capital letter R so all of our tutorial code works.
+
+```bash
+you@yourmachine:~/Powerhouse$ 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
+```
+
+Navigate to the newly created project directory:
+
+```bash
+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.
+
+Run the following command to start the Connect application:
+
+```bash
+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/
+  ➜  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.
+
+Create a new document model by clicking on the `DocumentModel` button by the "New Document" section. The Gif below shows you where to click.
+
+![Create New Document Model](./images/ChatRoomConnectApp.gif)
+
+If you followed the steps correctly, you should have an empty document model created called `ChatRoom`.
+
+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/02-AdvancedTutorial/01-Create/02-MoreTutorials/Chatroom/03-DefineChatroomDocumentModel.md

@@ -0,0 +1,139 @@
+# Define the Chatroom Document Model
+
+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.
+
+Before you start, make sure you have the Connect application running.
+
+## Chatroom Document Model Schema
+
+We use GraphQL Schema Definition Language (SDL) to define the document model schema. Below, you can see the SDL for the `ChatRoom` document model.
+
+:::info
+This schema contains the data structure of the document model and the basic operations that can be performed on the document model.
+Document models 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. These operations detail the parameters needed for state transitions The use of GraphQL aligns these transitions with explicit, validated, and reproducible commands, supporting CQRS (Command Query Responsibility Segregation) patterns.
+:::
+
+## State Schema (See next steps)
+
+```graphql
+# Defines a GraphQL type for the state of the chatroom document
+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
+  messages: [Message!]!       # List of messages in the chat-room
+}
+
+# Defines a GraphQL type for the state of a message
+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
+  reactions: [Reaction!]      # Reactions to the message
+}
+
+# Defines a GraphQL type for the state of a sender
+type 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
+}
+
+# Defines a GraphQL type for the state of 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
+}
+
+# Defines the various predefined emojis to react to a message
+enum ReactionType {
+  THUMBS_UP
+  THUMBS_DOWN
+  LAUGH
+  HEART
+  CRY
+}
+```
+
+## Operations Schema (See next steps)
+
+```graphql
+# add_message
+
+input AddMessageInput {
+  messageId: OID!          # ID of the message that is being added
+  sender: Sender!          # ID of the user sending the message
+  content: String!         # Content of the message
+  sentAt: DateTime!
+}
+
+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)
+}
+
+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)
+}
+
+input EditChatNameInput {
+  name: String
+}
+
+input EditChatDescriptionInput {
+  description: String
+}
+```
+
+## Define the Document Model
+
+To be able to define the document model, you need to open the Chatroom document model editor in Connect. 
+
+The steps below show you how to do this:
+
+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. 
+
+    In the `Document Type` field, type `powerhouse/chatroom`. This defines the new type of document that will be created with this document model.
+    
+    ![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 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. 
+```graphql
+{
+  "id": "",
+  "name": "",
+  "description": "",
+  "createdAt": "",
+  "createdBy": "",
+  "messages": ""
+}
+```
+
+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!          # ID of the message that is being added
+    sender: Sender!          # ID of the user sending the message
+    content: String!         # Content of the message
+    sentAt: DateTime!
+    }
+```
+
+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`
+8. 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.
+
+Check the screenshot below to verify the complete implementation:
+
+![Chatroom Document Model](image-3.png)