@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/03-BuildingUserExperiences/07-DocumentTools/02-RevisionHistoryTimeline.md

@@ -0,0 +1,132 @@
+# Revision History Timeline
+
+The timeline feature enables users to view document history and navigate through different revisions of a document. This guide explains how to implement and customize the timeline functionality in your Powerhouse application.
+
+## Enabling the Timeline Feature
+
+To enable the timeline feature in your document editor, you need to set `timelineEnabled: true` in your editor module configuration:
+
+```typescript
+// editors/to-do-list/index.ts
+export const module: EditorModule<ToDoDocument> = {
+  Component: Editor as unknown as FC<EditorProps<ToDoDocument> & Record<string, unknown>>,
+  documentTypes: ["powerhouse/todo"],
+  config: {
+    id: "editor-id",
+    disableExternalControls: true,
+    documentToolbarEnabled: true,
+    showSwitchboardLink: true,
+    timelineEnabled: true,  // Enable timeline feature
+  },
+};
+```
+
+This setting enables the timeline button in the document toolbar.
+
+## Implementation Options
+
+### Default Drive Explorer
+
+When using the default drive explorer with `ph connect`, the timeline functionality is handled automatically:
+
+- Document analytics are collected and passed to the document toolbar
+- The timeline button appears in the toolbar when enabled
+- Users can click on timeline items to view document revisions
+
+### Custom Drive Explorer
+
+For custom drive explorers, you need to handle timeline items fetching and user interaction manually. Here's how:
+
+1. First, import the necessary utilities from the Powerhouse common package:
+
+```typescript
+import { useTimelineItems, getRevisionFromDate } from "@powerhousedao/common";
+```
+
+2. Fetch timeline items using the `useTimelineItems` hook:
+
+```typescript
+// In your EditorContainer.tsx
+const timelineItems = useTimelineItems(documentId);
+```
+
+3. Track the selected timeline item in state:
+
+```typescript
+const [selectedTimelineItem, setSelectedTimelineItem] = useState<TimelineItem | null>(null);
+```
+
+4. Pass the timeline items to the DocumentToolbar and handle item selection:
+
+```typescript
+<DocumentToolbar
+  timelineButtonVisible={editorModule.config.timelineEnabled}
+  timelineItems={timelineItems.data}
+  onTimelineItemClick={setSelectedTimelineItem}
+  // ... other props
+/>
+```
+
+> **Note**: The `timelineButtonVisible` prop should be set based on the `timelineEnabled` setting in the editor module's configuration. This ensures the timeline button is only shown when the feature is enabled for that specific document type.
+
+5. Pass the required context values to your editor component:
+
+```typescript
+<EditorComponent
+  context={{
+    ...context,
+    readMode: !!selectedTimelineItem,
+    selectedTimelineRevision: getRevisionFromDate(
+      selectedTimelineItem?.startDate,
+      selectedTimelineItem?.endDate,
+      document.operations.global,
+    ),
+  }}
+  // ... other props
+/>
+```
+
+## Handling Timeline Revisions in Document Editor
+
+In your document editor (e.g., `editors/to-do-list/editor.tsx`), you need to handle the timeline context props:
+
+1. Extract timeline-related properties from the context:
+
+```typescript
+const { readMode = false, selectedTimelineRevision, getDocumentRevision } = context;
+```
+
+2. Fetch the document at the selected revision when in read mode:
+
+```typescript
+const [readModeDocument, setReadModeDocument] = useState<ToDoDocument | null>(null);
+
+useEffect(() => {
+  const getReadModeDocument = async () => {
+    if (getDocumentRevision && readMode && typeof selectedTimelineRevision === 'number') {
+      const document = await getDocumentRevision({ revisions: { global: selectedTimelineRevision } });
+      setReadModeDocument(document);
+    } else if (!readMode) {
+      setReadModeDocument(null);
+    }
+  };
+  getReadModeDocument();
+}, [getDocumentRevision, readMode, selectedTimelineRevision]);
+
+// Use the appropriate document based on mode
+const document = readModeDocument || writeModeDocument;
+```
+
+3. Adapt your UI to reflect read mode:
+
+```typescript
+{readMode && (
+  <div className="text-gray-500 text-md text-center">(🔒 Read Mode)</div>
+)}
+
+{!readMode && (
+  // Edit controls here
+)}
+```
+
+This implementation allows users to navigate through document history while preventing edits to historical revisions.

