@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/05-Architecture/05-DocumentModelTheory/01-WhatIsADocumentModel.md

@@ -0,0 +1,188 @@
+# What is a Document Model?
+
+A Document Model is: 
+- A structured 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. 

package/docs/academy/05-Architecture/05-DocumentModelTheory/02-DAOandDocumentsModelsQ+A.md

@@ -0,0 +1,177 @@
+# Q&A Guide for DAO's
+
+## **1. Introduction to Powerhouse and Document Models**
+
+### **1.1 What is Powerhouse?**
+
+Powerhouse is an open-source initiative focused on optimizing decentralized operations. It provides a structured **DAO operating system** designed to help organizations **automate processes, integrate AI**, and establish scalable workflows.
+
+### **1.2 What is Powerhouse’s ultimate goal?**
+
+Powerhouse aims to **transform decentralized operations** by providing a structured **organizational framework** and technology stack. It focuses on **capturing and automating workflows** through Document Models, enabling DAOs to function more efficiently.
+
+### **1.3 What are the five host apps that form Powerhouse’s ecosystem**
+
+Powerhouse’s ecosystem consists of **five core applications**:
+
+- **Fusion** – A public collaboration platform.
+- **Connect** – A private workspace for contributors.
+- **Renown** – A decentralized identity and reputation hub.
+- **Switchboard** – An open data API that enables data-driven workflows.
+- **Academy** – A learning and onboarding platform for contributors.
+
+---
+
+## **2. Understanding Document Models**
+
+### **2.1 What is a Document Model in simple terms?**
+
+Think of a **Document Model** as a **smart template**. It structures work, ensures **consistency**, and helps **capture necessary data** systematically—like an **intelligent checklist** that guides workflows and enforces best practices.
+
+### **2.2 How do Document Models differ from traditional documents?**
+
+- Traditional documents (.docx, .pdf) offer flexibility but **lack structure**.
+- Document Models are **structured templates** that follow predefined **business logic**.
+- They are **interactive, machine-readable, and optimized** for automation.
+
+### **2.3 Why are Document Models essential for DAOs and decentralized organizations?**
+
+DAOs often struggle with **disorganization, inconsistent data, and inefficient workflows**. Document Models help by:
+
+- **Structuring workflows** to avoid confusion.
+- **Ensuring data consistency** for decision-making.
+- **Automating repetitive processes** to reduce errors.
+
+### **2.4 How do Document Models help individuals working in DAOs?**
+
+Instead of **overcomplicating** workflows, Document Models:
+
+- **Streamline** operations.
+- Reduce the need for **manual coordination**.
+- Allow contributors to focus on **core work** without worrying about administrative overhead.
+
+---
+
+## **3. Document Models in Action**
+
+### **3.1 How do stakeholders interact with Document Models in their daily tasks?**
+
+Stakeholders use Document Models to:
+
+- **Input structured data** rather than free text.
+- Follow **predefined steps** to ensure completeness.
+- **Collaborate seamlessly**, reducing the risk of miscommunication.
+
+### **3.2 How do Document Models improve DAO efficiency?**
+
+- They serve as a **central reference point**, reducing confusion.
+- They **prevent knowledge loss** by capturing business logic.
+- They **enhance operational transparency**, making it easier to track contributions and changes.
+
+### **3.3 Can Document Models adapt to the changing needs of an organization?**
+
+Yes, Document Models are **flexible**. They evolve alongside the DAO, ensuring:
+
+- **New processes and policies** are easily integrated.
+- Workflows remain **aligned with organizational goals**.
+
+---
+
+## **4. Technical Aspects of Document Models**
+
+### **4.1 What is the architecture of a Document Model?**
+
+A Document Model consists of:
+
+- **State schema** – Defines the structure of the document.
+- **Operations** – Specify how the document can change over time.
+- **History tracking** – Ensures that all changes are recorded for traceability.
+
+### **4.2 How do Document Models support process automation?**
+
+Document Models operate on a **transaction-based design**, similar to blockchain:
+
+- Each modification is stored as a **transaction**.
+- Changes synchronize across instances, ensuring **data consistency**.
+- This enables **machine-readability**, making automation **seamless**.
+
+### **4.3 What makes Document Models better than traditional manual processes?**
+
+Traditional processes rely on **manual coordination and fragmented tools**, which lead to:
+
+- **Miscommunication and errors**.
+- **Time-consuming, manual work**.
+- **Lack of visibility into workflows**.
+
+With Document Models:
+
+- **Processes are automated**.
+- **Errors are minimized**.
+- **Workflows are unified**, allowing seamless collaboration.
+
+### **4.4 How do Document Models drive real-time actions like dashboards and reports?**
+
+Since Document Models are **machine-readable**, they:
+
+- Provide data to **dashboards, widgets, and analytics tools**.
+- Enable **real-time process automation**, like task assignments and payments.
+- Function similarly to **Zapier for DAOs**, triggering automated workflows.
+
+---
+
+## **5. The Role of Document Models in Powerhouse’s Ecosystem**
+
+### **5.1 How do Document Models integrate with Powerhouse’s applications?**
+
+- **Connect** – Users interact with Document Models for daily operations.
+- **Fusion** – Public-facing collaborations use structured Document Models.
+- **Switchboard** – Serves as the API that pulls and organizes data.
+- **Renown** – Uses Document Models for decentralized reputation tracking.
+- **Academy** – Trains new users on how to use Document Models effectively.
+
+### **5.2 How do Document Models bridge the gap between business analysts and software developers?**
+
+Document Models **standardize** business logic in a format that both **business stakeholders and developers** can understand, ensuring:
+
+- Clear **documentation of workflows**.
+- Efficient **translation of business needs into software**.
+
+### **5.3 Why is historical data access important for DAOs?**
+
+Running a DAO on a Document Model-based system allows:
+
+- **Version control** – Understanding past decisions.
+- **Easy audits** – Ensuring compliance and transparency.
+- **Better forecasting** – Using historical data for informed decisions.
+
+### **5.4 How do Document Models prepare organizations for AI integration and automation?**
+
+- Clean **data flows** allow AI models to **learn from structured information**.
+- Document Models **train AI assistants** to automate workflows.
+- This paves the way for **custom AI-powered DAOs**.
+
+### **5.5 Why is organization-specific data crucial for AI and automation?**
+
+- Generic AI models lack **deep organizational context**.
+- Organization-specific data enables **highly accurate AI-driven decision-making**.
+- Document Models help structure this data for AI **readiness and automation**.
+
+---
+
+## **6. The Future of Document Models in DAOs**
+
+### **6.1 What happens if a DAO doesn’t use Document Models?**
+
+Without Document Models, DAOs risk:
+
+- **Disorganization** – Lack of structured processes.
+- **Inefficiency** – Time-consuming manual work.
+- **Data inconsistency** – Making decisions harder.
+
+### **6.2 How do Document Models contribute to the long-term success of decentralized organizations?**
+
+By **providing structure, automation, and transparency**, Document Models:
+
+- Reduce **operational overhead**.
+- Improve **decision-making** through structured data.
+- Enable **scalability**, allowing DAOs to grow efficiently.

