@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/01-Create/00-BuilderTools.md

@@ -0,0 +1,234 @@
+# Powerhouse Builder Tooling
+
+This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.
+
+## Powerhouse Command Line Interface
+___
+
+### Installing the Powerhouse CLI 
+:::tip
+The Powerhouse CLI tool is the only essential tool to install on this page.   
+Once you've installed it with the command below you can continue to the next steps.
+:::
+
+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>
+
+<details>
+
+<summary> How to clean your system of the Powerhouse CLI?</summary>
+
+### Cleaning and Updating ph-cmd
+
+If you need to perform a clean reinstallation of the Powerhouse CLI (`ph-cmd`), follow these steps:
+
+1. First, uninstall the global ph-cmd package:
+```bash
+pnpm uninstall -g ph-cmd
+```
+
+2. Remove the Powerhouse configuration directory:
+```bash
+rm -rf ~/.ph
+```
+
+3. Reinstall the CLI tool (choose one):
+```bash
+# For the latest stable version
+pnpm install -g ph-cmd
+
+# For the staging version
+pnpm install -g ph-cmd@staging
+
+# For a specific version
+pnpm install -g ph-cmd@<version>
+```
+
+This process ensures a clean slate by removing both the CLI tool and its configuration files before installing the desired version. It's particularly useful when:
+- Troubleshooting CLI issues
+- Upgrading to a new version
+- Switching between stable and staging versions
+- Resolving configuration conflicts 			
+
+</details>
+
+### The Use Command
+The use command allows you to switch between different environments for your Powerhouse project dependencies.
+
+```bash
+ph use <environment> [localPath]
+``` 
+**Available Environments**
+- latest - Uses the latest stable version of all Powerhouse packages.
+- dev - Uses development versions of the packages.
+- prod - Uses production versions of the packages.
+- local - Uses local versions of the packages from a specified path.
+
+**Examples**
+
+#### Switch to latest stable versions
+```bash
+ph use latest
+``` 
+
+#### Switch to development versions
+```bash
+ph use dev
+``` 
+
+#### Use local versions from a specific path
+```bash
+ph use local /path/to/local/packages
+``` 
+
+#### Use a specific package manager
+```bash
+ph use latest --package-manager pnpm
+``` 
+
+### The Update Command
+The update command allows you to update your Powerhouse dependencies to their latest versions based on the version ranges specified in your package.json.
+
+```bash
+ph update [options]
+```
+
+**Examples**
+#### Update dependencies based on package.json ranges
+```bash
+ph update
+```
+
+#### Force update to latest dev versions
+```bash
+ph update --force dev
+```
+
+#### Force update to latest stable versions
+```bash
+ph update --force prod
+```
+
+#### Use a specific package manager
+```bash
+ph update --package-manager pnpm
+```
+
+## **Key Differences**
+
+### **Use command**
+- For switching between different **environments**.
+- Requires you to specify an environment.
+- Can work with **local packages**.
+
+### **Update command**
+- Updating **dependencies** within your current environment.
+- Optional with its parameters.
+- Focused on updating **remote package** versions.
+
+Both commands support multiple package managers (npm, yarn, pnpm, and bun) and will automatically detect your project's package manager based on the lockfile present in your project directory.
+
+## Boilerplate
+___
+The Document Model Boilerplate is a foundational template that is used for code generation when scaffolding your editors and models. It ensures compatibility with host applications like Connect and Switchboard for seamless Document Model and editor integration. 
+
+After installing `ph-cmd`, you will run `ph init` to initialize a project directory and structure. This initialization command makes use of the boilerplate. 
+
+The boilerplate includes essential commands with NPM/PNPM scripts for:
+- Generating code
+- Linting
+- Formatting
+- Building
+- Testing
+
+## Design System
+___
+The Powerhouse Design System is a collection of reusable front-end components based on GraphQL scalars, including custom scalars specific to the web3 ecosystem. It provides:
+- Consistent UI components across Powerhouse applications
+- 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)
+
+## Reactor Libraries
+___
+Reactors are the nodes in the Powerhouse network that handle document storage, conflict resolution, and operation verification. 
+The Reactor Libraries include:
+
+### API
+- **Subgraphs**: Modular GraphQL services that connect to the Reactor for structured data access
+- **Processors**: Event-driven components that react to document changes and process data
+
+### Browser
+Handles client-side interactions
+
+### Local
+Manages local storage and offline functionality
+
+### Drive App
+Handles document organization and storage management, but can also be customized to offer specific functionality, categorization, or tailored interfaces for your documents. 
+
+## Code Generators
+___
+Powerhouse provides several code generation tools to streamline development:
+
+    ### Document Model Scaffolding
+    Generates the basic structure for new Document Models with the command `ph init` based on the boilerplate. 
+
+    ### Editor Generator
+    Creates template code for Document Model editors with the command `ph generate --editor <name> --document-types <documenttype>`
+
+    ### Drive Editor Generator
+    Builds scaffolding for custom Drive interfaces with the command `ph generate --drive-editor <name>`
+
+    ### Subgraph Generator
+    Creates GraphQL subgraph templates for data access automatically upon `ph reactor`
+
+    ### Processor Generator
+    Generates processor templates for event handling automatically upon `ph reactor`
+
+    ### Analytics Processor Generator
+    Creates specialized processors for analytics tracking
+
+## Analytics Engine
+___
+The Analytics Engine is a system that allows tracking and analyzing operations and state changes on Document Models. Features include:
+- Custom dashboard and report generation
+- Document Model-specific analytics
+- Metric and dimension tracking
+- Data combination from multiple Document Models
+
+Generate an analytics processor using:
+```bash
+ph generate --processor-type analytics
+```

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