package/docs/academy/02-AdvancedTutorial/03-BuildingUserExperiences/07-DocumentTools/_category_.json

@@ -0,0 +1,7 @@
+{
+    "label": "Document Tools",
+    "link": {
+      "type": "generated-index",
+      "description": "All of the tools that you get for free with Powerhouse."
+    }
+  }

package/docs/academy/02-AdvancedTutorial/03-BuildingUserExperiences/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Build User Experiences",
+    "position": 4,
+    "link": {
+      "type": "generated-index",
+      "description": "Learn how to build beautiful document editors and drive-apps in Connect."
+    }
+  }

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/01-ReadingAndWritingThroughTheAPI.mdx

@@ -0,0 +1,121 @@
+# Read & Write through the API
+
+## Introduction to Switchboard
+
+**Switchboard** is the API interface that allows developers and data engineers to get access to the data, that is being collected through the use of document models in Connect & Fusion.
+After structurally capturing the desired data of your formalised business processes the data can be used to build insightful experiences in external websites, drive widgets or create specific reports and dashboard in fusion. 
+**Since your document models have been defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your document models.**
+
+<details>
+  <summary>Get your Switchboard API token (if required)</summary>
+
+Your API requests are authenticated using API keys or tokens. Any request that doesn't include an API key will return an error. You can generate an API token from your Switchboard instance at any time [by logging in with your Ethereum address here](https://apps.powerhouse.io/develop/powerhouse/switchboard/user).
+
+</details>
+
+## Querying a document with the GraphQL API
+
+### Starting the reactor locally
+
+In this documentation we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the ToDoList example** from our [introduction tutorial](/docs/academy/GetStarted/ToDoList/DefineToDoListDocumentModel) , but the process can be applied to any other document model.
+To make our document model available in the Apollo Studio Sandbox we'll need to store it on a remote [Reactor](/docs/academy/Architecture/WorkingWithTheReactor).
+
+:::info
+**Powerhouse Reactors** are the nodes in the network that store documents, resolve conflicts and rerun operations to verify document event histories. 
+Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. 
+
+A reactor allows you to store multiple documents, but also host **drives** with different organisational purposes, users, access rights and more.
+:::
+
+Just like we can run Connect locally in studio mode we can run a remote node or a Reactor locally.   
+Use the following commands:
+
+```bash
+ph reactor
+```
+
+To start both Connect and a Reactor locally at the same time in a Powerhouse project you can use the following command:
+```bash
+ph dev
+```
+
+It will return a url to access the Reactor.
+```bash
+[Reactor]:   ➜  Reactor:   http://localhost:4001/d/powerhouse
+```
+
+### Adding a remote drive or reactor to Connect:
+
+If the remote drive or Reactor isn't present yet in connect you can add it by clicking the (+) button in the Connect drive navigation 
+and using the localhost url to add a new drive with it's underlying reactor. Usually http://localhost:4001/d/powerhouse
+
+Get access to an **organisations drive** instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive url. 
+click the (+) to add a public drive. To add a new drive you'll have to know the correct public URL of the drive.
+
+## Querying the state of a document
+
+Now that we have our remote reactor and/or drive running we can store our document model on it.   
+Let's quickly create a new **todo list document** to test the process.
+
+Add to following todo's to your list:
+- [ ] Sign up for Powerhouse
+- [ ] Do the work 
+- [ ] Deliver the work
+- [ ] Send the invoice
+- [ ] Get paid
+
+Now that we have some data in our document model we can query it through the GraphQL API.
+
+### 1. The complete state of the document: 
+
+Whenever you want to start a query from a document within connect you can open up switchboard by looking for the Switchboard logo in the top right hand corner of the document editor interface. 
+This will prepopulate the Apollo Studio Sandbox with the correct **DocumentID** for your document model. This feature will not be available for documents stored on local drives.
+
+![Switchboardbutton](./images/SwitchboardButton.png)
+
+The documentation on the left hand side of the Apollo Sandbox will show you all of the different fields that are available to query.
+
+![document query](./images/QueryDocumentID.png)
+
+Alternatively we can just use our reactor url and endpoint to figure out the document id.  
+We can find out what the id of our document is by querying the drive for it's documents.   
+Since we only have one document in our drive it will return the id of our todo list document.
+
+This example query is structured to request a document by its unique identifier (id).   
+It extracts common fields such as **id**, **name**, **documentType**, **revision**, **created**, and **lastModified**.
+
+In the above example we queried for the content of the operations. Let's compare the results with the document operation history. 
+Side by side you can see the document content and the operation history.
+
+Below is the operation history of the todo list document. As you can see the operations are logged in the order they were executed.
+As you can see there is a 'Delete' operation in the history on revision 5 as we forgot to add 'Send the invoice' to our list.
+![Operation History](./images/OperationHistory.png)
+
+Now let's query the content of the document using Apollo Studio Sandbox. The left sidebar shows the schema documentation, where you can explore all available fields and types for your document model. 
+
+For our TodoList document, let's construct a query that fetches the operations with the help of a nested operations field
+
+```graphql
+query {
+  document(id: "...") {
+    name
+    documentType
+    revision
+    created
+    lastModified
+    ... on TodoList {
+      operations {
+        type
+        id
+        inputText
+      }
+    }
+  }
+}
+```
+
+This query will return all operations performed on the document, including ADD_TODO_ITEM and DELETE_TODO_ITEM operations, allowing us to see the complete history of changes.
+
+## Writing to a document
+
+Now that we know how to query the state of a document we can start to write to it.

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/02-GraphQLAtPowerhouse.md