package/docs/academy/05-Architecture/05-DocumentModelTheory/02-domain-modeling.md

@@ -0,0 +1,103 @@
+---
+id: Domain Modeling
+title: Domain Modeling
+description: This guide will introduce you to the principles of domain modeling and provide a step-by-step process for creating your first GraphQL state schema for a document model.
+slug: /domain-modeling
+---
+
+# Introduction to Domain Modeling with Powerhouse
+
+This guide will introduce you to the principles of domain modeling and provide a step-by-step process for creating your first GraphQL state schema for a document model.
+
+## What is Domain Modeling?
+
+Domain modeling in Powerhouse revolves around defining the structure and behavior of business data using **document models**. Each document model specifies:
+1. **State Schema**: The data structure.
+2. **Operations**: Valid transformations of the state.
+
+Document models are at the core of Powerhouse's event-sourcing architecture, enabling robust and transparent workflows for specific **"business domain's**. Which can range from finances, people-ops or development, but can get as specific as 'invoicing', 'reporting' or 'quality-assurance-checklist'. 
+
+## The analysis and design process
+
+The process for business analysts is a user-centered and iterative approach to problem-solving within a specific business domain. It involves collaboration with expert stakeholders to understand their needs, define problem statements, and develop actionable solutions. The process might include steps such as:
+
+- Interviewing users & business domain experts 
+- Documenting user journeys to come to a problem statements
+- Ideation & solution exploration
+- Defining new use case scenario's
+- Protyping and wireframing for user validation
+- Implement the document model schema definition.
+
+The team at Powerhouse is currently welcoming new business partners to support them in their analysis and design needs via our [discord server](https://discord.com/invite/h7GKvqDyDP)
+
+For our introduction to domain modeling we will instead of an intense analysis and design process stick to a domain that's quite familiar to most of us: 'Invoicing'. 
+
+---
+
+## Steps to Create Your First GraphQL Document Model Schema Definition
+
+First we'll guide you through the necessary steps of reaching your end goal. At the end we'll introduce our custom tooling, "the document-model-editor" which you can use inside Connect to define your document model schema definition. 
+
+### Step 1: Understand the Basics of a Document Model
+A document model consists of:
+- **Document State Schema**: Defines the shape of the data.
+- **Document Operations**: Specify how the state can change.
+
+For example, an `Invoice` document might include:
+- **State Schema**: Recipient, line items, status.
+- **Operations**: Add line item, update recipient.
+
+### Step 2: Define the GraphQL State Schema
+Use GraphQL to model the document state. All fields should:
+1. Be **optional** to allow creating an empty document.
+2. Have **defaults** where required using custom directives.
+
+#### Example
+```graphql
+type InvoiceState {
+  id: OID!
+  status: String @default(value: "DRAFT")
+  recipient: String
+  dueDate: DateTime
+  lineItems: [LineItem!]!
+}
+
+type LineItem {
+  id: OID!
+  description: String
+  quantity: Int @default(value: 1)
+  unitPrice: Currency
+}
+```
+
+### Step 3: Define Document Operations
+Operations represent user actions as state transitions. Define these with GraphQL input types.
+
+#### Example
+```graphql
+input AddLineItemInput {
+  invoiceId: OID!
+  description: String
+  quantity: Int @default(value: 1)
+  unitPrice: Currency
+}
+```
+
+### Step 4: Implement Reducer Functions
+Each operation requires a reducer function to handle state transitions. Start by scaffolding the reducers, then implement specific business logic.
+
+#### Example
+```typescript
+function addLineItem(state, { input }) {
+  const { description, quantity, unitPrice } = input;
+  const lineItem = { id: generateOID(), description, quantity, unitPrice };
+  return {
+    ...state,
+    lineItems: [...state.lineItems, lineItem],
+  };
+}
+```
+
+### Step 6: Test Your Document Model
+Validate the operations by simulating state transitions.
+Use the Powerhouse Reactor for local-first development, enabling offline editing and testing. Ensure the document history maintains an immutable audit trail of all operations.

package/docs/academy/05-Architecture/05-DocumentModelTheory/03-BenefitsOfDocumentModels.md

@@ -0,0 +1,95 @@
+# Benefits of Document Models
+
+As you might have read in our introduction, domain modeling is a foundational practice in the Powerhouse ecosystem, enabling developers to build scalable, structured, and maintainable applications. At the core of Powerhouse's domain modeling approach is the **document model**, a powerful abstraction that encapsulates data, document-operations, and lifecycle management in an append-only data structure.
+
+For developers, this means:
+
+- **Less boilerplate code** to manage state.
+- **More focus on building intuitive front-end applications**.
+- **Greater flexibility** in designing custom workflows.
+- **Seamless blockchain and decentralized system integrations**.
+
+Document models seamlessly integrate with decentralized, blockchain-based architectures because of their append-only nature, providing a structured and event-driven framework that supports real-time collaboration, efficient data retrieval, and modular UI development. This chapter explores the key benefits of document models in Powerhouse and how they empower developers to build robust applications. Soon that will be you! 
+
+---
+
+## **1. Append-Only Structure and Blockchain Compatibility**
+
+One of the fundamental advantages of document models is their **append-only** nature, which aligns perfectly with blockchain transaction-based patterns. In this model:
+
+- Every modification to a document is stored as a new **document operation**, rather than overwriting existing data.
+- The full history of a document remains **immutable**, creating a transparent and auditable record.
+- This structure makes it easier to integrate with blockchain-based storage or decentralized state machines, where **transactions are recorded in sequential order**.
+
+By leveraging append-only principles, document models ensure **data integrity, transparency, and recoverability**, making them ideal for decentralized applications and trustless environments.
+
+## **2. Leveraging Flux Patterns and Event Sourcing Principles**
+
+Document models in Powerhouse naturally fit into an **event-driven architecture**, benefiting from:
+
+- **Flux Patterns**: Changes to a document follow a **unidirectional data flow**, where:
+    - The **user triggers an action** (e.g., updates a field in an invoice).
+    - The action is **dispatched** as a document operation.
+    - The **state updates** based on the append-only event history.
+    - The **UI re-renders** with the updated state.
+- **Event Sourcing Principles**:
+    - Every document operation is **logged as an immutable event**, rather than modifying the state directly.
+    - This enables **time travel debugging**, where developers can inspect historical document states.
+    - Read models can be **reconstructed from past events**, allowing flexible data recovery and analytics.
+
+This event-driven approach provides **high scalability, resilience, and better debugging capabilities**, making it ideal for complex applications with many state changes.
+
+---
+
+## **3. Querying with the Schema Definition Language**
+
+Powerhouse document models are defined using a **schema definition language (SDL)**, which provides a structured format for defining:
+
+- Document state schemas
+- The set of allowed operations
+- Relationships between entities or data objects in the SDL
+
+Because document models are well-structured, they enable immediate queryability. Developers can therefor: 
+
+- **Instantly retrieve document states** based on their schemas.
+- **Use GraphQL queries** to access document data via the Switchboard API
+- **Aggregate read models** from document operations to optimize data fetching.
+- Run data processors to analyse, slice and redirect data as you like.
+
+This built-in queryability allows for real-time, on-demand access to structured data.
+
+---
+
+## **4. Automated State Management for Developers**
+
+Traditionally, handling state management is one of the most complex aspects of front-end development. Powerhouse's document model framework simplifies this by:
+
+- Providing **built-in state tracking** for every document.
+- Automatically maintaining **document revisions** and update history.
+- Ensuring **eventual consistency** across distributed systems.
+
+By **abstracting away state management**, developers can **focus purely on front-end development** without worrying about manual state synchronization, conflict resolution, or data integrity issues.
+
+---
+
+## **5. Modular and Extensible System**
+
+Powerhouse’s document model framework is designed for **extensibility**:
+
+- **Custom plugins** can introduce new document operations.
+- **Computed fields** enable derived data without modifying the core schema.
+- **Integration with AI contributors** allows automated data processing.
+
+By decoupling data models from UI implementations and extending them with **custom plugins**, Powerhouse offers a flexible architecture that evolves with the needs of the organization.
+
+---
+
+## **7. Simplified Collaboration and Auditability**
+
+Since document models maintain **immutable histories**, they offer:
+
+- **Built-in audit trails**, making it easy to track changes over time.
+- **Multi-user collaboration**, where contributors can asynchronously modify documents.
+- **Role-based access control**, defining who can append which operations.
+
+This structured collaboration makes document models ideal for **decentralized governance**, **cross-team workflows**, and **regulated industries** where transparency is critical.