@@ -0,0 +1,247 @@
+# Setup Builder Environment
+
+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)
+:::
+
+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
+- [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 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.
+
+### 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 pnpm:**
+   ```bash
+   sudo apt install nodejs pnpm
+   ```
+
+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
+
+#### For 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
+   ```
+
+#### For macOS
+1. Install using Homebrew:
+   ```bash
+   brew install git
+   ```
+2. Verify installation:
+   ```bash
+   git --version
+   ```
+
+#### For 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)
+
+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 first Document Model!

package/docs/academy/02-AdvancedTutorial/01-Create/02-MoreTutorials/04-UtilitiesAndTips.md

@@ -0,0 +1,79 @@
+# Utilities and Tips
+
+## What will be produced for you on your next document model: 
+
+To help you along your way in document model generation we've set you up with a couple of tools that help you write your reducers. Alongside we'll offer you a series of tips that make your life a bit easier while defining document models.
+
+### 1. Introducing Zod
+
+The reducer's input, output, and possibly internal state are defined and enforced using the Zod library. Zod is a TypeScript-first schema declaration and validation library that allows developers to create schemas that describe the shape and constraints of data. By using Zod to strongly type a reducer, you leverage TypeScript's static type checking along with Zod's runtime validation to ensure that the data flowing through the reducer conforms to expected types and structures at both compile-time and runtime.
+
+### 2. Introducing Immer
+
+Immer is a library designed to simplify the process of working with immutable state in JavaScript applications, particularly in contexts like Redux reducers, where immutability is a key principle. Immer allows you to write code that appears to mutate state directly while actually producing new immutable states behind the scenes. This approach significantly simplifies the reducer logic, especially when dealing with complex state shapes or deep updates. 
+
+### 3. Generate Mock Data
+
+The GenerateMock function is designed to simplify the creation of mock data for testing purposes. By taking a Zod schema as its input, it leverages the capabilities of Faker.js to automatically generate fake, yet plausible, values for each element defined within the schema. This allows developers to efficiently produce mock data corresponding to the structure and constraints specified in their Zod schemas, facilitating thorough testing and validation of application functionality without the need for manually crafting mock data sets for each schema.
+
+### 4. Making use of utility Functions
+
+Embedding detailed business logic directly within reducers can lead to bulky, hard-to-test code. To mitigate this, we recommend abstracting business logic into discrete utility functions. Reducers become straightforward maps between action types and state transformations, with the heavy lifting offloaded to utility functions. This offers several advantages to your document model. 
+
+1. Modularity: Utility functions encapsulate specific pieces of business logic, making your codebase more organized and modular. 
+
+2. Granular Testing: By isolating business logic in utility functions, you can write more focused and granular tests. 
+
+3. Reusability: Utility functions can be reused across different parts of your application, including multiple reducers. 
+
+4. Reducer Simplicity: Keeping reducers lean by focusing on state transition mechanisms rather than detailed logic makes them more predictable and easier to maintain. 
+
+### 5. Working with derived fields
+
+Understand that inputs to reducers don't have to directly map to the schema's state fields. This is particularly important for derived fields, which are computed based on other data or transactions within the model.
+
+- **Derived Fields**: Certain fields within a state object, such as for example 'an asset', do not hold values provided directly by user input but are calculated from other data, like a series of transactions. 
+
+- **Reducer Inputs and State Updates**: The input to a reducer function responsible for updating the state of such an asset doesn't need to include these derived fields explicitly. Instead, the reducer needs sufficient information to identify the asset and perform calculations to update these derived fields based on new transactions and the latest state.
+
+- **Example of Updating Derived Fields**: When a new 'transaction' occurs, such as the sale of 'an asset', the relevant reducer function computes the necessary updates to the derived fields (e.g., "purchase price") of the associated asset. This computation is based on the details of the transaction and the existing data of the asset within the state.
+
+Even in scenarios involving intricate relationships between different parts of the state (such as our example above: transactions affecting assets), the reducer treats the state as a single cohesive object. It performs all necessary computations and updates within the context of a single operation, returning a new, updated state object that reflects all changes.
+
+### 6. `getDifferences` function
+
+Even though we're receiving all of the fields in the form, at the moment we're submitting an edit for an item, we first check which fields are actually different with the previous state with the getDifferences function. This allows us to only publish an edit operation action that only contains the changed fields. We don't include all of the fields, which it might to by default, but only the 'differences' in the data. Making it much easier to keep track of operations going forward. 
+
+```javascript
+input : {
+    id : "0.4019292477011591"
+    text : "New task"
+}
+```
+
+### 8. How reducers & editors go hand in hand.
+
+In developing a document model, it's crucial to distinguish between derived and stored states to maintain efficiency and simplicity. For instance, the state of our checked to-dos in our to-do list application doesn't need to be persistently saved in the document model, as their count can be dynamically derived from the current state. 
+
+Reducers help manage and update states based on actions, while editors provide functionalities such as counting checked to-dos through specific functions. Both derived states, like the count of checked to-dos or unit prices in a portfolio, and the tools to manage them (reducers and editors) reside within the same repository, so it's most effective to develop and update reducers and editors concurrently. Keeping this in mind while developing ensures that only essential data is stored, while derived data is efficiently calculated as needed.
+
+### 9. No need for asynchronous operations
+
+Asynchronous operations should be handled outside of the document model, ensuring that reducers remain pure functions of the state
+
+Document models primary focus is on capturing the data specific to a business domain rather than facilitating user interface interactions. The document model's role is to represent and capture the business logic and rules inherent to the domain model. 
+For instance, in the context of a real asset portfolio, the document model is concerned with operations such as adding a new transaction to an asset and how such actions affect the total value of the asset—essentially, the core calculations and data manipulations that reflect business events and their impacts on the domain state.
+
+This focus on the business logic side, rather than on asynchronous operations typically associated with user interface interactions (like fetching data or updating UI elements in response to user actions), means that the document model serves as a portable module. It's designed to be used across different contexts within the applications of powerhouse, prioritising the accurate representation and manipulation of business data (through Fusion or Switchboard) over UI concerns. 
+
+### Additional Tips
+
+- Design state schemas with clear distinctions between directly inputted data and derived/computed fields.
+
+- Implement reducers that can handle complex operations by computing necessary updates based on actions without requiring explicit inputs for derived fields.
+
+- Maintain the purity of reducer functions by ensuring they do not mutate the existing state but instead return new instances of the state with the required updates.
+
+- Validation and Leniency: While some validation is necessary, aim to be as lenient as possible without allowing unrecoverable states. 
+
+- The strict ts-eslint rules set by the core developers at Powerhouse will help you maintain code quality, consistency, and adherence to best practices across the project.