@@ -0,0 +1,156 @@
+# GraphQL at Powerhouse
+
+In this section, we will cover **the core concepts of GraphQL with examples applied to the Powerhouse ecosystem**. More specifically, GraphQL is used as:
+- The **schema definition language (SDL)** for defining our document models and thereby self-documenting the API to the data model. It allows developers to define the structure and relationships of data in a strongly-typed format.
+- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically. Jump to the section [GraphQL and Subgraphs](/docs/academy/AdvancedTutorial/WorkWithData/WorkingWithSubgraphs/GraphQLAndSubgraphs) to learn more about this.
+
+
+### Why GraphQL?
+
+- **Precision**: Instead of over-fetching or under-fetching data, GraphQL enables you to specify the precise data requirements in your query.
+- **Single Endpoint**: With GraphQL, you can access all the data you need through one endpoint, reducing the number of network requests.
+- **Dynamic Queries**: Its introspective nature allows developers to explore the API's schema dynamically, which streamlines development and documentation.
+
+## GraphQL: Core Concepts
+
+### Schema
+The schema defines the structure of a GraphQL API. It acts as a contract between the client and server, detailing:
+
+- **Data Types**: The various types of data that can be queried.   
+For example the contributor type and the project type
+- **Fields**: The available fields on each type.   
+For example the contributor type has a field 'name' and the project type has a field 'title'
+- **Relationships**: How different types relate to each other.   
+For example the contributor type has a relationship with the project type
+
+  ```graphql title="Example of a Powerhouse Contributor schema in GraphQL"
+  type Contributor {
+    id: ID!
+    name: String!
+    reputationScore: Float
+    projects: [Project]   # The Contributor type has a field 'projects' that returns an array of Project objects
+  }
+
+  type Project {
+    id: ID!
+    title: String!
+    status: String
+    budget: Float
+  }
+
+  type Query {
+    getContributor(id: ID!): Contributor
+  }
+  ```
+
+  With the following query someone can request the contributor with the id 123
+
+    ```graphql title="Example of a query to get a contributor"
+    query {
+      getContributor(id: "123") {
+        name
+        reputationScore
+        projects {      # Accessing the related projects
+          title
+          status
+        }
+      }
+    }
+    ```
+
+---
+
+### Fields & Arguments
+- **Field**: A specific piece of data you can request from an object. When you build a query, you select the fields you want to retrieve.
+- **Argument**: Key-value pairs that can be attached to fields to customize and refine the query. Some fields require arguments to work correctly, especially when dealing with mutations.
+
+  Powerhouse uses invoices as part of its decentralized operations. With GraphQL, an invoice query might look like this:
+  Here, contributorId and status are arguments that filter the results to return only paid invoices for a specific contributor.
+
+  ```graphql title="Fetching an Invoice with Filtering"
+  query {
+    getInvoices(contributorId: "456", status: "PAID") {
+      id
+      amount
+      currency
+      dueDate
+    }
+  }
+  ```
+___
+
+### Introspection
+GraphQL APIs are self-documenting. Through introspection, you can query the API to retrieve details about its schema, including:
+
+- The list of **available types and fields**.
+- The **relationships** between those types. This capability is particularly useful for developing dynamic client applications and auto-generating documentation.
+
+  Developers might want to see what data structures are available. This makes it easy to explore document models and read models in Powerhouse without needing to consult extensive external documentation.
+
+  ```graphql title="Discovering Available Queries"
+  {
+    __schema {
+      types {
+        name
+        fields {
+          name
+        }
+      }
+    }
+  }
+  ```
+
+---
+### Connections, Edges, and Nodes
+When dealing with lists of data, GraphQL employs a pattern that includes:
+
+- **Connection**: A structure that represents a list of related objects.
+- **Edge**: Represents the link between individual nodes (objects) in a connection. Each edge contains:
+  - A node field (the actual object).
+  - A cursor for pagination.
+- **Node**: The individual object in the connection. When querying nodes, you continue selecting subfields until all the data resolves to scalar values.
+
+  To efficiently fetch invoices in Powerhouse, a paginated query could look like this.
+  This allows Powerhouse Switchboard to efficiently handle large datasets and return results incrementally
+
+  ```graphql title="Paginated List of Invoices"
+  query {
+    invoices(first: 10, after: "cursor123") {
+      edges {
+        node {
+          id
+          amount
+          dueDate
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+  ```
+
+---
+
+### Mutations
+- While queries retrieve data, **mutations modify data**. In Powerhouse, a contributor might need to submit an invoice after completing a task. A GraphQL mutation for this could be:
+
+    ```graphql title="Submitting an Invoice"
+    mutation {
+      submitInvoice(input: {
+        contributorId: "123"
+        amount: 500.00
+        currency: "USD"
+        dueDate: "2024-03-01"
+      }) {
+        id
+        status
+      }
+    }
+    ```
+
+---
+## Summary
+GraphQL offers a streamlined and efficient approach to data retrieval, particularly useful when you need granular control over your API interactions. By defining a robust schema, using precise fields and arguments, and leveraging introspection, GraphQL minimizes unnecessary data transfers. If you want to learn more about GraphQL, there is the following link to the official documentation: [Introduction to GraphQL](https://graphql.org/learn/).

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/03-WorkingWithSubgraphs/02-GraphQLAndSubgraphs.mdx

@@ -0,0 +1,119 @@
+# GraphQL and Subgraphs
+
+GraphQL plays a fundamental role in defining document model data schemas, handling data access patterns, and enabling event-driven workflows within the Powerhouse ecosystem.   
+This document provides an intro to graphQL and how it is used at Powerhouse when dealing with subgraphs
+
+More specifically, GraphQL is used as:
+- The **schema definition language (SDL)** for defining our document models and thereby self-documenting the API to the data model. It allows developers to define the structure and relationships of data in a strongly-typed format.
+- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically.
+
+
+## Powerhouse's use of GraphQL Subgraphs
+Powerhouse structures its data into subgraphs, which are modular GraphQL services that connect to the Reactor, Powerhouse's core data infrastructure, or Operational Data Stores fueled by data from a processor.
+
+### Fetching data from the Reactor
+
+Powerhouse uses GraphQL to expose system-level data, such as drives, users, and operational records.  
+Example: The **System Subgraph** allows querying of drives, stored files and folders.
+
+### Operational Data Stores
+
+Custom subgraphs can be created to store and retrieve operational data in real time.
+Example: A subgraph can track file uploads and expose this data via GraphQL queries.    ????
+
+??
+
+```graphql
+type File {
+  id: ID!
+  name: String!
+  size: Int!
+  createdAt: DateTime!
+}
+
+type Query {
+  getFile(id: ID!): File
+}
+```
+This schema ensures that every File entity has an ID, name, size, and timestamp.
+
+??
+
+In Powerhouse, each subgraph has its own SDL, ensuring modularity and flexibility while working within the ecosystem.
+
+## CQRS Breakdown
+
+Powerhouse uses CQRS to separate write operations (commands) from read operations (queries).   
+This improves system scalability and flexibility. 
+- GraphQL Queries handle read operations, retrieving structured data efficiently. 
+- GraphQL Mutations handle write operations, modifying the state in a controlled manner.
+
+Powerhouse's subgraphs act as the read layer, while processors handle write operations into operational data stores. This prevents conflicts between querying and modifying data.
+
+| Layer | Role | GraphQL Usage | Implementation |
+| --- | --- | --- | --- |
+| Write Model (Commands) | Handles state changes (adding, modifying, deleting) | GraphQL Mutations | Processor |
+| Read Model (Queries) | Optimized for fetching/reading/retrieving data | GraphQL Queries | Subgraph |
+
+### Read & Write Separation  
+**Read Model (Query)**  
+
+- Optimized for data retrieval
+- Structured using GraphQL Queries
+- Aggregates and exposes data via a subgraph
+- Pulls data from Operational Data Stores, Analytics Stores, and Reactor
+- Subgraphs do not directly modify the data—they only expose pre-processed information  
+
+
+
+```graphql title="Example of a Powerhouse Contributor schema in GraphQL"
+query {
+  getFile(id: "123") {
+    name
+    size
+  }
+}
+```
+
+**Write Model (Mutation)** 
+- Handles state changes (adding, modifying, deleting)
+- Structured using GraphQL Mutations
+- Writes data to Operational Data Stores
+
+```graphql title="Example of a Powerhouse Contributor schema in GraphQL"
+mutation {
+  createFile(name: "document.pdf", size: 1024) {
+    id
+    name
+  }
+}
+```
+
+### GraphQL & Event-Driven Architecture (EDA)
+Event-Driven Architecture (EDA) enables asynchronous processing where events trigger actions. Powerhouse uses GraphQL to expose real-time event data from its Reactor and Operational Data Stores.
+
+How GraphQL Fits into EDA
+- **Real-Time Data Exposure** – Subgraphs fetch event-based data updates.
+- **Event Subscription Mechanism** – Powerhouse is working towards integrating GraphQL Subscriptions for real-time updates.
+- **Efficient Decoupling** – Events are stored in an operational datastore, and GraphQL queries retrieve structured results.
+
+#### Example: Powerhouse's Event Flow
+1. Processor detects an event (e.g., file upload).
+2. Writes event data to the Operational Data Store.
+3. Subgraph exposes the updated data via GraphQL.
+
+
+## GraphQL Subscriptions
+Although Powerhouse currently uses queries and mutations, GraphQL Subscriptions could allow real-time streaming of event-based data.
+
+#### Example (future implementation):
+
+```graphql 
+subscription {
+  fileUploaded {
+    id
+    name
+  }
+}
+```
+This would enable clients to listen for new file uploads without polling.