{drive.header.slug}

; onAddFolder: ( name: string, parent: Node | undefined, ) => Promise; onRenameNode: (newName: string, node: Node) => Promise; onCopyNode: (src: Node, target: Node | undefined) => Promise; onMoveNode: (src: Node, target: Node | undefined) => Promise; onDuplicateNode: (src: Node) => Promise; onAddAndSelectNewFolder: (name: string) => Promise; }; ``` **Returned Functions:** | Function | Description | | ------------------------------- | ---------------------------------------------------------- | | `onAddFile(file, parent)` | Adds a file to the drive under the specified parent folder | | `onAddFolder(name, parent)` | Creates a new folder under the specified parent | | `onRenameNode(newName, node)` | Renames a node | | `onCopyNode(src, target)` | Copies a node to a target folder | | `onMoveNode(src, target)` | Moves a node to a target folder | | `onDuplicateNode(src)` | Duplicates a node in the current folder | | `onAddAndSelectNewFolder(name)` | Creates a new folder and selects it | **Example:** ```tsx useNodeActions, useSelectedFolder, } from "@powerhousedao/reactor-browser"; function FileUploader() { const { onAddFile, onAddFolder } = useNodeActions(); const selectedFolder = useSelectedFolder(); const handleFileUpload = async ( event: React.ChangeEvent, ) => { const file = event.target.files?.[0]; if (file) { await onAddFile(file, selectedFolder); } }; const handleCreateFolder = async () => { await onAddFolder("New Folder", selectedFolder); }; return (

); } ``` --- ## Modals ### `usePHModal` Returns the currently displayed modal. ```typescript function usePHModal(): PHModal | undefined; ``` **Modal Types:** ```typescript type PHModal = | { type: "createDocument"; documentType: string } | { type: "deleteItem"; id: string } | { type: "addDrive" } | { type: "upgradeDrive"; driveId: string } | { type: "deleteDrive"; driveId: string } | { type: "driveSettings"; driveId: string } | { type: "settings" } | { type: "clearStorage" } | { type: "debugSettings" } | { type: "disclaimer" } | { type: "cookiesPolicy" } | { type: "exportDocumentWithErrors"; documentId: string } | { type: "inspector" }; ``` --- ### `showPHModal` Shows a modal. ```typescript function showPHModal(modal: PHModal): void; ``` --- ### `closePHModal` Closes the currently displayed modal. ```typescript function closePHModal(): void; ``` --- ### `showCreateDocumentModal` Shows the create document modal for a specific document type. ```typescript function showCreateDocumentModal(documentType: string): void; ``` **Example:** ```tsx function CreateButton() { return ( ); } ``` --- ### `showDeleteNodeModal` Shows the delete confirmation modal for a node. ```typescript function showDeleteNodeModal(nodeOrId: Node | string): void; ``` **Parameters:** - `nodeOrId` — The node object or node ID to delete --- ## Revision History ### `useRevisionHistoryVisible` Returns whether the revision history panel is visible. ```typescript check function useRevisionHistoryVisible(): boolean | undefined; ``` --- ### `showRevisionHistory` Shows the revision history panel. ```typescript function showRevisionHistory(): void; ``` --- ### `hideRevisionHistory` Hides the revision history panel. ```typescript function hideRevisionHistory(): void; ``` --- ## Timeline ### `useSelectedTimelineItem` Returns the selected timeline item. ```typescript function useSelectedTimelineItem(): TimelineItem | null | undefined; ``` **Timeline Item Types:** ```typescript type TimelineBarItem = { id: string; type: "bar"; addSize?: 0 | 1 | 2 | 3 | 4; delSize?: 0 | 1 | 2 | 3 | 4; timestampUtcMs?: string; additions?: number; deletions?: number; revision?: number; startDate?: Date; endDate?: Date; }; type TimelineDividerItem = { id: string; type: "divider"; timestampUtcMs?: string; title?: string; subtitle?: string; revision?: number; startDate?: Date; endDate?: Date; }; type TimelineItem = TimelineBarItem | TimelineDividerItem; ``` --- ### `setSelectedTimelineItem` Sets the selected timeline item. ```typescript function setSelectedTimelineItem(item: TimelineItem | null | undefined): void; ``` --- ### `useSelectedTimelineRevision` Returns the selected timeline revision. ```typescript function useSelectedTimelineRevision(): string | number | null | undefined; ``` --- ### `setSelectedTimelineRevision` Sets the selected timeline revision. ```typescript function setSelectedTimelineRevision( revision: string | number | null | undefined, ): void; ``` --- ## Document Types ### `useDocumentTypes` Returns the document types a drive editor supports. Uses `allowedDocumentTypes` config if set, otherwise falls back to all supported document types from the reactor. ```typescript function useDocumentTypes(): string[] | undefined; ``` --- ### `useSupportedDocumentTypesInReactor` Returns the supported document types for the reactor, derived from the registered document model modules. ```typescript function useSupportedDocumentTypesInReactor(): string[] | undefined; ``` --- ## Vetra Packages ### `useVetraPackages` Returns all Vetra packages loaded by the Connect instance. ```typescript function useVetraPackages(): VetraPackage[] | undefined; ``` **VetraPackage Type:** ```typescript type VetraPackage = { id: string; name: string; description: string; category: string; author: Author; modules: { documentModelModules?: VetraDocumentModelModule[]; editorModules?: VetraEditorModule[]; subgraphModules?: SubgraphModule[]; importScriptModules?: ImportScriptModule[]; processorModules?: VetraProcessorModule[]; }; }; ``` --- ### `setVetraPackages` Sets the Vetra packages for the Connect instance. ```typescript function setVetraPackages(vetraPackages: VetraPackage[] | undefined): void; ``` --- ## Switchboard Link ### `useGetSwitchboardLink` Hook that returns a function to generate a document's switchboard URL. Only returns a function for documents in remote drives. Returns `null` for local drives or when the document/drive cannot be determined. The returned function generates a fresh bearer token and builds the switchboard URL with authentication when called. ```typescript function useGetSwitchboardLink( document: PHDocument | undefined, ): (() => Promise) | null; ``` **Parameters:** - `document` — The document to create a switchboard URL generator for **Returns:** An async function that returns the switchboard URL, or `null` if not applicable. **Example:** ```tsx useGetSwitchboardLink, useSelectedDocument, } from "@powerhousedao/reactor-browser"; function SwitchboardButton() { const [document] = useSelectedDocument(); const getSwitchboardLink = useGetSwitchboardLink(document); if (!getSwitchboardLink) { return null; // Not available for local drives } const handleClick = async () => { const url = await getSwitchboardLink(); window.open(url, "_blank"); }; return ; } ``` --- ## Editor Configuration ### `useIsExternalControlsEnabled` Gets whether external controls are enabled for a given editor. ```typescript function useIsExternalControlsEnabled(): boolean | undefined; ``` --- ### `setIsExternalControlsEnabled` Sets whether external controls are enabled for a given editor. ```typescript function setIsExternalControlsEnabled(enabled: boolean | undefined): void; ``` --- ### `useIsDragAndDropEnabled` Gets whether drag and drop is enabled for a given drive editor. ```typescript check function useIsDragAndDropEnabled(): boolean | undefined; ``` --- ### `setIsDragAndDropEnabled` Sets whether drag and drop is enabled for a given drive editor. ```typescript function setIsDragAndDropEnabled(enabled: boolean | undefined): void; ``` --- ### `useAllowedDocumentTypes` Defines the document types a drive supports. Defaults to all document types registered in the reactor. ```typescript function useAllowedDocumentTypes(): string[] | undefined; ``` --- ### `setAllowedDocumentTypes` Sets the allowed document types for a given drive editor. ```typescript function setAllowedDocumentTypes(types: string[] | undefined): void; ``` --- ## Config: Set by Object ### `setPHDriveEditorConfig` Sets the global drive editor config. Pass in a partial object of the config to set. ```typescript function setPHDriveEditorConfig(config: Partial): void; ``` **Config Options:** - `allowedDocumentTypes` — Array of allowed document type strings - `isDragAndDropEnabled` — Whether drag and drop is enabled --- ### `setPHDocumentEditorConfig` Sets the global document editor config. Pass in a partial object of the config to set. ```typescript function setPHDocumentEditorConfig( config: Partial, ): void; ``` **Config Options:** - `isExternalControlsEnabled` — Whether external controls are enabled --- ### `useSetPHDriveEditorConfig` Wrapper hook that automatically sets the global drive editor config when the component mounts. ```typescript function useSetPHDriveEditorConfig(config: Partial): void; ``` **Example:** ```tsx function MyDriveEditor() { useSetPHDriveEditorConfig({ isDragAndDropEnabled: true, allowedDocumentTypes: ["powerhouse/budget-statement", "powerhouse/invoice"], }); return

{/* editor content */}

; } ``` --- ### `useSetPHDocumentEditorConfig` Wrapper hook that automatically sets the global document editor config when the component mounts. ```typescript function useSetPHDocumentEditorConfig( config: Partial, ): void; ``` --- ## Config: Get by Key ### `usePHDriveEditorConfigByKey` Gets the value of an item in the global drive config for a given key. Strongly typed, inferred from type definition for the key. ```typescript function usePHDriveEditorConfigByKey( key: TKey, ): PHDriveEditorConfig[TKey]; ``` --- ### `usePHDocumentEditorConfigByKey` Gets the value of an item in the global document config for a given key. Strongly typed, inferred from type definition for the key. ```typescript function usePHDocumentEditorConfigByKey( key: TKey, ): PHDocumentEditorConfig[TKey]; ``` --- ## Step 1: Create Custom Scalars > Source: https://academy.vetra.io/academy/Reference/EditorsUI/CreateCustomScalars This tutorial provides step-by-step instructions for creating custom scalars & components, and to contributing to the document-engineering project. The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main) ### Creating New GraphQL Scalars GraphQL scalars are custom data types that define how data is validated, serialized, and parsed. This guide will walk you through creating a new scalar in the `src/scalars/graphql/` directory. ## Step 1: Create the Scalar File Create a new TypeScript file in `src/scalars/graphql/` for your scalar. Use `EmailAddress.ts` as a reference. **Example: Creating a `PhoneNumber.ts` scalar** ```typescript GraphQLError, GraphQLScalarType, type GraphQLScalarTypeConfig, Kind, } from "graphql"; export interface ScalarType { input: string; output: string; } export const type = "string"; // TS type in string form export const typedef = "scalar PhoneNumber"; export const schema = z .string() .regex(/^\+?[1-9]\d{1,14}$/, "Invalid phone number format"); export const stringSchema = 'z.string().regex(/^\\+?[1-9]\\d{1,14}$/, "Invalid phone number format")'; const phoneValidation = (value: unknown): string => { if (typeof value !== "string") { throw new GraphQLError(`Value is not string: ${JSON.stringify(value)}`); } const result = schema.safeParse(value); if (result.success) return result.data; throw new GraphQLError(result.error.message); }; export const config: GraphQLScalarTypeConfig = { name: "PhoneNumber", description: "A field whose value conforms to international phone number format.", serialize: phoneValidation, parseValue: phoneValidation, parseLiteral: (value) => { if (value.kind !== Kind.STRING) { throw new GraphQLError( `Can only validate strings as phone numbers but got a: ${value.kind}`, { nodes: value }, ); } return phoneValidation(value.value); }, }; export const scalar = new GraphQLScalarType(config); ``` ### Key Components to Update: 1. **`type`**: The TypeScript type (usually `'string'` for text-based scalars) 2. **`typedef`**: The GraphQL type definition (e.g., `'scalar PhoneNumber'`) 3. **`schema`**: Zod validation schema for your data type 4. **`stringSchema`**: String representation of the zod schema (used for code generation) 5. **Validation function**: Custom validation logic for your scalar 6. **`config.name`**: The name of your scalar (must match the typedef) 7. **`config.description`**: Human-readable description of the scalar ## Step 2: Register the Scalar in `scalars.ts` After creating your scalar file, you need to register it in `src/scalars/graphql/scalars.ts`. This involves updating multiple sections of the file. The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main) ### 2.1 Add Namespace Import Add your scalar to the namespace imports section (around line 2): ```typescript // namespace imports -- DO NOT REMOVE OR EDIT THIS COMMENT // ... other imports ... ``` ### 2.2 Add Type Export Add the type export (around line 22): ```typescript // export types -- DO NOT REMOVE OR EDIT THIS COMMENT export type { ScalarType as AmountScalarType } from "./Amount.js"; // ... other type exports ... export type { ScalarType as PhoneNumberScalarType } from "./PhoneNumber.js"; // ADD THIS LINE export type { ScalarType as URLScalarType } from "./URL.js"; ``` ### 2.3 Add to Export Object Add your scalar to the main export object (around line 40): ```typescript export { Amount, AmountCrypto, // ... other exports ... PhoneNumber, // ADD THIS LINE URLScalar, }; ``` ### 2.4 Add to Custom Scalars Add your scalar to the `customScalars` object (around line 54): ```typescript export const customScalars: Record> = { // ... other scalars ... PhoneNumber, // ADD THIS LINE URLScalar, } as const; ``` #### 2.5 Add to Resolvers Add your scalar to the `resolvers` object (around line 74): ```typescript export const resolvers = { // export resolvers -- DO NOT REMOVE OR EDIT THIS COMMENT AmountTokens: AmountTokens.scalar, // ... other resolvers ... PhoneNumber: PhoneNumber.scalar, // ADD THIS LINE Amount: Amount.scalar, }; ``` ### 2.6 Add to Type Definitions Add your typedef to the `typeDefs` array (around line 90): ```typescript export const typeDefs = [ // export typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT AmountTokens.typedef, // ... other typedefs ... PhoneNumber.typedef, // ADD THIS LINE Amount.typedef, ]; ``` ### 2.7 Add to Generator Type Definitions Add your scalar to the `generatorTypeDefs` object (around line 105): ```typescript export const generatorTypeDefs = { // export generator typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT [AmountTokens.config.name]: AmountTokens.type, // ... other entries ... [PhoneNumber.config.name]: PhoneNumber.type, // ADD THIS LINE [Amount.config.name]: Amount.type, }; ``` ### 2.8 Add to Validation Schema Add your scalar to the `validationSchema` object (around line 120): ```typescript export const validationSchema = { // export validation schema -- DO NOT REMOVE OR EDIT THIS COMMENT [AmountTokens.config.name]: AmountTokens.stringSchema, // ... other entries ... [PhoneNumber.config.name]: PhoneNumber.stringSchema, // ADD THIS LINE [Amount.config.name]: Amount.stringSchema, }; ``` ## Step 3: Create Tests for Your Scalar Every scalar must have comprehensive tests to ensure it works correctly. Create a test file in `src/scalars/graphql/test/` following the naming convention `YourScalar.test.ts`. **Example: Creating `PhoneNumber.test.ts`** ```typescript describe("PhoneNumber Scalar", () => { it("should serialize a phone number", () => { const phoneNumber = "+1234567890"; expect(scalar.serialize(phoneNumber)).toBe(phoneNumber); }); it("should throw an error if the value is not a string", () => { const phoneNumber = 123; expect(() => scalar.serialize(phoneNumber)).toThrow(); }); it("should throw an error if the value is not a valid phone number", () => { const phoneNumber = "invalid-phone"; expect(() => scalar.serialize(phoneNumber)).toThrow(); }); it("should parse a valid phone number", () => { const phoneNumber = "+1234567890"; expect(scalar.parseValue(phoneNumber)).toBe(phoneNumber); }); it("should throw an error if parse a value that is not a valid phone number", () => { const phoneNumber = "invalid-phone"; expect(() => scalar.parseValue(phoneNumber)).toThrow(); }); it("should throw an error if parse a value that is not a string", () => { const phoneNumber = 123; expect(() => scalar.parseValue(phoneNumber)).toThrow(); }); it("should parse a valid phone number from a literal", () => { const phoneNumber = "+1234567890"; expect( scalar.parseLiteral({ kind: Kind.STRING, value: phoneNumber, }), ).toBe(phoneNumber); }); it("should throw an error if parse a literal that is not a valid phone number", () => { const phoneNumber = "invalid-phone"; expect(() => scalar.parseLiteral({ kind: Kind.STRING, value: phoneNumber, }), ).toThrow(); }); it("should throw an error if parse a literal that is not a string", () => { const phoneNumber = "+1234567890"; expect(() => scalar.parseLiteral({ kind: Kind.INT, value: phoneNumber, }), ).toThrow(); }); }); ``` #### Required Test Cases Your scalar tests should cover these essential scenarios: ##### Serialization Tests - ✅ **Valid values**: Test that valid inputs are serialized correctly - ❌ **Invalid types**: Test that non-string inputs throw errors - ❌ **Invalid format**: Test that strings not matching your validation throw errors ##### Parse Value Tests - ✅ **Valid values**: Test that valid inputs are parsed correctly - ❌ **Invalid format**: Test that invalid strings throw errors - ❌ **Invalid types**: Test that non-string inputs throw errors ##### Parse Literal Tests - ✅ **Valid STRING literals**: Test that valid string literals are parsed correctly - ❌ **Invalid STRING literals**: Test that invalid string literals throw errors - ❌ **Non-STRING literals**: Test that non-string literal kinds (INT, FLOAT, etc.) throw errors #### Testing Best Practices 1. **Test edge cases**: Include boundary values and common invalid inputs 2. **Test multiple valid formats**: If your scalar accepts different valid formats, test them all 3. **Use descriptive test names**: Make it clear what each test is validating 4. **Follow the naming convention**: `YourScalar.test.ts` in the `test/` directory #### Example Edge Cases for Different Scalar Types **String-based scalars (like PhoneNumber):** ```typescript // Test empty string expect(() => scalar.parseValue("")).toThrow(); // Test too long/short values expect(() => scalar.parseValue("123")).toThrow(); expect(() => scalar.parseValue("+" + "1".repeat(20))).toThrow(); // Test special characters expect(() => scalar.parseValue("+1-234-567-890")).not.toThrow(); ``` **Number-based scalars:** ```typescript // Test zero expect(scalar.parseValue(0)).toBe(0); // Test negative numbers expect(() => scalar.parseValue(-1)).toThrow(); // Test decimal numbers expect(scalar.parseValue(123.45)).toBe(123.45); ``` **Date-based scalars:** ```typescript // Test valid ISO date expect(scalar.parseValue("2023-12-25T00:00:00Z")).toBe("2023-12-25T00:00:00Z"); // Test invalid date format expect(() => scalar.parseValue("25/12/2023")).toThrow(); ``` ## Step 4: Validate Your Implementation After implementing your scalar and tests, make sure to: 1. **Run the tests** to ensure they all pass 2. **Build the project** to ensure there are no TypeScript errors 3. **Test GraphQL queries** that use your new scalar 4. **Verify code generation** works with your new scalar ### Common Scalar Types Here are some common patterns for different types of scalars: #### String-based Scalars ```typescript export const type = "string"; export const schema = z.string().min(1).max(100); ``` #### Number-based Scalars ```typescript export const type = "number"; export const schema = z.number().positive(); ``` #### Date-based Scalars ```typescript export const type = "string"; export const schema = z.string().datetime(); ``` **INFO:** **Contributing and UI for Scalars** - **Open Source**: Please submit contributions as a pull request to the Powerhouse team. - **UI is Optional but Helpful**: A design or UI for your scalar isn't required, but it helps reviewers understand its purpose. - **Semantic Scalars**: Some scalars don't need a unique UI. For instance, `Title` and `Description` might both use a simple text input but serve a semantic role by adding specific meaning and validation to the schema. ::: ### Tips - Always follow the naming convention: use PascalCase for scalar names - Include meaningful validation in your Zod schema - Write clear, descriptive error messages - Keep the `stringSchema` in sync with your `schema` definition - Test edge cases in your validation function - Update all required sections in `scalars.ts` --- ## Renown SDK > Source: https://academy.vetra.io/academy/Reference/Authorization/renown-sdk/Overview A comprehensive SDK for integrating Renown authentication and user profile management into your React applications. ## Features - 🔐 **Authentication** - Complete authentication flow with session management - 👤 **User Profiles** - Fetch and manage user profile data - ⚛️ **React Integration** - Provider and hooks for seamless React integration - 🎨 **UI Component** - Ready-to-use RenownAuthButton component - 🔄 **Session Persistence** - Automatic session restoration across page reloads - 🌐 **Renown Portal** - Easy integration with Renown authentication portal - 📦 **Type-Safe** - Full TypeScript support - 🎯 **Headless** - Customizable UI with optional render props ## Installation ```bash npm install @renown/sdk # or yarn add @renown/sdk # or pnpm add @renown/sdk ``` ## Quick Start ### 1. Wrap Your App with RenownUserProvider The RenownUserProvider automatically initializes the SDK - no manual setup needed! ```typescript // app/layout.tsx or app.tsx export default function RootLayout({ children }) { return ( {children} ) } ``` Optional: Customize with loading/error components: ```typescript

Initializing...

} errorComponent={(error, retry) => (

Failed to initialize

{error.message}

)} > {children} ``` ### 2. Use Authentication in Components ```typescript // components/Header.tsx export function Header() { return (

My App

) } ``` Or use the `useUser` hook for custom implementations: ```typescript // components/CustomAuth.tsx export function CustomAuth() { const { user, loginStatus, openRenown, logout } = useUser() if (user) { return (

Welcome, {user.name || user.did}

) } return } ``` ## Documentation Structure - **[Authentication Guide](../docs/docs/01-Authentication.md)** - Comprehensive guide to implementing authentication - **[API Reference](../docs/docs/02-APIReference.md)** - Complete API documentation ## Key Concepts ### RenownUserProvider The `` component is the central authentication provider that manages auth state across your application. It must wrap your application to provide authentication context. ### useUser Hook The `useUser()` hook provides access to authentication state and methods throughout your application. It can only be used within a ``. The hook returns `connectCrypto` and `renown` instances for advanced use cases. ### Session Management The SDK automatically manages user sessions using sessionStorage, allowing users to stay logged in across page reloads within the same browser session. ### Profile Data User profile data is automatically fetched from the Renown API after successful authentication, enriching the user object with display name, avatar, and other profile information. ### UI Component The SDK provides a ready-to-use component: - **RenownAuthButton** - Smart component that adapts to auth state (shows login button or user info) This component is optional - you can build your own UI using the `useUser` hook. ## Examples ### Next.js App Router ```typescript // app/layout.tsx - Minimal setup export default function RootLayout({ children }) { return ( {children} ) } // components/Navbar.tsx - Using RenownAuthButton component 'use client' export function Navbar() { return ( ) } // app/profile/page.tsx - Using useUser hook 'use client' export default function ProfilePage() { const { user, openRenown, logout } = useUser() if (!user) { return (

Login Required

) } return (

Profile

DID: {user.did}

Name: {user.name}

{user.avatar &&

}

) } ``` ### React SPA ```typescript // main.tsx ReactDOM.createRoot(document.getElementById('root')!).render( ) // App.tsx - Using RenownAuthButton function App() { return (

My App

) } // Or custom with useUser hook function CustomApp() { const { user, openRenown } = useUser() return (

{user ? (

Welcome {user.name}

) : ( )}

) } ``` ## Configuration ### RenownUserProvider Props Customize the Renown SDK initialization: ```typescript } // Custom loading screen errorComponent={(error, retry) => } // Custom error screen > ``` All props are optional - RenownUserProvider uses sensible defaults. ### Environment Variables You can use environment variables for configuration: ```typescript ``` ```bash # .env NEXT_PUBLIC_RENOWN_URL=https://www.renown.id ``` ## Troubleshooting ### Context Error **Error:** `useUser must be used within a RenownUserProvider` **Solution:** Ensure your component is wrapped by ``: ```typescript {/* ✅ Can use useUser */} ``` ### Custom Renown URL If you need to use a different Renown instance: ```typescript ``` ## Resources - [GitHub Repository](https://github.com/powerhouse-inc/powerhouse) - [NPM Package](https://www.npmjs.com/package/@renown/sdk) - [Renown Portal](https://www.renown.id) ## License AGPL-3.0-only --- ## Authentication Guide > Source: https://academy.vetra.io/academy/Reference/Authorization/renown-sdk/Authentication Comprehensive guide to implementing authentication with the Renown SDK. ## Table of Contents - [Overview](#overview) - [Authentication Flow](#authentication-flow) - [Setup](#setup) - [Implementation](#implementation) - [Advanced Patterns](#advanced-patterns) - [Security Considerations](#security-considerations) ## Overview The Renown SDK provides a complete authentication system that: 1. **Auto-initializes** the Renown SDK and ConnectCrypto (zero configuration!) 2. **Manages** user sessions across page reloads 3. **Handles** authentication redirects from Renown portal 4. **Fetches** user profile data automatically 5. **Provides** React hooks, components, and context for easy integration ## Authentication Flow ### 1. Initial Load ``` User visits app ↓ RenownUserProvider initializes ↓ Check sessionStorage for existing session ↓ ├─ Session found → Restore user → Authorized └─ No session → Check URL params → Initialize SDK → Not Authorized ``` ### 2. Login Flow ``` User clicks "Login" ↓ openRenown() called ↓ Redirect to Renown Portal ↓ User authenticates ↓ Redirect back to app with DID ↓ handleRenownReturn() processes ↓ login() called ↓ Fetch user profile ↓ Store in sessionStorage ↓ Update auth state → Authorized ``` ### 3. Session Restoration ``` User refreshes page ↓ RenownUserProvider checks sessionStorage ↓ Valid session found ↓ Fetch latest profile data ↓ Restore auth state → Authorized ``` ## Setup ### Step 1: Wrap Your App with RenownUserProvider The RenownUserProvider automatically initializes the Renown SDK - no manual setup required! ```typescript // app/layout.tsx (Next.js App Router) export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( {children} ) } ``` That's it! The SDK is now initialized and ready to use. ### Optional: Customize Configuration You can customize the Renown URL, network, and chain: ```typescript {children} ``` ### Optional: Add Loading/Error Screens Provide custom UI for initialization states: ```typescript

Initializing authentication...

} errorComponent={(error, retry) => (

Authentication Failed

{error.message}

)} > {children} ``` ## Implementation ### Using the RenownAuthButton Component The simplest way to add authentication is to use the built-in `RenownAuthButton` component: ```typescript 'use client' export function Header() { return (

My App

) } ``` ### Custom Login Component with useUser Hook For full control, build your own component using the `useUser` hook: ```typescript 'use client' export function CustomRenownAuthButton() { const { user, loginStatus, isLoading, openRenown, logout } = useUser() if (isLoading) { return ( ) } if (loginStatus === 'authorized' && user) { return (

{user.avatar && (

)} {user.name || user.did.slice(0, 15)}...

) } return ( ) } ``` ### Protected Route Component ```typescript 'use client' export function ProtectedRoute({ children }: { children: React.ReactNode }) { const { user, loginStatus, isLoading, openRenown } = useUser() const router = useRouter() useEffect(() => { if (!isLoading && loginStatus !== 'authorized') { // Redirect to login or show login prompt router.push('/login') } }, [isLoading, loginStatus, router]) if (isLoading) { return

} if (loginStatus !== 'authorized' || !user) { return (

Authentication Required

Please log in to access this page

) } return <>{children} } ``` ### User Profile Display ```typescript 'use client' export function UserProfile() { const { user, logout } = useUser() if (!user) return null return (

{user.avatar && (

)}

{user.name || 'Anonymous User'}

DID: {user.did}
Ethereum Address: {user.ethAddress}
Email: {user.email}

) } ``` ## Advanced Patterns ### Conditional Navigation Based on Auth ```typescript 'use client' export function Navigation() { const { user, loginStatus } = useUser() const isAuthorized = loginStatus === 'authorized' return ( ) } ``` ### Auth State Listener ```typescript "use client"; export function AuthStateListener() { const { user, loginStatus } = useUser(); const router = useRouter(); useEffect(() => { if (loginStatus === "authorized" && user) { // User just logged in toast.success(`Welcome back, ${user.name || "User"}!`); // Track analytics analytics.identify(user.did, { name: user.name, ethAddress: user.ethAddress, }); // Redirect to dashboard router.push("/dashboard"); } }, [loginStatus, user, router]); useEffect(() => { if (loginStatus === "not-authorized") { // User logged out toast.info("You have been logged out"); // Clear analytics analytics.reset(); // Redirect to home router.push("/"); } }, [loginStatus, router]); return null; // This is a listener component } ``` ### Custom Auth Hook with Additional Logic ```typescript "use client"; interface ExtendedAuthState { user: User | null; isAuthenticated: boolean; isLoading: boolean; hasCompletedProfile: boolean; login: () => void; logout: () => Promise; } export function useUser(): ExtendedAuthState { const auth = useRenownAuth(); const [hasCompletedProfile, setHasCompletedProfile] = useState(false); useEffect(() => { if (auth.user) { // Check if user has completed their profile const isComplete = !!( auth.user.name && auth.user.avatar && auth.user.email ); setHasCompletedProfile(isComplete); } else { setHasCompletedProfile(false); } }, [auth.user]); return { user: auth.user, isAuthenticated: auth.loginStatus === "authorized", isLoading: auth.isLoading, hasCompletedProfile, login: auth.openRenown, logout: auth.logout, }; } ``` ### Role-Based Access Control ```typescript 'use client' interface RBACProps { children: ReactNode allowedRoles?: string[] fallback?: ReactNode } export function RoleBasedAccess({ children, allowedRoles = [], fallback =

Access Denied

}: RBACProps) { const { user, loginStatus } = useUser() if (loginStatus !== 'authorized' || !user) { return fallback } // Check user roles (you'd fetch this from your backend) const userRoles = getUserRoles(user.did) // Implement this const hasAccess = allowedRoles.length === 0 || allowedRoles.some(role => userRoles.includes(role)) return hasAccess ? <>{children} : fallback } // Usage function AdminPanel() { return (

Admin Panel

{/* Admin content */} ) } ``` ## Security Considerations ### 1. Token Storage The SDK stores session data in `sessionStorage` (not `localStorage`) for security: - ✅ Session data clears when tab closes - ✅ Not accessible across tabs - ✅ Not persisted across browser sessions - ✅ Protected from XSS via httpOnly (for API tokens) ### 2. DID Validation Always validate DIDs before processing: ```typescript function isValidDID(did: string): boolean { // Must start with did:pkh: if (!did.startsWith("did:pkh:")) return false; // Must have correct number of parts const parts = did.split(":"); if (parts.length !== 5) return false; // Validate ethereum address format const address = parts[4]; if (!address.match(/^0x[a-fA-F0-9]{40}$/)) return false; return true; } ``` ### 3. Secure Communication Always use HTTPS for Renown URLs: ```typescript const RENOWN_URL = process.env.NEXT_PUBLIC_RENOWN_URL; if (RENOWN_URL && !RENOWN_URL.startsWith("https://")) { console.warn("WARNING: Renown URL should use HTTPS"); } ``` ### 4. Session Timeout Implement session timeout for security: ```typescript const SESSION_TIMEOUT = 24 * 60 * 60 * 1000; // 24 hours function isSessionValid(timestamp: number): boolean { const now = Date.now(); const age = now - timestamp; return age < SESSION_TIMEOUT; } ``` ### 5. Server-Side Verification **Never trust client-side auth alone**. Always verify on the server: ```typescript // Server-side API route export async function GET(request: Request) { const authHeader = request.headers.get("authorization"); if (!authHeader) { return new Response("Unauthorized", { status: 401 }); } // Verify the JWT/credential with Renown const isValid = await verifyRenownCredential(authHeader); if (!isValid) { return new Response("Invalid credentials", { status: 403 }); } // Proceed with authorized request return Response.json({ data: "Protected data" }); } ``` ## Best Practices ### 1. Handle Loading States Always handle loading states to provide good UX: ```typescript function MyComponent() { const { user, isLoading, loginStatus } = useUser() if (isLoading) { return // Show skeleton/spinner } // Now safe to use user/loginStatus } ``` ### 2. Graceful Degradation Provide fallbacks for unauthenticated users: ```typescript function FeatureSection() { const { user } = useUser() return (

{user ? ( ) : ( )}

) } ``` ### 3. Cleanup on Unmount Clean up subscriptions and listeners: ```typescript useEffect(() => { const handleAuthChange = () => { // Handle auth changes }; // Subscribe to auth events const unsubscribe = subscribeToAuthEvents(handleAuthChange); return () => { unsubscribe(); // Cleanup }; }, []); ``` ### 4. Error Boundaries Wrap auth components in error boundaries: ```typescript }> ``` ## Troubleshooting ### Issue: Auth state not updating **Cause:** Component not re-rendering when auth changes **Solution:** Ensure you're using `useUser()` hook, not accessing `window.renown` directly ```typescript // ❌ Wrong const user = window.renown?.user; // ✅ Correct const { user } = useUser(); ``` ### Issue: Session not persisting **Cause:** SessionStorage might be disabled or cleared **Solution:** Check browser settings and handle gracefully ```typescript try { SessionStorageManager.setUserData(data); } catch (error) { console.warn("SessionStorage not available:", error); // Fallback to in-memory storage } ``` ### Issue: Multiple login popups **Cause:** `openRenown()` called multiple times **Solution:** Debounce the login button ```typescript const handleLogin = useCallback( debounce(() => { openRenown(); }, 1000), [openRenown], ); ``` ## Next Steps - Read the [API Reference](../docs/docs/02-APIReference.md) for detailed documentation --- ## API Reference > Source: https://academy.vetra.io/academy/Reference/Authorization/renown-sdk/APIReference Complete API reference for the Renown SDK. ## Table of Contents - [Components](#components) - [Hooks](#hooks) - [Functions](#functions) - [Types](#types) - [Classes](#classes) - [Constants](#constants) ## Components ### `RenownUserProvider` Central authentication provider that automatically initializes the Renown SDK. #### Props ```typescript interface RenownUserProviderProps { children: React.ReactNode; renownUrl?: string; networkId?: string; chainId?: string; loadingComponent?: React.ReactNode; errorComponent?: (error: Error, retry: () => void) => React.ReactNode; } ``` | Prop | Type | Default | Description | | ------------------ | ----------------------------- | ------------------------- | --------------------------------------- | | `children` | `React.ReactNode` | - | **Required.** Child components | | `renownUrl` | `string` | `'https://www.renown.id'` | Renown service URL | | `networkId` | `string` | `'eip155'` | Network identifier | | `chainId` | `string` | `'1'` | Chain identifier | | `loadingComponent` | `React.ReactNode` | undefined | Custom loading UI during initialization | | `errorComponent` | `(error, retry) => ReactNode` | undefined | Custom error UI if initialization fails | #### Example **Basic usage (auto-initializes with defaults):** ```typescript ``` **With custom configuration:** ```typescript

Initializing...

} errorComponent={(error, retry) => (

Failed to initialize

{error.message}

)} > ``` #### Behavior - **Automatically initializes** Renown SDK and ConnectCrypto on mount - Creates global `window.renown` and `window.connectCrypto` instances - Checks sessionStorage for existing sessions - Handles Renown authentication redirects - Shows `loadingComponent` during initialization (if provided) - Shows `errorComponent` if initialization fails (if provided) - If no custom components provided, renders children immediately - Provides auth context to all children --- ### `RenownAuthButton` Smart button component that adapts based on authentication state. #### Props ```typescript interface RenownAuthButtonProps { className?: string; profileBaseUrl?: string; renderAuthenticated?: (props: RenownAuthButtonRenderProps) => React.ReactNode; renderUnauthenticated?: (props: { openRenown: () => void; isLoading: boolean; }) => React.ReactNode; renderLoading?: () => React.ReactNode; showUsername?: boolean; showLogoutButton?: boolean; logoutButtonText?: string; } ``` | Prop | Type | Default | Description | | ----------------------- | ---------- | --------------------------------- | ---------------------------- | | `className` | `string` | `""` | Custom CSS class | | `profileBaseUrl` | `string` | `"https://www.renown.id/profile"` | Base URL for profile | | `renderAuthenticated` | `function` | Default renderer | Custom authenticated state | | `renderUnauthenticated` | `function` | Default renderer | Custom unauthenticated state | | `renderLoading` | `function` | Default renderer | Custom loading state | | `showUsername` | `boolean` | `true` | Show username next to avatar | | `showLogoutButton` | `boolean` | `false` | Show logout button | | `logoutButtonText` | `string` | `"Logout"` | Logout button text | #### Example ```typescript // Basic usage // Custom rendering (

{user.name}

)} renderUnauthenticated={({ openRenown }) => ( )} /> ``` --- ### `RenownLoginButton` A login button with Renown branding. By default, clicking the button triggers login directly. Optionally shows a popover with connect option. #### Props ```typescript interface RenownLoginButtonProps { onLogin: (() => void) | undefined; darkMode?: boolean; style?: CSSProperties; className?: string; renderTrigger?: (props: { onMouseEnter: () => void; onMouseLeave: () => void; isLoading: boolean; }) => ReactNode; showPopover?: boolean; } ``` | Prop | Type | Default | Description | | --------------- | ------------------------- | ------- | ----------------------------------------------------------------------- | | `onLogin` | `() => void \| undefined` | - | Callback when login is requested | | `darkMode` | `boolean` | `false` | Enable dark mode styling | | `style` | `CSSProperties` | - | Custom styles for the button | | `className` | `string` | - | Custom class name | | `renderTrigger` | `function` | - | Custom render function for the trigger button | | `showPopover` | `boolean` | `false` | Show a popover with connect option instead of triggering login directly | #### Example ```typescript // Direct login (default) - clicks trigger onLogin immediately // With popover - shows hover popover with "Connect" button // Dark mode // Custom trigger ( )} /> ``` --- ## Hooks ### `useUser()` Access authentication state and methods. #### Returns ```typescript interface RenownUserContextValue { user: User | null; loginStatus: LoginStatus; isLoading: boolean; isInitialized: boolean; login: (userDid?: string) => Promise; logout: () => Promise; openRenown: () => void; connectCrypto: IConnectCrypto | null; renown: IRenown | null; } ``` | Property | Type | Description | | --------------- | ------------------------ | --------------------------------------------------- | | `user` | `User \| null` | Current authenticated user or null | | `loginStatus` | `LoginStatus` | Current authentication status | | `isLoading` | `boolean` | Whether an auth operation is in progress | | `isInitialized` | `boolean` | Whether the auth system has initialized | | `login` | `function` | Authenticate with optional DID | | `logout` | `function` | Log out current user | | `openRenown` | `function` | Open Renown authentication portal | | `connectCrypto` | `IConnectCrypto \| null` | ConnectCrypto instance for cryptographic operations | | `renown` | `IRenown \| null` | Renown SDK instance | #### Example ```typescript function MyComponent() { const { user, loginStatus, isLoading, login, logout, openRenown, connectCrypto, renown } = useUser() if (isLoading) return

if (!user) return return } ``` #### Throws Throws an error if used outside of ``: ``` Error: useUser must be used within a RenownUserProvider ``` --- ## Functions ### `initRenown()` Initialize the Renown SDK. #### Signature ```typescript function initRenown( did: string, networkId: string, renownUrl: string, ): Promise; ``` #### Parameters | Parameter | Type | Description | | ----------- | -------- | ----------------------------------- | | `did` | `string` | Decentralized identifier (DID) | | `networkId` | `string` | Network identifier (e.g., 'eip155') | | `renownUrl` | `string` | Renown service URL | #### Returns `Promise` - Initialized Renown instance #### Example ```typescript const renown = await initRenown( "did:pkh:eip155:1:0x123...", "eip155", "https://www.renown.id", ); ``` --- ### `login()` Authenticate a user with Renown. #### Signature ```typescript function login( userDid: string | undefined, renown: IRenown | undefined, connectCrypto: IConnectCrypto | undefined, ): Promise; ``` #### Parameters | Parameter | Type | Description | | --------------- | ----------------------------- | -------------------------- | | `userDid` | `string \| undefined` | User's DID to authenticate | | `renown` | `IRenown \| undefined` | Renown instance | | `connectCrypto` | `IConnectCrypto \| undefined` | ConnectCrypto instance | #### Returns `Promise` - Authenticated user or undefined #### Side Effects - Stores user session in sessionStorage - Fetches user profile data - Updates auth state #### Example ```typescript const user = await login( "did:pkh:eip155:1:0x123...", window.renown, window.connectCrypto, ); ``` --- ### `logout()` Log out the current user. #### Signature ```typescript function logout(): Promise; ``` #### Returns `Promise` #### Side Effects - Clears sessionStorage - Calls renown.logout() - Removes JWT handler #### Example ```typescript await logout(); ``` --- ### `openRenown()` Open the Renown authentication portal. #### Signature ```typescript function openRenown(): void; ``` #### Returns `void` #### Behavior - Constructs authentication URL with current DID - Adds network and chain parameters - Sets return URL to current location - Redirects to Renown portal #### Example ```typescript function MyLoginButton() { return } // Or use the built-in RenownAuthButton component function Header() { return } ``` --- ### `handleRenownReturn()` Process authentication redirect from Renown. #### Signature ```typescript function handleRenownReturn(): Promise; ``` #### Returns `Promise` #### Behavior - Checks URL for authentication parameters - Extracts user DID from query string - Calls login with the DID - Cleans up URL parameters #### Example ```typescript // Called automatically by UserProvider useEffect(() => { handleRenownReturn(); }, []); ``` --- ### `fetchProfileDataForUser()` Fetch user profile data from Renown API. #### Signature ```typescript function fetchProfileDataForUser(user: User): Promise; ``` #### Parameters | Parameter | Type | Description | | --------- | ------ | --------------------------------------- | | `user` | `User` | User object to enrich with profile data | #### Returns `Promise` - User with profile data #### Behavior - Extracts ETH address from user's DID - Calls Renown profile API - Enriches user object with profile data (name, avatar, etc.) - Returns original user if profile not found #### Example ```typescript const userWithProfile = await fetchProfileDataForUser(user); console.log(userWithProfile.name); // Display name console.log(userWithProfile.avatar); // Avatar URL ``` --- ### `reauthenticateFromSession()` Restore authentication from stored session. #### Signature ```typescript function reauthenticateFromSession(): Promise; ``` #### Returns `Promise` - Restored user or null #### Behavior - Checks for stored session in sessionStorage - Calls login with stored DID - Fetches fresh profile data - Returns null if session invalid or expired #### Example ```typescript const user = await reauthenticateFromSession(); if (user) { console.log("Session restored for:", user.did); } ``` --- ### `extractEthAddressFromDid()` Extract Ethereum address from a DID. #### Signature ```typescript function extractEthAddressFromDid(did: string): string | null; ``` #### Parameters | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------- | | `did` | `string` | DID string (e.g., 'did:pkh:eip155:1:0x123...') | #### Returns `string | null` - Ethereum address or null if invalid #### Example ```typescript const address = extractEthAddressFromDid("did:pkh:eip155:1:0x1234..."); console.log(address); // '0x1234...' ``` --- ## Types ### `User` Represents an authenticated user. ```typescript interface User { did: string; // Decentralized identifier address: string; // Ethereum address name?: string; // Display name from profile email?: string; // Email address avatar?: string; // Avatar image URL ethAddress?: string; // Ethereum address (duplicate of address) } ``` --- ### `LoginStatus` Authentication status enumeration. ```typescript type LoginStatus = | "initial" // Not yet checked | "checking" // Currently checking auth | "authorized" // User is authenticated | "not-authorized"; // User is not authenticated ``` --- ### `RenownUserContextValue` Type for the authentication context value. ```typescript interface RenownUserContextValue { user: User | null; loginStatus: LoginStatus; isLoading: boolean; isInitialized: boolean; login: (userDid?: string) => Promise; logout: () => Promise; openRenown: () => void; connectCrypto: IConnectCrypto | null; renown: IRenown | null; } ``` --- ### `IRenown` Interface for the Renown instance. ```typescript interface IRenown { user: User | undefined | (() => Promise); login: (did: string) => Promise; logout: () => Promise; on: (event: string, handler: Function) => Unsubscribe; } ``` --- ### `IConnectCrypto` Interface for the ConnectCrypto instance. ```typescript interface IConnectCrypto { did: () => Promise; // Additional methods... } ``` --- ## Classes ### `ConnectCrypto` Manages cryptographic operations and DID generation. #### Constructor ```typescript constructor(keyStorage: IKeyStorage) ``` #### Parameters | Parameter | Type | Description | | ------------ | ------------- | -------------------------- | | `keyStorage` | `IKeyStorage` | Key storage implementation | #### Methods ##### `did()` Get the DID for the current key. ```typescript async did(): Promise ``` **Returns:** `Promise` - The DID **Example:** ```typescript const connectCrypto = new ConnectCrypto(new BrowserKeyStorage()); const did = await connectCrypto.did(); console.log(did); // 'did:pkh:eip155:1:0x...' ``` --- ### `BrowserKeyStorage` Browser-based key storage using IndexedDB. #### Constructor ```typescript constructor(); ``` #### Usage ```typescript const keyStorage = new BrowserKeyStorage(); const connectCrypto = new ConnectCrypto(keyStorage); ``` --- ### `SessionStorageManager` Manages user session persistence. #### Static Methods ##### `setUserData()` Store user session data. ```typescript static setUserData(data: { user: User userDid: string loginStatus: LoginStatus timestamp: number }): void ``` **Example:** ```typescript SessionStorageManager.setUserData({ user: currentUser, userDid: currentUser.did, loginStatus: "authorized", timestamp: Date.now(), }); ``` ##### `getUserData()` Retrieve stored user session. ```typescript static getUserData(): { user: User userDid: string loginStatus: LoginStatus timestamp: number } | null ``` **Returns:** Session data or null **Example:** ```typescript const session = SessionStorageManager.getUserData(); if (session) { console.log("Found session for:", session.user.did); } ``` ##### `clearUserData()` Clear stored session. ```typescript static clearUserData(): void ``` **Example:** ```typescript SessionStorageManager.clearUserData(); ``` ##### `isUserDataValid()` Check if session data is valid. ```typescript static isUserDataValid(data: { user: User userDid: string loginStatus: LoginStatus timestamp: number }): boolean ``` **Returns:** `boolean` - Whether session is valid **Example:** ```typescript const data = SessionStorageManager.getUserData(); if (data && SessionStorageManager.isUserDataValid(data)) { // Session is valid } ``` ##### `getStoredUserDid()` Get stored user DID. ```typescript static getStoredUserDid(): string | null ``` **Returns:** `string | null` - Stored DID or null --- ## Constants ### `RENOWN_URL` Default Renown service URL. ```typescript const RENOWN_URL: string = "https://www.renown.id"; ``` --- ### `RENOWN_NETWORK_ID` Default network identifier. ```typescript const RENOWN_NETWORK_ID: string = "eip155"; ``` --- ### `RENOWN_CHAIN_ID` Default chain identifier. ```typescript const RENOWN_CHAIN_ID: string = "1"; ``` --- ## Global Window Extensions The SDK extends the global `Window` interface: ```typescript declare global { interface Window { renown?: IRenown; connectCrypto?: IConnectCrypto; reactor?: { setGenerateJwtHandler: ( handler: (driveUrl: string) => Promise, ) => void; removeJwtHandler: () => void; }; } } ``` ### `window.renown` Global Renown instance after initialization. **Usage:** ```typescript if (window.renown) { const user = await window.renown.login("did:pkh:..."); } ``` ### `window.connectCrypto` Global ConnectCrypto instance after initialization. **Usage:** ```typescript if (window.connectCrypto) { const did = await window.connectCrypto.did(); } ``` --- ## Error Handling ### Common Errors #### `useUser must be used within a RenownUserProvider` **Cause:** Using `useUser()` outside of `` **Solution:** Wrap your component tree with `` ```typescript {/* ✅ Can use useUser */} ``` #### `Invalid DID format` **Cause:** DID doesn't match expected format `did:pkh:networkId:chainId:address` **Solution:** Ensure DID is properly formatted ```typescript // ✅ Valid "did:pkh:eip155:1:0x1234567890123456789012345678901234567890"; // ❌ Invalid "did:1234567890123456789012345678901234567890"; ``` #### `Renown or ConnectCrypto not available` **Cause:** SDK initialization failed **Solution:** The RenownUserProvider automatically initializes the SDK. If you see this error: 1. Check that `` is mounted 2. Check browser console for initialization errors 3. Verify network connectivity to Renown service 4. Try providing an `errorComponent` prop to see detailed error messages ```typescript (

Init failed: {error.message}

)} > ``` --- ## TypeScript Support The SDK is fully typed. Import types as needed: ```typescript User, LoginStatus, RenownUserContextValue, IRenown, IConnectCrypto, } from "@renown/sdk"; ``` --- ## Version Compatibility | SDK Version | React Version | TypeScript Version | | ----------- | ------------- | ------------------ | | 5.x | 18.x - 19.x | 4.5+ | | 4.x | 18.x | 4.5+ | --- ## Related Documentation - [Authentication Guide](../docs/docs/01-Authentication.md) - Comprehensive auth implementation guide --- ## CLI Identity & Authentication > Source: https://academy.vetra.io/academy/Reference/Authorization/renown-sdk/CLIIdentity This guide covers how to authenticate the Powerhouse CLI with your Ethereum identity and use that identity in the Switchboard for authenticated operations with remote services. ## Overview The Powerhouse CLI uses **Renown** for identity management. When you run `ph login`, the CLI: 1. Generates a cryptographic keypair (ECDSA P-256) stored locally 2. Creates a DID (Decentralized Identifier) in `did:key:...` format 3. Opens your browser to authorize this DID to act on behalf of your Ethereum address 4. Stores the authorization credentials for future use This enables the CLI and Switchboard to authenticate with remote drives and services using your Ethereum identity. ## Quick Start ```bash # 1. Login with your Ethereum wallet ph login # 2. Start switchboard with your identity ph switchboard --use-identity ``` ## The Login Command ### Basic Usage ```bash # Authenticate with Renown ph login # Check your authentication status ph login --status # Show only your CLI's DID (useful for scripts) ph login --show-did # Logout and clear credentials ph logout ``` ### How It Works ``` ┌──────────────────────────────────────────────────────────────────────┐ │ ph login │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ 1. CLI generates/loads keypair (.keypair.json) │ │ └─► Creates DID: did:key:zDnae... │ │ │ │ 2. Opens browser to Renown portal │ │ └─► URL includes CLI's DID │ │ │ │ 3. User connects wallet & signs authorization │ │ └─► "I authorize did:key:zDnae... to act on my behalf" │ │ │ │ 4. Renown issues credential │ │ └─► Links CLI DID to user's ETH address │ │ │ │ 5. CLI stores credentials (.auth.json in project dir) │ │ └─► Ready to authenticate with remote services │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` ### Output Example ``` $ ph login Initializing cryptographic identity... CLI DID: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo Opening browser for authentication... Session ID: a1b2c3d4... Waiting for authentication in browser (timeout in 300 seconds) Please connect your wallet and authorize this CLI to act on your behalf. Waiting................. Successfully authenticated! ETH Address: 0x1234...abcd User DID: did:pkh:eip155:1:0x1234...abcd CLI DID: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo The CLI can now act on behalf of your Ethereum identity. ``` ## Storage Locations All identity files are stored **per-project** in the current working directory: ``` your-project/ ├── .keypair.json # CLI's cryptographic keypair (did:key identity) ├── .auth.json # Authentication credentials (ETH address, User DID, etc.) ├── powerhouse.config.json └── ... ``` This means each project can have its own identity and credentials, which is useful for: - Different projects requiring different identities - Team members using the same machine - Separating development and production identities - Isolating credentials between projects ### Environment Variable For CI/CD environments, provide the keypair via environment variable: ```bash # Export keypair as JSON export PH_RENOWN_PRIVATE_KEY='{"publicKey":{"kty":"EC",...},"privateKey":{"kty":"EC",...}}' # Now ph login --show-did will use this keypair ph login --show-did ``` ## Using Identity in Switchboard ### Starting with Identity ```bash # Enable identity using keypair from ph login ph switchboard --use-identity # Output includes identity DID: # ➜ Switchboard: http://localhost:4001 # ➜ Identity: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo ``` ### Identity Options | Option | Description | | ----------------------- | ------------------------------------- | | `--use-identity` | Enable identity using `.keypair.json` | | `--keypair-path ` | Use a custom keypair file | | `--require-identity` | Fail if no keypair exists | ### Requiring Identity Use `--require-identity` when the switchboard must have a valid identity: ```bash # Fails if no keypair exists (user must run ph login first) ph switchboard --require-identity # Error if not logged in: # Error: Identity required but failed to initialize. Run "ph login" first. ``` ### Custom Keypair Path ```bash # Use a specific keypair file ph switchboard --use-identity --keypair-path /path/to/my-keypair.json ``` ## How the Switchboard Uses Identity When the Switchboard starts with identity enabled, it can: 1. **Authenticate with Remote Drives**: Generate bearer tokens for API requests 2. **Sign Operations**: Cryptographically sign document operations 3. **Identify Itself**: Present its DID to remote services ### Getting Bearer Tokens The Switchboard can generate bearer tokens for authenticated API calls: ```typescript // Get the switchboard's DID const did = await getConnectDid(); console.log("Switchboard DID:", did); // Get a bearer token for a remote drive const token = await getBearerToken("https://remote.drive.example.com"); console.log("Bearer Token:", token); // Use in API requests const response = await fetch("https://remote.drive.example.com/api/documents", { headers: { Authorization: `Bearer ${token}`, }, }); ``` ## Security Considerations ### Identity Files Protection The `.keypair.json` and `.auth.json` files contain sensitive data. Protect them: ```bash # Add to .gitignore echo ".keypair.json" >> .gitignore echo ".auth.json" >> .gitignore # Set restrictive permissions (Unix) chmod 600 .keypair.json .auth.json ``` ### CI/CD Best Practices For automated environments: 1. **Use environment variables** instead of files 2. **Store secrets securely** (GitHub Secrets, AWS Secrets Manager, etc.) 3. **Rotate keys** periodically 4. **Limit scope** - use separate identities for different environments ```yaml # GitHub Actions example jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup identity env: PH_RENOWN_PRIVATE_KEY: ${{ secrets.PH_KEYPAIR }} run: | ph switchboard --use-identity & ``` ### Authorization Scope When you authorize the CLI's DID: - It can act on behalf of your Ethereum address - It can authenticate with services that trust Renown - It **cannot** sign Ethereum transactions or access your wallet ## Troubleshooting ### "No existing keypair found" ```bash $ ph switchboard --require-identity Error: Identity required but failed to initialize. Run "ph login" first. ``` **Solution**: Run `ph login` to create a keypair: ```bash ph login # Then retry ph switchboard --require-identity ``` ### "Authentication timed out" The browser authentication didn't complete in time. **Solutions**: - Increase timeout: `ph login --timeout 600` - Check browser opened correctly - Ensure you completed the wallet connection ### Different DID than expected Each project directory has its own `.keypair.json`. **Check current DID**: ```bash ph login --show-did ``` **Use specific keypair**: ```bash ph switchboard --use-identity --keypair-path ~/.shared-keypair.json ``` ## API Reference ### Login Options | Option | Type | Default | Description | | -------------- | ------- | ------------------------------ | ---------------------- | | `--renown-url` | string | `https://renown.powerhouse.io` | Renown server URL | | `--timeout` | number | `300` | Auth timeout (seconds) | | `--logout` | boolean | `false` | Clear credentials | | `--status` | boolean | `false` | Show auth status | | `--show-did` | boolean | `false` | Print DID only | ### Switchboard Identity Options | Option | Type | Default | Description | | -------------------- | ------- | --------------- | -------------------- | | `--use-identity` | boolean | `false` | Enable identity | | `--keypair-path` | string | `.keypair.json` | Keypair file path | | `--require-identity` | boolean | `false` | Fail without keypair | ### Exported Functions (Switchboard) ```typescript // Get the ConnectCrypto instance function getConnectCrypto(): IConnectCrypto | null; // Get the switchboard's DID async function getConnectDid(): Promise; // Get a bearer token for a remote URL async function getBearerToken( driveUrl: string, address?: string, refresh?: boolean, ): Promise; ``` ## Related Documentation - [Renown SDK Overview](../docs/docs/00-Overview.md) - Introduction to Renown - [Authentication Guide](../docs/docs/01-Authentication.md) - Web app authentication - [API Reference](../docs/docs/02-APIReference.md) - Full SDK reference --- ## Powerhouse CLI > Source: https://academy.vetra.io/academy/Reference/CLITooling/PowerhouseCLI ### Installing the Powerhouse CLI **TIP:** The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below. 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. ```bash pnpm install -g ph-cmd ``` {/* AUTO-GENERATED-CLI-COMMANDS-START */} {/* This content is automatically generated. Do not edit directly. */} ## Quick Reference | Command | Description | Example | |---------|-------------|---------| | `ph init` | Initialize a new project | `ph init my-project --pnpm` | | `ph use` | Switch to a release version | `ph use staging` | | `ph update` | Update dependencies to latest | `ph update` | | `ph setup-globals` | Initialize global project | `ph setup-globals my-globals` | | `ph use-local` | Use local monorepo dependencies | `ph use-local ../powerhouse` | --- ### ph-cmd Commands - [Init](#init) - [Use](#use) - [Update](#update) - [Setup Globals](#setup-globals) - [Use Local](#use-local) ## Init Initialize a new project --- ## Parameters ### Arguments **Name** - The name of your project. A new directory will be created in your current directory with this name. - Usage: `[name]` ### Options **Name** - The name of your project. A new directory will be created in your current directory with this name. - Usage: `--name, -n ` **Package Manager** - Specify the package manager to use for your project. Can be one of: `npm`, `pnpm`, `yarn`, or `bun`. Defaults to your environment package manager. - Usage: `--package-manager, -p ` **Tag** - Specify the release tag to use for your project. Can be one of: "latest", "staging", "dev", or "rc". - Usage: `--tag, -t ` **Version** - Specify the exact semver release version to use for your project. - Usage: `--version, -v ` **Remote Drive** - Remote drive identifier. - Usage: `--remote-drive, -r ` **Clone** - Path to an existing scaffolded project to clone instead of resolving deps from scratch. Install runs offline from the cloned project's pnpm-lock.yaml (requires --pnpm; --version/--tag are ignored). - Usage: `--clone ` ### Flags **Npm** - Use 'npm' as package manager - Usage: `--npm` **Pnpm** - Use 'pnpm' as package manager - Usage: `--pnpm` **Yarn** - Use 'yarn' as package manager - Usage: `--yarn` **Bun** - Use 'bun' as package manager - Usage: `--bun` **Dev** - Use the `dev` release tag. - Usage: `--dev, -d` **Staging** - Use the `staging` release tag. - Usage: `--staging, -s` **Rc** - Use the `rc` release tag. - Usage: `--rc` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Use Specify the release version of Powerhouse dependencies to use. --- ## Parameters ### Arguments **Tag** - Specify the release tag to use for your project. Can be one of: "latest", "staging", "dev", or "rc". - Usage: `[tag]` ### Options **Tag** - Specify the release tag to use for your project. Can be one of: "latest", "staging", "dev", or "rc". - Usage: `--tag, -t ` **Version** - Specify the exact semver release version to use for your project. - Usage: `--version, -v ` ### Flags **Skip Install** - Skip running `install` with your package manager - Usage: `--skip-install, -s` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Update Update your powerhouse dependencies to their latest tagged version ### Flags **Skip Install** - Skip running `install` with your package manager - Usage: `--skip-install, -s` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Setup Globals Initialize a new global project --- ## Parameters ### Arguments **Name** - The name of your project. A new directory will be created in your current directory with this name. - Usage: `[name]` ### Options **Name** - The name of your project. A new directory will be created in your current directory with this name. - Usage: `--name, -n ` **Package Manager** - Specify the package manager to use for your project. Can be one of: `npm`, `pnpm`, `yarn`, or `bun`. Defaults to your environment package manager. - Usage: `--package-manager, -p ` **Tag** - Specify the release tag to use for your project. Can be one of: "latest", "staging", "dev", or "rc". - Usage: `--tag, -t ` **Version** - Specify the exact semver release version to use for your project. - Usage: `--version, -v ` **Remote Drive** - Remote drive identifier. - Usage: `--remote-drive, -r ` **Clone** - Path to an existing scaffolded project to clone instead of resolving deps from scratch. Install runs offline from the cloned project's pnpm-lock.yaml (requires --pnpm; --version/--tag are ignored). - Usage: `--clone ` ### Flags **Npm** - Use 'npm' as package manager - Usage: `--npm` **Pnpm** - Use 'pnpm' as package manager - Usage: `--pnpm` **Yarn** - Use 'yarn' as package manager - Usage: `--yarn` **Bun** - Use 'bun' as package manager - Usage: `--bun` **Dev** - Use the `dev` release tag. - Usage: `--dev, -d` **Staging** - Use the `staging` release tag. - Usage: `--staging, -s` **Rc** - Use the `rc` release tag. - Usage: `--rc` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Use Local Use your local `powerhouse` monorepo dependencies the current project. --- ## Parameters ### Arguments **Monorepo Path** - Path to your local powerhouse monorepo relative to this project - Usage: `[monorepo path]` ### Options **Path** - Path to your local powerhouse monorepo relative to this project - Usage: `--path, -p ` ### Flags **Skip Install** - Skip running `install` with `pnpm` - Usage: `--skip-install, -s` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ### ph-cli Commands - [Generate](#generate) - [All](#all) - [Document Model](#document-model) - [Editor](#editor) - [App](#app) - [Processor](#processor) - [Subgraph](#subgraph) - [Migration File](#migration-file) - [Vetra](#vetra) - [Connect](#connect) - [Connect Studio](#connect-studio) - [Connect Build](#connect-build) - [Connect Preview](#connect-preview) - [Access Token](#access-token) - [Inspect](#inspect) - [List](#list) - [Migrate](#migrate) - [Switchboard](#switchboard) - [Login](#login) - [Install](#install) - [Uninstall](#uninstall) ## Generate The generate command creates code for Powerhouse modules. It helps you create new code from scratch, or to re-generate existing code in your project. ## All Re-generate all modules in the current project ### Flags **Extract** - Instead of generating code, write a spec for every module into specs/ (one-shot migration to documents-as-source-of-truth) - Usage: `--extract, -x` **Help** - show help - Usage: `--help, -h` ## Document Model Generate a document model ### Options **Document** - Path to a document model spec (.phd or .json) to generate from - Usage: `--document, -d ` **Dir** - Name of the directory of an existing document model to re-generate - Usage: `--dir ` ### Flags **All** - Re-generate all existing document models in the current project - Usage: `--all, -a` **Extract** - Write a powerhouse/document-model spec for each existing document model into specs/document-models/ - Usage: `--extract, -x` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Editor Generate a document editor ### Options **Name** - The name of the document editor to generate - Usage: `--name, -n ` **Document Type** - The document type for the new editor - Usage: `--document-type, -t ` **Document** - Path to a powerhouse/document-editor spec file (.phd or .json) to drive codegen - Usage: `--document, -d ` **Dir** - Name of the directory of an existing editor to re-generate - Usage: `--dir ` ### Flags **All** - Re-generate all existing editors in the current project - Usage: `--all, -a` **Extract** - Write a powerhouse/document-editor spec for each existing editor into specs/editors/ - Usage: `--extract, -x` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## App Generate a drive app ### Options **Name** - The name of the drive app to generate - Usage: `--name, -n ` **Document Types** - The document types allowed by the new app - Usage: `--document-types , -t=` **Document** - Path to a powerhouse/app spec file (.phd or .json) to drive codegen - Usage: `--document, -d ` **Dir** - Name of the directory of an existing app to re-generate - Usage: `--dir ` ### Flags **Disable Drag And Drop** - Do not allow drag and drop in this drive app. - Usage: `--disable-drag-and-drop` **Default:** `false` **All** - Re-generate all existing apps in the current project - Usage: `--all, -a` **Extract** - Write a powerhouse/app spec for each existing drive app into specs/apps/ - Usage: `--extract, -x` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Processor Generate a processor ### Options **Name** - The name of the processor to generate - Usage: `--name, -n ` **Type** - The type of processor to generate - Usage: `--type ` **Default:** `analytics` **Document Types** - The document types the processor will run on - Usage: `--document-types , -t=` **Default:** `` **Apps** - Whether the processor will run in switchboard (nodejs), connect (browser), or both - Usage: `--apps ` **Default:** `switchboard,connect` **Document** - Path to a powerhouse/processor spec file (.phd or .json) to drive codegen - Usage: `--document, -d ` **Dir** - Name of the directory of an existing processor to re-generate - Usage: `--dir ` ### Flags **All** - Re-generate all existing processors in the current project - Usage: `--all, -a` **Extract** - Write a powerhouse/processor spec for each existing processor into specs/processors/ - Usage: `--extract, -x` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Subgraph Generate a subgraph ### Options **Name** - The name of the subgraph to generate - Usage: `--name, -n ` **Document** - Path to a powerhouse/subgraph spec file (.phd or .json) to drive codegen - Usage: `--document, -d ` **Dir** - Name of the directory of an existing subgraph to re-generate - Usage: `--dir ` ### Flags **All** - Re-generate all existing subgraphs in the current project - Usage: `--all, -a` **Extract** - Write a powerhouse/subgraph spec for each existing subgraph into specs/subgraphs/ - Usage: `--extract, -x` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Migration File Generate a migration file ### Options **Path *[required]*** - Path to the migration file - Usage: `--path, -p ` **Schema File** - Path to the output file. Defaults to './schema.ts' - Usage: `--schema-file ` ### Flags **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Vetra The vetra command sets up a Vetra development environment for working with Vetra projects. It starts a Vetra Switchboard and optionally Connect Studio, enabling document collaboration and real-time processing with a "Vetra" drive or connection to remote drives. **What it does:** - 1. Starts a Vetra Switchboard with a "Vetra" drive for document storage - 2. Optionally connects to remote drives instead of creating a local drive - 3. Starts Connect Studio pointing to the Switchboard for user interaction (unless disabled) - 4. Enables real-time updates, collaboration, and code generation ### Options **Switchboard Port** - port to use for the Vetra Switchboard - Usage: `--switchboard-port ` **Connect Port** - port to use for the Vetra Connect - Usage: `--connect-port ` **Default:** `3001` **Remote Drive** - URL of remote drive to connect to (skips switchboard initialization) - Usage: `--remote-drive ` **Drives Public Base** - public base URL for the drive URLs advertised to Connect; each drive is exposed as <base>/d/<slug> instead of `http://localhost:/d/`. Use when the switchboard is reachable through a reverse proxy. - Usage: `--drives-public-base ` **Db Path** - Database path or connection string. Use a `postgres://` URL for Postgres; otherwise treated as a PGlite filesystem path. Leave unset for in-memory PGlite. - Usage: `--db-path ` **Renown Namespace** - Renown localStorage namespace; share it across Connects to share login. - Usage: `--renown-namespace ` **Base** - Base path for the app - Usage: `--base ` **Log Level** - Log level for the application - Usage: `--log-level ` **Environment:** `PH_CONNECT_LOG_LEVEL` **Default:** `info` **Packages** - Comma-separated list of package names to load - Usage: `--packages ` **Environment:** `PH_PACKAGES` **Local Package** - Path to local package to load during development - Usage: `--local-package ` **Environment:** `PH_LOCAL_PACKAGE` **Default Drives Url** - The default drives url to use in connect - Usage: `--default-drives-url ` **Drive Preserve Strategy** - The preservation strategy to use on default drives - Usage: `--drive-preserve-strategy ` **Default:** `preserve-by-url-and-detach` **Host** - Expose the server to the network. Pass an IP (e.g. 0.0.0.0) to bind to a specific address. - Usage: `--host ` **Watch Timeout** - Amount of time to wait before a file is considered changed - Usage: `--watch-timeout ` **Default:** `300` **Https Key File** - path to the ssl key file - Usage: `--https-key-file ` **Https Cert File** - path to the ssl cert file - Usage: `--https-cert-file ` **Remote Drives** - Specify remote drive URLs to use - Usage: `--remote-drives ` ### Flags **Watch** - Enable dynamic loading for document-models and editors in connect-studio and switchboard - Usage: `--watch, -w` **Default:** `false` **Logs** - Show additional logs - Usage: `--logs` **Default:** `false` **Disable Connect** - Skip Connect initialization (only start switchboard and reactor) - Usage: `--disable-connect` **Default:** `false` **Interactive** - Enable interactive mode for code generation (requires user confirmation before generating code) - Usage: `--interactive` **Default:** `false` **Ignore Local** - Do not load local packages from this project - Usage: `--ignore-local` **Force** - Force dep pre-optimization regardless of whether deps have changed. - Usage: `--force` **Debug** - Log arguments passed to this command - Usage: `--debug` **Open** - Open browser on startup - Usage: `--open` **Cors** - Enable CORS - Usage: `--cors` **Strict Port** - Exit if specified port is already in use - Usage: `--strictPort` **Print Urls** - Print server urls - Usage: `--print-urls` **Default:** `true` **Bind Cli Shortcuts** - Bind CLI shortcuts - Usage: `--bind-cli-shortcuts` **Default:** `true` **Https** - Use https - Usage: `--https` **Dev** - enable development mode to load local packages - Usage: `--dev` **Help** - show help - Usage: `--help, -h` ## Connect Powerhouse Connect commands. Use with `studio`, `build`, `preview`, or `config`. Defaults to `studio` if not specified. ## Connect Studio The studio command starts the Connect Studio, a development environment for building and testing Powerhouse applications. It provides a visual interface for working with your project. **What it does:** - 1. Starts a local Connect Studio server - 2. Provides a web interface for development - 3. Allows you to interact with your project components - 4. Supports various configuration options for customization ### Options **Port** - Port to run the dev server on. - Usage: `--port ` **Default:** `3000` **Renown Namespace** - Renown localStorage namespace; share it across Connects to share login. - Usage: `--renown-namespace ` **Base** - Base path for the app - Usage: `--base ` **Log Level** - Log level for the application - Usage: `--log-level ` **Environment:** `PH_CONNECT_LOG_LEVEL` **Default:** `info` **Packages** - Comma-separated list of package names to load - Usage: `--packages ` **Environment:** `PH_PACKAGES` **Local Package** - Path to local package to load during development - Usage: `--local-package ` **Environment:** `PH_LOCAL_PACKAGE` **Default Drives Url** - The default drives url to use in connect - Usage: `--default-drives-url ` **Drive Preserve Strategy** - The preservation strategy to use on default drives - Usage: `--drive-preserve-strategy ` **Default:** `preserve-by-url-and-detach` **Host** - Expose the server to the network. Pass an IP (e.g. 0.0.0.0) to bind to a specific address. - Usage: `--host ` **Watch Timeout** - Amount of time to wait before a file is considered changed - Usage: `--watch-timeout ` **Default:** `300` ### Flags **Ignore Local** - Do not load local packages from this project - Usage: `--ignore-local` **Force** - Force dep pre-optimization regardless of whether deps have changed. - Usage: `--force` **Debug** - Log arguments passed to this command - Usage: `--debug` **Open** - Open browser on startup - Usage: `--open` **Cors** - Enable CORS - Usage: `--cors` **Strict Port** - Exit if specified port is already in use - Usage: `--strictPort` **Print Urls** - Print server urls - Usage: `--print-urls` **Default:** `true` **Bind Cli Shortcuts** - Bind CLI shortcuts - Usage: `--bind-cli-shortcuts` **Default:** `true` **Help** - show help - Usage: `--help, -h` ## Connect Build The Connect build command creates a production build with the project's local and external packages included. Runtime-config overrides (all combinable — last wins on collision): ph connect build Build with the current source config. ph connect build <key> <value> Build with a positional override applied (e.g. ph connect build connect.renown.url `https://renown.staging`). ph connect build --<field> <value> Build with a per-field flag override (e.g. --renown-url `https://renown.staging`). ph connect build --json '\{"…":"…"\}' Build with a bulk override. Build has no read mode; passing only <key> without <value> errors out (use `ph connect config ` to read). ### Options **Out Dir** - Output directory - Usage: `--outDir ` **Default:** `.ph/connect-build/dist/` **Json** - Inline JSON override for the runtime connect.* block, e.g. '\{"renown":\{"url":"..."\}\}'. Validated against the runtime schema; deep-merged on top of env seeds and source powerhouse.config.json. Individual --flag values beat --json on collision. - Usage: `--json ` **Renown Url** - Override connect.renown.url. - Usage: `--renown-url ` **Renown Network Id** - Override connect.renown.networkId. - Usage: `--renown-network-id ` **Renown Chain Id** - Override connect.renown.chainId. - Usage: `--renown-chain-id ` **Renown Namespace** - Renown localStorage namespace; share it across Connects to share login. - Usage: `--renown-namespace ` **Allow Add Drive** - Override connect.drives.allowAddDrive (top-level add-drive toggle). - Usage: `--allow-add-drive ` **External Packages** - Override connect.packages.externalEnabled. - Usage: `--external-packages ` **Remote Drives Enabled** - Override connect.drives.sections.remote.enabled (the unified cloud+public section). - Usage: `--remote-drives-enabled ` **Remote Drives Allow Add** - Override connect.drives.sections.remote.allowAdd. - Usage: `--remote-drives-allow-add ` **Remote Drives Allow Delete** - Override connect.drives.sections.remote.allowDelete. - Usage: `--remote-drives-allow-delete ` **Local Drives Enabled** - Override connect.drives.sections.local.enabled. - Usage: `--local-drives-enabled ` **Local Drives Allow Add** - Override connect.drives.sections.local.allowAdd. - Usage: `--local-drives-allow-add ` **Local Drives Allow Delete** - Override connect.drives.sections.local.allowDelete. - Usage: `--local-drives-allow-delete ` **Packages Registry** - Override the top-level packageRegistryUrl. - Usage: `--packages-registry ` **App Name** - Override connect.branding.appName. - Usage: `--app-name ` **Home Background** - Override connect.branding.homeBackground. URL or path to an image; pass an empty string ("") to reset to the bundled default. - Usage: `--home-background ` **Sentry Dsn** - Override connect.sentry.dsn (Sentry DSN URL). Pass an empty string ("") to set null and disable Sentry. - Usage: `--sentry-dsn ` **Sentry Env** - Override connect.sentry.env (Sentry environment label). - Usage: `--sentry-env ` **Sentry Tracing Enabled** - Override connect.sentry.tracing (Sentry performance tracing). - Usage: `--sentry-tracing-enabled ` **Favicon** - Path to a favicon file (e.g. .ico) to bundle in place of the default Connect icon. Emitted as icon.ico; resolved relative to the build cwd. - Usage: `--favicon ` **Base** - Base path for the app - Usage: `--base ` **Log Level** - Log level for the application - Usage: `--log-level ` **Environment:** `PH_CONNECT_LOG_LEVEL` **Default:** `info` **Packages** - Comma-separated list of package names to load - Usage: `--packages ` **Environment:** `PH_PACKAGES` **Local Package** - Path to local package to load during development - Usage: `--local-package ` **Environment:** `PH_LOCAL_PACKAGE` **Default Drives Url** - The default drives url to use in connect - Usage: `--default-drives-url ` **Drive Preserve Strategy** - The preservation strategy to use on default drives - Usage: `--drive-preserve-strategy ` **Default:** `preserve-by-url-and-detach` --- ## Parameters ### Arguments **Key** - Dotted path inside the runtime config (e.g. connect.renown.url). Pair with <value> to set; pass alone to `ph connect config` to read. - Usage: `[key]` **Value** - Value to set at <key>. Coerced against the runtime schema (string, bool, number, enum). Arrays and objects require --json instead. - Usage: `[value]` ### Flags **Dynamic Base** - Build one bundle that serves under any subpath; base resolved at serve time from a runtime global. Overrides --base. - Usage: `--dynamic-base` **Ignore Local** - Do not load local packages from this project - Usage: `--ignore-local` **Force** - Force dep pre-optimization regardless of whether deps have changed. - Usage: `--force` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Connect Preview The Connect preview command previews a built Connect project. NOTE: You must run `ph connect build` first ### Options **Port** - Port to run the preview server on. - Usage: `--port ` **Default:** `4173` **Out Dir** - Output directory - Usage: `--outDir ` **Default:** `.ph/connect-build/dist/` **Base** - Base path for the app - Usage: `--base ` **Log Level** - Log level for the application - Usage: `--log-level ` **Environment:** `PH_CONNECT_LOG_LEVEL` **Default:** `info` **Packages** - Comma-separated list of package names to load - Usage: `--packages ` **Environment:** `PH_PACKAGES` **Local Package** - Path to local package to load during development - Usage: `--local-package ` **Environment:** `PH_LOCAL_PACKAGE` **Default Drives Url** - The default drives url to use in connect - Usage: `--default-drives-url ` **Drive Preserve Strategy** - The preservation strategy to use on default drives - Usage: `--drive-preserve-strategy ` **Default:** `preserve-by-url-and-detach` **Host** - Expose the server to the network. Pass an IP (e.g. 0.0.0.0) to bind to a specific address. - Usage: `--host ` **Watch Timeout** - Amount of time to wait before a file is considered changed - Usage: `--watch-timeout ` **Default:** `300` ### Flags **Ignore Local** - Do not load local packages from this project - Usage: `--ignore-local` **Force** - Force dep pre-optimization regardless of whether deps have changed. - Usage: `--force` **Debug** - Log arguments passed to this command - Usage: `--debug` **Open** - Open browser on startup - Usage: `--open` **Cors** - Enable CORS - Usage: `--cors` **Strict Port** - Exit if specified port is already in use - Usage: `--strictPort` **Print Urls** - Print server urls - Usage: `--print-urls` **Default:** `true` **Bind Cli Shortcuts** - Bind CLI shortcuts - Usage: `--bind-cli-shortcuts` **Default:** `true` **Help** - show help - Usage: `--help, -h` ## Access Token The access-token command generates a bearer token for API authentication. This token can be used to authenticate requests to Powerhouse APIs like reactor-api (Switchboard). **What it does:** - 1. Uses your CLI's cryptographic identity (DID) to sign a verifiable credential - 2. Creates a JWT bearer token with configurable expiration - 3. Outputs the token to stdout (info to stderr) for easy piping Prerequisites: You must have a cryptographic identity. Run 'ph login' first to: - Generate a keypair (stored in .ph/.keypair.json) - Optionally link your Ethereum address (stored in .ph/.renown.json) Token Details: The generated token is a JWT (JSON Web Token) containing: - Issuer (iss): Your CLI's DID (did:key:...) - Subject (sub): Your CLI's DID - Credential Subject: Chain ID, network ID, and address (if authenticated) - Expiration (exp): Based on --expiry option - Audience (aud): If --audience is specified Output: - Token information (DID, address, expiry) is printed to stderr - The token itself is printed to stdout for easy piping/copying This allows you to use the command in scripts: TOKEN=$(ph access-token) curl -H "Authorization: Bearer $TOKEN" `http://localhost:4001/graphql` Usage with APIs: Generate token and use with curl TOKEN=$(ph access-token --expiry 1d) curl -X POST `http://localhost:4001/graphql` \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '\{"query": "\{ drives \{ id name \} \}"\}' Export as environment variable export PH_ACCESS_TOKEN=$(ph access-token) Notes: - Tokens are self-signed using your CLI's private key - No network request is made; tokens are generated locally - The recipient API must trust your CLI's DID to accept the token - For reactor-api, ensure AUTH_ENABLED=true to require authentication ### Options **Expiry** - Token expiry duration. Supports: "7d" (days), "24h" (hours), "3600" or "3600s" (seconds) - Usage: `--expiry ` **Default:** `7d` **Audience** - Target audience URL for the token - Usage: `--audience ` ### Flags **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Inspect The inspect command examines and provides detailed information about a Powerhouse package. It helps you understand the structure, dependencies, and configuration of packages in your project. **What it does:** - 1. Analyzes the specified package - 2. Retrieves detailed information about its structure and configuration - 3. Displays package metadata, dependencies, and other relevant information - 4. Helps troubleshoot package-related issues --- ## Parameters ### Arguments **Package Name *[required]*** - The name of the package to inspect - Usage: `` ### Flags **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## List The list command displays information about installed Powerhouse packages in your project. It reads the powerhouse.config.json file and shows the packages that are currently installed. **What it does:** - 1. Examines your project configuration - 2. Lists all installed Powerhouse packages - 3. Provides a clear overview of your project's dependencies - 4. Helps you manage and track your Powerhouse components ### Flags **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Migrate Run migrations --- ## Parameters ### Arguments **Version** - The version to migrate to. Accepts a valid semver version or `staging`, `dev`, `latest`. - Usage: `[version]` ### Options **Version** - The version to migrate to. Accepts a valid semver version or `staging`, `dev`, `latest`. - Usage: `--version, -v ` **Default:** `latest` ### Flags **Force** - Run migrate from the bundled codegen even if the target version cannot be resolved from the npm registry or differs from the installed ph-cli version. - Usage: `--force, -f` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Switchboard The switchboard command starts a local Switchboard instance, which acts as the document processing engine for Powerhouse projects. It provides the infrastructure for document models, processors, and real-time updates. **What it does:** - 1. Starts a local switchboard server - 2. Loads document models and processors - 3. Provides an API for document operations - 4. Enables real-time document processing - 5. Can authenticate with remote services using your identity from 'ph login' ### Flags **Https** - Use https - Usage: `--https` **Dev** - enable development mode to load local packages - Usage: `--dev` **Ignore Local** - Do not load local packages from this project - Usage: `--ignore-local` **Debug** - Log arguments passed to this command - Usage: `--debug` **Use Identity** - enable identity using keypair from ph login (uses ~/.ph/keypair.json) - Usage: `--use-identity` **Require Identity** - require existing keypair, fail if not found (implies --use-identity) - Usage: `--require-identity` **Migrate** - Run database migrations and exit - Usage: `--migrate` **Migrate Status** - Show migration status and exit - Usage: `--migrate-status` **Reset** - Wipe the local PGlite switchboard storage after confirmation, then exit - Usage: `--reset` **Yes** - Skip the interactive confirmation prompt for --reset (required for non-interactive use) - Usage: `--yes, -y` **Mcp** - enable Mcp route at /mcp - Usage: `--mcp` **Default:** `true` **Use Vetra Drive** - Use a Vetra drive - Usage: `--use-vetra-drive` **Default:** `false` **Help** - show help - Usage: `--help, -h` ### Options **Https Key File** - path to the ssl key file - Usage: `--https-key-file ` **Https Cert File** - path to the ssl cert file - Usage: `--https-cert-file ` **Remote Drives** - Specify remote drive URLs to use - Usage: `--remote-drives ` **Packages** - Comma-separated list of package names to load - Usage: `--packages ` **Environment:** `PH_PACKAGES` **Port** - Port to host the api - Usage: `--port ` **Default:** `4001` **Base Path** - base path for the API endpoints (sets the BASE_PATH environment variable) - Usage: `--base-path ` **Keypair Path** - path to custom keypair file for identity - Usage: `--keypair-path ` **Vetra Drive Id** - Specify a Vetra drive ID - Usage: `--vetra-drive-id ` **Default:** `vetra` **Db Path** - path to the database - Usage: `--db-path ` ## Login The login command authenticates you with Renown using your Ethereum wallet. This enables the CLI to act on behalf of your Ethereum identity for authenticated operations. **What it does:** - 1. Generates or loads a cryptographic identity (DID) for the CLI - 2. Opens your browser to the Renown authentication page - 3. You authorize the CLI's DID to act on behalf of your Ethereum address - 4. Stores the credentials locally in .ph/.renown.json ### Options **Renown Url** - Renown server URL. - Usage: `--renown-url ` **Environment:** `PH_CONNECT_RENOWN_URL` **Default:** `https//www.renown.id` **Timeout** - Authentication timeout in seconds. - Usage: `--timeout ` **Default:** `300` ### Flags **Logout** - Sign out and clear stored credentials - Usage: `--logout` **Status** - Show current authentication status - Usage: `--status` **Show Did** - Show the CLI's DID and exit - Usage: `--show-did` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Install The install command adds Powerhouse dependencies to your project. By default it only registers the package in powerhouse.config.json with provider "registry" — Connect will load it from the registry CDN at runtime. With --local, the package is also installed into node_modules and marked as provider "local" — it will be bundled into ph connect build so the preview works without the registry being reachable. Resolution order for the registry URL: --registry flag > PH_REGISTRY_URL env > powerhouse.config.json > default --- ## Parameters ### Arguments **Dependencies *[required]*** - Names of the dependencies to install - Usage: `[...dependencies]` ### Options **Registry** - Registry URL to install from (overrides config and environment) - Usage: `--registry ` **Allow Build** - A list of package names that are allowed to run postinstall scripts during installation. - Usage: `--allow-build ` **Package Manager** - Specify the package manager to use for your project. Can be one of: `npm`, `pnpm`, `yarn`, or `bun`. Defaults to your environment package manager. - Usage: `--package-manager, -p ` ### Flags **Local** - Also install packages into node_modules (marks them as provider: "local" so they get bundled into ph connect build) - Usage: `--local` **Npm** - Use 'npm' as package manager - Usage: `--npm` **Pnpm** - Use 'pnpm' as package manager - Usage: `--pnpm` **Yarn** - Use 'yarn' as package manager - Usage: `--yarn` **Bun** - Use 'bun' as package manager - Usage: `--bun` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` ## Uninstall The uninstall command removes Powerhouse dependencies from your project. It handles the removal of packages, updates configuration files, and ensures proper cleanup. **What it does:** - 1. Uninstalls specified Powerhouse dependencies using your package manager - 2. Updates powerhouse.config.json to remove the dependencies - 3. Supports various uninstallation options and configurations - 4. Works with npm, yarn, yarn@berry, pnpm, pnpm@6, bun, deno package managers --- ## Parameters ### Arguments **Dependencies *[required]*** - Names of the dependencies to uninstall - Usage: `[...dependencies]` ### Options **Package Manager** - Specify the package manager to use for your project. Can be one of: `npm`, `pnpm`, `yarn`, or `bun`. Defaults to your environment package manager. - Usage: `--package-manager, -p ` ### Flags **Npm** - Use 'npm' as package manager - Usage: `--npm` **Pnpm** - Use 'pnpm' as package manager - Usage: `--pnpm` **Yarn** - Use 'yarn' as package manager - Usage: `--yarn` **Bun** - Use 'bun' as package manager - Usage: `--bun` **Debug** - Log arguments passed to this command - Usage: `--debug` **Help** - show help - Usage: `--help, -h` {/* AUTO-GENERATED-CLI-COMMANDS-END */} --- ## Vetra Remote Drive > Source: https://academy.vetra.io/academy/Reference/CLITooling/VetraRemoteDrive These commands enable collaborative development using Vetra remote drives. Instead of working with local drives only, you can connect your Powerhouse project to a remote drive that syncs across team members. ## Commands Overview ### `ph init --remote-drive` **Purpose:** Create a new Powerhouse project and connect it to a remote Vetra drive. **When to use:** You're starting a NEW project that will be shared via a remote drive. **How it works:** 1. Validates the remote drive URL and checks that no GitHub URL is configured yet 2. Creates a standard Powerhouse project from the boilerplate 3. Adds Vetra configuration to `powerhouse.config.json`: ```json { "vetra": { "driveId": "abc123", "driveUrl": "https://vetra.example.com/d/abc123" } } ``` **Usage:** ```bash ph init my-project --remote-drive https://vetra.example.com/d/abc123 ``` **After initialization:** - Create a GitHub repository - Commit and push your code - Run `ph vetra` to configure the GitHub URL in the remote drive --- ### `ph checkout --remote-drive` **Purpose:** Clone an existing Powerhouse project that's already connected to a remote drive. **When to use:** You're joining an EXISTING project that someone else initialized. **How it works:** 1. Queries the remote drive to find the configured GitHub URL 2. Clones the repository from GitHub 3. Installs dependencies 4. The project is already configured to use the remote drive **Usage:** ```bash ph checkout --remote-drive https://vetra.example.com/d/abc123 ``` **Requirements:** - The remote drive must have a GitHub URL configured (done during `ph vetra` after init) --- ### `ph vetra` **Purpose:** Start the Vetra development environment with Switchboard and Connect Studio. **When to use:** After initializing or checking out a project, to start development. **How it works:** 1. Reads the remote drive URL from `powerhouse.config.json` (or `--remote-drive` flag) 2. Starts Switchboard connected to the remote drive (syncs automatically) 3. Prompts to configure GitHub URL if not set (first time after init) 4. Starts Connect Studio pointing to the drive(s) **With `--watch` flag:** - Creates a second "Vetra Preview" drive for testing local changes - Dynamically loads your local document models and editors - Main drive stays stable, preview drive for experimentation **Usage:** ```bash # Basic usage (uses config from powerhouse.config.json) ph vetra # With watch mode for development ph vetra --watch # Override remote drive URL ph vetra --remote-drive https://vetra.example.com/d/abc123 # Disable Connect Studio ph vetra --disable-connect ``` **Key options:** - `--watch` - Enable dynamic loading and create preview drive - `--remote-drive ` - Specify remote drive URL - `--switchboard-port ` - Custom Switchboard port (default: 4001) - `--connect-port ` - Custom Connect Studio port (default: 3000) - `--disable-connect` - Skip Connect Studio - `--interactive` - Enable interactive mode for code generation --- ## Workflows ### Starting a New Project (Owner) ```bash # 1. Initialize with remote drive ph init my-project --remote-drive https://vetra.example.com/d/abc123 # 2. Create GitHub repo and push cd my-project git add . git commit -m "Initial commit" git remote add origin https://github.com/user/my-project.git git push -u origin main # 3. Start Vetra and configure GitHub URL ph vetra # (Select option to use detected GitHub URL when prompted) # 4. Start developing with watch mode ph vetra --watch ``` ### Joining an Existing Project (Collaborator) ```bash # 1. Checkout from remote drive ph checkout --remote-drive https://vetra.example.com/d/abc123 # 2. Navigate to project cd project-name # 3. Start Vetra environment with watch mode ph vetra --watch # You're now synced with the remote drive ``` --- ## Key Concepts **Remote Drive vs Local Drive:** - Without remote drive: `ph vetra` creates a local drive on your machine only - With remote drive: `ph vetra` connects to a shared drive that syncs across team members **When to use each command:** - Use `ph init --remote-drive` when starting a NEW project (no GitHub URL configured in drive yet) - Use `ph checkout --remote-drive` when joining an EXISTING project (GitHub URL already configured) - Use `ph vetra --watch` to start development after either init or checkout **Preview Drive (`--watch` mode):** - Main "Vetra" drive: syncs with remote, contains stable package configuration - "Vetra Preview" drive: created locally with `--watch`, for testing local document models - Without `--watch`: safer, prevents untested code from affecting Connect - With `--watch`: enables rapid development and testing --- # Book of Powerhouse ## Overview > Source: https://academy.vetra.io/bookofpowerhouse/Overview Powerhouse is an initiative at the intersection of software development, legal innovation, and new business models for open-source projects. These elements form a common vision for reimagining how software is created, funded, and sustained. While each component has its own purpose, they are deeply interconnected and designed to support one another.

Book of Powerhouse Outline: 1. General Framework and Philosophy 2. Powerhouse Software Architecture 3. Technical Development Approaches 4. SNOs as an extension of DAOs 5. The Powerhouse Operations Platform --- ## **Part 1: Powerhouse General Framework and Open-Source Capitalism** > Source: https://academy.vetra.io/bookofpowerhouse/GeneralFrameworkAndPhilosophy Powerhouse emerged in the wake of Ethereum’s DAO movement, which began gaining momentum after the collapse of _The DAO_ in 2016. This turning point spurred the creation of blockchain-enabled organizations capable of operating without centralized corporate structures. Over the years, governance systems and decentralized operational tools have advanced, paving the way for the next generation of organizations across chains like Solana, Ethereum Layer 2 solutions, and beyond. Powerhouse aims to advance these principles and build large, global organizations around networks. Powerhouse operates at the intersection of open-source innovation and decentralized coordination. This section outlines the philosophical foundation and systemic structure that guides its operations and vision—what we call “Open-Source Capitalism.” ## **Why Open-Source Capitalism?** Capitalism is the most powerful system of economic coordination ever invented. It incentivizes productivity, innovation, and risk-taking. But just as important—open-source has proven to be one of the most powerful engines of innovation within that system. Open-source unlocks coordination across boundaries: between companies, communities, and individuals. It builds shared infrastructure at unprecedented speed, allows bottom-up experimentation, and lowers barriers to participation. This is why Big Tech, for all its closed platforms and walled gardens, has embraced open-source at the core of its own operations—releasing projects like React, Kubernetes, and TensorFlow not out of charity, but because open collaboration is often the best way to build foundational technology. Yet this dynamic is incomplete. While open-source has dominated infrastructure, it has consistently struggled to capture value—particularly in consumer applications and services. The common assumption is that the challenge is distribution: how to equitably allocate funding, resources, and decision-making. But Open-Source Capitalism takes a broader view. Before we can redistribute value, we have to make sure value is being captured in the first place. That’s the central promise of Open-Source Capitalism: not just to build open alternatives, but to make them self-sustaining, investable, and scalable. It’s about combining the pro-market, pro-innovation ethos of open-source with incentive structures that actually work—so we can build networks that don’t just survive, but thrive. ## **Four Principles of Open-Source Capitalism** 1. **Coordination Through Marketplace Platforms** Open-Source Capitalism demands new types of platforms—public marketplaces where contributors, customers, and investors can interact transparently. Like Uber or Airbnb, these marketplaces optimize for liquidity and coordination, but with open governance and ownership. \ 2. **Incentive Alignment via Tokens and Revenue Sharing** Powerhouse uses Proof of Work Tokens (POWTs) to compensate contributors fairly over time, enabling deferred compensation models that align long-term incentives. \ 3. **Reinvestment Through Revenue-Generating Hubs** Monetized OSS must funnel returns back to the contributors. The RGH (Revenue Generating Hub) manages licensing, sales, and commercial transactions in alignment with decentralized values. \ 4. **Make Open Source Investable** By enabling investor flows through the Operational Collateral Fund (OCF), open-source projects gain sustainable funding channels. Returns are tied to the downstream use of open infrastructure. \ ## **Decentralized Operations and Collaboration** Open-Source Capitalism doesn’t work without new organizational structures. DAOs promised a way forward, but fell short: plagued by coordination failures, incentive misalignment, and lack of clarity around roles, responsibilities, and execution. Powerhouse emerged from this gap—building systems that retain the openness of decentralized networks while introducing the operational rigor of traditional institutions. At the core of this approach is a belief in structured decentralization. Powerhouse enables independent teams to coordinate around shared goals, using workflows encoded in software rather than enforced by hierarchy. Contributors take ownership over workstreams, reputations are built over time, and budgets are allocated based on transparent processes. This is not decentralization for its own sake—it is a functional reimagining of how work gets done at scale. Transparency plays a critical role. Rather than relying on opaque decision-making or internal politics, Powerhouse makes contributions, decisions, and payments legible. Governance and compensation are traceable across time, creating a persistent and auditable record of organizational behavior. The result is a system that fosters trust not just between individuals, but across entire networks. This is what makes Powerhouse unique: it’s not just about running decentralized software—it’s about running decentralized organizations. Open-Source Capitalism is the economic philosophy. Scalable Network Organizations are the structure. And these principles come to life through the operational frameworks that guide every action on the network. --- ## Part 2: Powerhouse Software Architecture > Source: https://academy.vetra.io/bookofpowerhouse/PowerhouseSoftwareArchitecture Powerhouse’s software architecture is designed to empower scalable, decentralized organizations with a modular, layered approach. It uses document models as the core unit that used across three layers: - the **Data Infrastructure Layer**, which handles secure storage and synchronization across local, cloud, and decentralized systems; - the **Host Application Layer**, which provides contributor tools like Powerhouse Connect and Fusion; - and the Customization **Layer**, enabling bespoke solutions for specific use cases. ## Software Architecture ### Document Models - A **document model** is a structured representation of data and workflows that captures relationships, states, and operations within a system. By treating documents as dynamic entities that evolve over time, document models allow multiple people to contribute, make changes, and track progress in a flexible and transparent way. Document models are central to Powerhouse’s development approach, forming the backbone of adaptable workflows and versatile data management. In environments where contributors work asynchronously and systems must respond to evolving needs, document models provide the flexibility and responsiveness that traditional, static structures often lack. - Building on this foundation, Powerhouse’s document models are designed to go beyond static data storage, encapsulating the complex relationships, states, and operations that drive decentralized workflows. Each document functions as a living entity, continuously evolving to reflect updates and interactions among contributors. This allows for: - **Asynchronous Collaboration**: Contributors can work on documents without being bound by linear processes. For example, a task document can move through different states (e.g., draft, review, approved) based on specific triggers or events. - **Customizable Processes**: Document models are highly adaptable, supporting unique workflows for different teams or organizations. This flexibility ensures that systems can address specialized requirements while maintaining overall consistency and transparency. - **Event-Driven Updates**: By integrating with Powerhouse’s event-driven architecture, documents can respond to real-time changes, such as new data inputs or status updates, ensuring workflows remain efficient and responsive. ### Three layers of Powerhouse 1. **Data Infrastructure Layer -** This layer is responsible for data storage and synchronization, whether locally, in the cloud, or on decentralized storage networks like Ceramic or IPFS. It includes: - **Reactor**: A storage node for documents and files, supporting multiple storage adapters for various environments. - **Powerhouse Network Components**: services required to build scalable networks of Reactor nodes, such as event buses, queues, caching services, and load balancers. 2. **Host Application Layer - t**his layer provides the tools to build apps and platforms using modular host applications. Each host application is an empty shell that gains functionality through plugins. The key host applications include: - **Powerhouse Connect**: Tools for contributors to perform their roles with tailored plugins for document management. - **Powerhouse Switchboard**: A scalable API service for aggregating data into operational, analytical, or other specialized read models. - **Powerhouse Fusion**: Public-facing collaboration platforms or marketplaces for the SNO’s platform economy. - **Powerhouse Renown**: Decentralized authentication and reputation management for contributors. - **Powerhouse Academy**: Onboarding and training tools for contributors, offering tutorials and reputation badges. 3. **Customization Layer - t**his layer consists of organization-specific plugins and instances of the host applications. It enables customization and deployment of unique platforms for each network organization. Examples include: - **Connect Plugins**: Tailored apps for contributors. - **Switchboard Plugins**: Aggregated data and API services. - **Fusion Plugins**: Custom marketplaces and user-facing platforms. - **Renown and Academy Plugins**: Contributor reputation systems and training resources. --- ## Part 3: Development Approaches > Source: https://academy.vetra.io/bookofpowerhouse/DevelopmentApproaches Powerhouse’s development approaches are designed to enable efficient, scalable, and innovative solutions for decentralized organizations. By drawing from blockchain principles, adopting Model-Driven Development (MDD), leveraging dynamic document models, and employing a Rapid Application Development (RAD) process, Powerhouse provides a comprehensive framework to address the unique challenges of decentralized systems. These methodologies enhance collaboration, streamline workflows, and accelerate iteration cycles, empowering teams to design, implement, and adapt their solutions seamlessly while staying aligned with Powerhouse’s vision for sustainable and decentralized growth. ### Blockchain principles applied to decentralized operations - Powerhouse’s development approach draws inspiration from the principles of blockchain technology while adapting them to meet the specific needs of decentralized organizations. These principles heavily influence its architecture, blending blockchain’s strengths with practical adaptations for scalable operations. - Powerhouse shares several core ideas with blockchain: - **Immutability**: Like a blockchain, Powerhouse emphasizes immutable data records. Through event sourcing, every state change is preserved as an append-only event, ensuring transparent, auditable histories. - **Decentralization**: Both systems operate without relying on a centralized authority. Powerhouse’s Document Synchronization Protocol (DocSync) does not rely on a centralized server but can run P2P. It is also storage agnostic, so there is no lock-in. Users have the option to rely on decentralized, centralized or local storage solutions. - **Transparency**: Inspired by the visibility of blockchain transactions, Powerhouse ensures operational workflows and changes are traceable, which makes governance and accountability easier. - While Powerhouse builds on blockchain principles, it diverges in key ways to address operational challenges: - **Local Scalability**: Blockchain’s global consensus can limit speed and scalability. Powerhouse prioritizes local-first workflows, ensuring contributors can operate efficiently without requiring global synchronization. - **Tailored Operations**: Unlike blockchain’s general-purpose design, Powerhouse’s architecture focuses on organizational needs, supporting custom workflows, dynamic governance, and flexible scaling. ### Model-Driven Development & Rapid Application Development (RAD) - Powerhouse leverages **Model-Driven Development (MDD)** and **Rapid Application Development (RAD)** to streamline the creation of scalable, decentralized systems. - MDD enables cross-functional collaboration by using **abstract models** as blueprints for workflows, data, and system behaviors—similar to how GraphQL schemas unify API design. These models ensure alignment across teams, enable early validation, and support seamless system evolution. **Meta-models** extend this by automating code generation, documentation, and workflow updates, reducing manual effort and ensuring consistency. - RAD accelerates development by eliminating backend complexity and leveraging **automated code generation**. Pre-built frameworks and reusable components let developers focus on UI/UX without managing backend logic. An **event-driven architecture** handles state and data sync, while document models serve as a **source of truth**, ensuring APIs, data structures, and front-end scaffolding stay in sync. Developers can rapidly iterate on tailored user experiences—akin to “swapping skins” in a game—without disrupting core functionality. ### CQRS (Command Query Responsibility Segregation) - CQRS, or Command Query Responsibility Segregation, is a key design principle in Powerhouse’s software architecture. It separates the responsibilities of handling write operations (commands) and read operations (queries) into distinct models, optimizing both for their specific purposes. - In the Powerhouse framework: - **Commands** handle operations that modify the state, such as creating or updating documents. These commands are validated and stored as events, forming the immutable history central to the system’s transparency and auditability. - **Queries** are optimized for retrieving data, leveraging read models designed for performance, scalability, and flexibility. These models aggregate data from events to provide users with tailored insights, whether for analytics, search, or operational tasks. - This separation offers significant advantages: 1. **Scalability**: Write and read models can scale independently, allowing Powerhouse to support large decentralized organizations without performance bottlenecks. 2. **Maintainability**: By isolating business logic (commands) from query logic, developers can iterate on one without affecting the other, ensuring the system evolves efficiently. 3. **Flexibility**: Powerhouse supports multiple types of read models—such as relational databases, full-text search, and analytics—each tailored to specific organizational needs. ### Event-driven Architectures (EDA) - Event-Driven Architecture (EDA) is a foundational element of Powerhouse’s software philosophy, designed to create responsive, scalable systems that support asynchronous workflows. In EDA, events represent meaningful changes or actions, such as “Document Updated” or “Contributor Added,” and these events trigger reactions across the system in real time. - EDA enables Powerhouse to design systems that are inherently responsive and scalable. By decoupling components, EDA allows systems to react to events independently, ensuring high availability and performance even as complexity grows. For example, when a document is updated, different processes like validation, notifications, and analytics generation can run in parallel without blocking each other. This architecture makes Powerhouse systems highly efficient in handling distributed operations, as it allows them to scale dynamically by adding or replicating components where needed. It also improves fault tolerance, as failures in one part of the system do not cascade to others due to the loosely coupled design. - **Asynchronous Workflows -** EDA is particularly effective in supporting asynchronous workflows, which are critical for decentralized organizations. In this model, components communicate through events, eliminating the need for direct dependencies. This loose coupling enables workflows to operate flexibly, allowing different tasks to be executed simultaneously without blocking others. For instance, when a contributor submits work, separate processes—like task approval, logging, and analytics—can run independently, ensuring smoother coordination. Additionally, event histories can be replayed to debug workflows or audit past operations, providing transparency and traceability essential to decentralized systems. --- ## Part 4: Scalable Network Organizations (SNOs) > Source: https://academy.vetra.io/bookofpowerhouse/SNOsandANewModelForOSSandPublicGoods Decentralized Autonomous Organizations (DAOs) once promised to revolutionize global collaboration by enabling decentralized governance, transparent decision-making, and equitable ownership. However, the reality has often fallen short. DAOs have struggled with legal ambiguity, resource allocation inefficiencies, and broken incentive structures. These challenges have stifled their ability to scale and compete with centralized organizations. Scalable Network Organizations (SNOs) emerge as the next evolutionary step. Combining the principles of decentralization with the operational rigor of traditional organizations, SNOs provide a structured framework for decentralized governance, sustainable operations, and global scalability. Powerhouse’s vision for SNOs aims to deliver on the original promise of DAOs, empowering organizations to scale without sacrificing their decentralized principles. ### Core Components of SNOs[](https://staging.powerhouse.academy/docs/bookofpowerhouse/SNOsandANewModelForOSSandPublicGoods#core-components-of-snos) At the heart of Scalable Network Organizations (SNOs) are five entities, each fulfilling a critical role in scaling decentralized operations. From governance to funding and IP management, these components work together to ensure alignment, collaboration, and financial sustainability. - DAO - The DAO is the governing entity responsible for setting the strategic vision and ensuring alignment across the SNO. Through on-chain governance mechanisms powered by smart contracts, the DAO facilitates transparent decision-making, distributed ownership, and accountability. Members participate in proposing and voting on budgets, initiatives, and key operational decisions, creating a decentralized system where authority is widely distributed rather than concentrated in a single entity. - By maintaining immutable records and eliminating the need for intermediaries, the DAO supports scalable and adaptable governance structures that suit decentralized networks. Its ability to flexibly adapt rules and processes ensures that the SNO remains efficient and innovative as it grows, while retaining the values of transparency and inclusivity. - Operational Hub (OH) - The Operational Hub acts as the administrative core of the SNO, handling contributor relationships, compliance, and payment processing. By leveraging legal structures like Swiss Associations, the OH ensures contributors are protected from liability while enabling the SNO to interact with banks, vendors, and regulatory entities. This hub simplifies complex operations such as tax reporting, cross-border compliance, and contributor agreements, removing these burdens from individual participants. - The Operational Hub acts as the administrative core of the SNO, handling contributor relationships, compliance, and payment processing. By leveraging legal structures like Swiss Associations, the OH ensures contributors are protected from liability while enabling the SNO to interact with banks, vendors, and regulatory entities. This hub simplifies complex operations such as tax reporting, cross-border compliance, and contributor agreements, removing these burdens from individual participants. - Operational Collateral Fund (OCF) - The OCF provides the financial infrastructure to fuel the SNO’s growth. It allocates resources to high-potential initiatives and rewards contributors by issuing Proof of Work Tokens (POWTs). These tokens align incentives by linking compensation to measurable contributions, ensuring that individuals and teams are motivated to create long-term value. POWTs represent a stake in the success of the network, making contributors invested in the outcomes of the projects they support. - Beyond its internal role, the OCF also attracts external investment by offering structured opportunities for funding impactful projects within the network. By maintaining transparency in its allocation processes and linking funding to measurable outputs, the OCF builds trust among both contributors and investors, creating a virtuous cycle where capital supports meaningful innovation. - Revenue Generating Hub (RGH) - The RGH is the SNO’s commercial interface, enabling the network to generate sustainable revenue while maintaining its decentralized principles. It manages licensing agreements, product sales, and customer-facing activities, ensuring that all revenue-generating operations align with the broader goals set by the DAO. By addressing the regulatory complexities associated with handling fiat revenue or contractual obligations, the RGH provides a seamless bridge between decentralized networks and traditional market systems. - The RGH supports multiple revenue streams, including enterprise licensing for proprietary versions of open-source software, subscription models for SaaS offerings, and consulting services tailored to client needs. A portion of the revenue collected flows back into the ecosystem, funding operations, rewarding contributors through the OCF, and sustaining the open-source projects that drive the SNO’s long-term success. - IP-Holding Entity (IPSPV) - The IP-Holding Entity safeguards the SNO’s intellectual property assets, including trademarks, copyrights, and other IP rights. It is responsible for enforcing licensing agreements and ensuring that the use of the network’s IP aligns with governance decisions made by the DAO. By employing a dual licensing model, the IPSPV supports open-source availability through copyleft licenses while generating revenue from enterprise licenses, allowing businesses to use proprietary versions of the SNO’s software. - The IPSPV also plays a critical role in protecting the network’s creative assets from exploitation or infringement. It ensures that the IP is managed as a collective resource, aligned with the community’s mission and values, while providing a steady revenue stream for reinvestment into the ecosystem. By separating IP management from operational activities, the IPSPV ensures that the SNO remains focused on innovation without losing control of its most valuable assets. ### Legal Foundations for SNOs[](https://staging.powerhouse.academy/docs/bookofpowerhouse/SNOsandANewModelForOSSandPublicGoods#legal-foundations-for-snos) Legal structures are crucial for the success of SNOs, providing clarity, compliance, and protection. - Multisig Participation Agreements (MPAs) \ MPAs are a foundational legal tool within the SNO framework. These agreements define the roles and responsibilities of multisig wallet signers, ensuring accountability and mitigating internal liability risks. By formalizing governance processes, MPAs reduce the chaos and inefficiency often associated with decentralized decision-making. They also protect contributors by clarifying liability boundaries, preventing signers from inadvertently exposing themselves to legal risks. \ MPAs are fully customizable, allowing SNOs to adapt them to their specific operational needs. They integrate seamlessly with Gnosis Safe wallets, creating a transparent and secure environment for managing resources. - Swiss Associations \ Swiss Associations offer a flexible and cost-effective legal wrapper for early-stage SNOs. These entities provide liability protection, separate legal personhood, and the ability to engage in commercial activities that support the SNO’s mission. Notably, Swiss Associations do not require registration, preserving privacy while maintaining compliance. Their reputation as part of Switzerland’s crypto-friendly regulatory environment makes them ideal for DAOs transitioning into SNOs. These are typically used as legal structures for the OCR and IPSPV, while the OH and RGH may be Swiss foundations but their jurisdiction is likely determined by where inbound and outbound payments are taking place. - Open Source Legal Templates \ Powerhouse has developed a library of open-source legal templates to simplify the setup and operation of SNO entities. These templates include Contributor Agreements, MPAs, and licensing contracts, reducing the complexity and cost of navigating legal requirements. By standardizing these processes, Powerhouse enables SNOs to focus on innovation and growth. --- ## **Part 5: Powerhouse Platforms – Decentralized Operations and Builder** > Source: https://academy.vetra.io/bookofpowerhouse/SNOsInActionAndPlatformEconomies ## **Introduction** The Powerhouse architecture is not only organizational but also deeply technological. To enable scalable network organizations (SNOs) to operate effectively, Powerhouse has developed two core platforms that provide the infrastructure for decentralized coordination and execution: the **Decentralized Operations Platform** and the **Builder Platform**. These platforms are complementary: one structures and stabilizes daily operations; the other opens up participation and innovation. Together, they form the digital substrate of the Powerhouse model, encoding its governance logic, collaboration structures, and incentive mechanisms directly into software. --- ## **Decentralized Operations Platform** The Decentralized Operations Platform serves as the operational engine of a SNO. It provides the workflows, rules, and execution logic required for contributors to collaborate without a central management layer. This includes systems for compensation, budgeting, IP management, and contributor reputation. At its core, the platform acts as a programmable coordination system. Contributors are onboarded, assigned tasks, compensated, and recognized through transparent, rule-based processes encoded in smart contracts and synchronized document models. These workflows are not static: they evolve based on activity, inputs, and contributor feedback, adapting to the changing needs of the network. The Decentralized Operations Platform also embeds accountability. Actions taken on the platform generate verifiable records—both financial and reputational—that form a shared source of truth. Disputes can be resolved, work can be audited, and contributors can prove their track record across projects and teams. This persistent memory allows SNOs to grow while retaining coherence and trust. Strategically, the platform supports multiple service categories, including governance operations, legal and financial services, and compliance. Each of these is modular, and the marketplace of service providers enables networks to plug in what they need, when they need it. Revenue is structured around project-based transactions and reinforced by policies that encourage on-platform fulfillment, ensuring alignment across stakeholders. --- ## **Builder Platform** While the Decentralized Operations Platform governs execution, the Builder Platform governs creation. It is designed for extending the Powerhouse architecture—enabling developers and contributors to build new tools, workflows, and modules that others in the ecosystem can use. The Builder Platform represents a shift in how coordination infrastructure is developed. Instead of building monolithic applications, contributors define document types, schemas, automation rules, and interfaces as reusable modules. These are published to a shared registry, where they can be discovered, forked, extended, or monetized. Every time a module is used in another network’s deployment, its original authors receive a share of the value generated. In this way, Powerhouse makes open-source infrastructure economically sustainable and creates a new incentive model for public goods. Technically, the Builder Platform is integrated with the rest of the Powerhouse stack. Its outputs are interoperable with the Operations Platform, the Governance layer, and the contributor onboarding systems. It uses typed schemas, CLI scaffolding, and standardized packaging to ensure modules are composable and production-ready. Strategically, the platform ensures that innovation remains decentralized. No single team or organization controls what can or cannot be built. Any contributor with sufficient context and intent can extend the system—and be rewarded for doing so. This model transforms Powerhouse from a static platform into a living ecosystem. --- ## **A Unified Infrastructure Layer** Together, these platforms operationalize the vision of scalable, decentralized networks. The Operations Platform provides the scaffolding for work: roles, rules, payments, and projects. The Builder Platform enables the ecosystem to evolve: by building, sharing, and monetizing new capabilities. They are not products to be sold—they are foundational infrastructure for a new kind of organization. Powerhouse is not simply offering software; it is building the operating system for a post-corporate world. --- # Release Notes ## Powerhouse v5.3.0 🚀 > Source: https://academy.vetra.io/academy/ReleaseNotes/v5.3.0 ## ✨ Highlights 1. **Authentication & Permissions** - CLI authentication and document-level permissions 2. **Improved Code Generation** - TS Morph and templates for faster, more reliable generation 3. **Runtime Document Model Subgraphs** - No more generated subgraph code to manage This release focuses on authentication, permissions, improved code generation, and runtime document model subgraphs. ## 🔐 CLI Authentication New commands for authentication workflows: | Command | Description | | ----------------- | --------------------------------------------- | | `ph login` | Authenticate with your Powerhouse identity | | `ph access-token` | Generate access tokens for API authentication | The CLI now supports full authentication workflows for secure operations and programmatic API access. ## 🛡️ Document Permission Service Fine-grained access control at the document level for Switchboard. - **Operation Permissions** - Control who can perform specific operations - **Document Group Permissions** - Organize documents with shared access rules - **Feature Flag** - Enable/disable via configuration When enabled, all document operations are validated against permission rules. Enterprise-grade access control that integrates seamlessly with existing Switchboard deployments. ## 📊 Autogenerated Document Model Subgraphs Subgraphs are now **automatically available** on Switchboard at runtime. ### ⚠️ Action Required Previously generated subgraphs should be **deleted** to avoid conflicts. This eliminates manual subgraph generation and maintenance. Clean up old generated files to prevent runtime conflicts. ## ⚛️ New React Hooks `useGetDocument` and `useGetDocuments` ```typescript const getDocument = useGetDocument(); const onDocumentSelected = async (id: string) => { const document = await getDocument(id); // Fetch on demand }; ``` ## ⚛️ Dispatch Callbacks Optional callbacks to handle results of dispatched actions. ```typescript const [document, dispatch] = useDocumentById(documentId); dispatch( myAction, (errors) => { // Handle errors (e.g., show toast notification) alert(errors); }, (document) => { // Handle success console.log("Document updated:", document); }, ); ``` Useful for showing toast notifications or triggering follow-up actions based on dispatch results. ## ⚛️ React Hooks Bug Fixes - Hooks returning multiple documents now correctly update when any document changes - Improved React Suspense integration to avoid unnecessary loading states Thank you **Liberuum**! These improvements make working with documents more reliable and flexible. ## 🎨 Document Model Editor Improvements Enhanced state editing experience in the Document Model Editor. The Document Model Editor now provides a better experience for editing document state schemas with improved validation and feedback. ## 🛠️ Improved Code Generation Faster, more reliable code generation with **TS Morph** and **templates**. - Templates are easier to maintain and customize - More predictable output - Better error messages The new template-based approach makes codegen more maintainable and gives developers clearer error messages when something goes wrong. ## 📝 Updated Editor Boilerplate Better starting point for custom editors with improved default styling. The new boilerplate includes DocumentToolbar integration, proper state management with hooks, and cleaner default styles. ## 🔄 Migration Steps 1. **Run migrations** - `ph migrate` 2. **Update editor styles** - Editors now control their own padding 3. **Delete document model subgraphs** - Remove generated subgraphs to avoid conflicts 4. **Update config files** - Add `vitest.config.ts` to `tsconfig.json` exclude and ESLint's `allowDefaultProject` Follow these steps carefully for a smooth upgrade to v5.3.0. ## 📚 Documentation Coming soon to **https://academy.vetra.io** - Reactor API Authorization - Document Permission System - Inspector Modal guide - Updated hooks documentation - Vetra Studio usage guides --- ## Powerhouse v6.0.0 🚀 > Source: https://academy.vetra.io/academy/ReleaseNotes/v6.0.0 ## ✨ Highlights 1. **Redesigned Reactor with sync reliability** — Complete rewrite of the write model, sync pipeline, and job system with quarantine, dead letters, paging, and FIFO batching 2. **Vetra Package Ecosystem** — Private npm-compatible registry, `ph publish/install/unpublish`, and dynamic package loading at runtime in Connect and Switchboard 3. **Reactor Attachments** — New `reactor-attachments` package for document-linked file storage with reservations, direct upload, and soft-delete 4. **Switchboard Load Balancer** — Built-in `switchboard-lb` for multi-node deployments with least-conn routing and drive-id-based pinning 5. **Full Observability** — OpenTelemetry metrics, Sentry source map uploads, Prometheus exporter, and OTel-to-Sentry span bridging ## ⚙️ Reactor — Rewritten Write Model & Sync Engine The reactor's core write model was fundamentally rearchitected to unify transactions with execution context. The sync pipeline gained per-document quarantine (instead of blocking entire remotes), a persistent dead-letter store, buffered batched mailboxes, abort signals on GQL channels, and cursor-based paging for large sync batches. Key additions: - **DocumentIntegrityService** — validates and rebuilds document keyframes/snapshots - **Sync paging** — `getOperations` now pages across scopes - **Job timeout** via abort signals propagated through the entire job pipeline - **Yield utilities** for cooperative scheduling in the job executor - **Exponential backoff + jitter** on retries - **`test-sync-queue` CLI app** for detecting sync drift on large drives ```bash # New profiling script for direct reactor performance testing npx tsx profiling/reactor-direct.ts --docs 1000 --otel ``` ## 📦 Vetra Package Ecosystem A full end-to-end package ecosystem now powers Powerhouse apps. A private npm-compatible registry (Verdaccio-backed) hosts packages, and the CLI, Connect, and Switchboard all integrate with it. **New CLI commands:** ```bash # Publish a built package to the Powerhouse registry ph publish # Install from the registry (uses Powerhouse registry by default) ph install @your-org/your-package # Unpublish a package and purge the CDN cache ph unpublish @your-org/your-package@1.0.0 ``` **Dynamic loading:** Connect and Switchboard load processors and subgraphs at runtime from the HTTP registry — no rebuild required when new packages are published. **Auto-discovery:** Connect automatically finds and installs the correct package when it encounters an unknown document type. **Version picker:** The Connect UI lets users choose specific dist-tag versions when installing packages. ```json // powerhouse.config.json { "registry": "https://your-registry-url" } ``` ## 📎 Reactor Attachments New `reactor-attachments` package provides document-linked file storage, integrated directly into the reactor and switchboard. Features: - Upload reservations + direct upload to storage - Switchboard transport implementation - `HEAD` support, soft-delete, and case-insensitive hash indexing - `Attachment-Metadata` headers ## ⚖️ Switchboard Load Balancer New `switchboard-lb` package provides HTTP load balancing for multi-node Switchboard deployments: - **M1:** Least-connections proxying of upstream routes - **M2:** Request pinning across restarts - **M3:** Rewrite to drive-id header for deterministic routing ## 📊 OpenTelemetry & Sentry Observability ```bash # Enable OTel metrics export from Switchboard OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318 ph switchboard start # Prometheus metrics (opt-in) PROMETHEUS_METRICS=true ph switchboard start ``` - New `opentelemetry-instrumentation-reactor` package for distributed tracing across reactor internals - Sentry source maps uploaded in CI and releases tagged automatically - OTel spans bridged to Sentry for unified error correlation - Opt-out error reporting for `ph-cli` and `ph-cmd` via config - Lightweight Sentry SDK replaces full SDK in CLI ## 🪝 `useDocumentSafe` Hook ```typescript function MyEditor({ documentId }: { documentId: string }) { const { document, error, isLoading } = useDocumentSafe(documentId); if (isLoading) return ; if (error) return ; return ; } ``` Replaces the pattern of calling `useDocument` and catching thrown errors — now surfaces error and loading state as first-class values. ## 🤖 `ph code` Subcommand — AI Agent Harness ```bash # Launch an AI-assisted code generation session ph code ``` New subcommand that wires Mastra and ph-clint into the CLI for AI-powered code assistance scoped to your Powerhouse project. ## 🛡️ Per-Document Authentication - **Signature verification** on Switchboard: operations must carry a valid app-key signature - **Per-document protection model**: configure which documents require authentication - `ph login` / `ph logout` / `ph access-token` login flow now implemented in the Renown SDK and forwarded by the CLI ## 🔧 Codegen Improvements - **Versioned reducers by default** — reducers are version-stamped at generation time - **`satisfies DocumentModelModule`** instead of type casts - **CI/CD + Docker templates** scaffolded by `ph init` for new projects - **Vitest coverage** scaffolded with reducer threshold checks - **Separate `ph generate` commands** for reducers, editors, and processors - **AGENTS.md template** with editor drag-and-drop guidance and reducer testing playbook - **E2E codegen tests** for processor and subgraph generation ## 🖥️ Connect Improvements - **Processor inspector** panel showing live processor state - **Offline preview** for locally installed packages (bundled into Connect) - **PGlite migration banner** for DB version transitions - **Dump & import** for local PGlite database - **Version picker** UI for dist-tag selection - **Git hash display** in settings/URL for build traceability - **Drive info** shown in settings menu - **JSON viewer** in operations tooltip - **Retry on startup** for default drives with backoff ## 📡 Reactor MCP The `reactor-mcp` package now creates a fresh `McpServer` per `/mcp` request, fixing concurrent transport collision when multiple clients connect simultaneously. ## 🔄 Improvements - **tsdown** replaces the previous build toolchain across all packages: `analytics-engine`, `builder-tools`, `ph-cli`, `ph-cmd`, `registry`, `shared`, `design-system` - **Separate node/browser processor bundles** — processors now publish distinct `node` and `browser` entrypoints - **Tree-shaking** — `sideEffects: false` added to generated package boilerplate; pglite, jszip, and renown crypto are now lazy-loaded - **Document cache** made compatible with GraphQL clients directly - **Remote document controller** in `reactor-browser` for server-driven document state - **Single batch query** in `reactor-browser` for pulling operations on remote controllers - **Switchboard**: dynamic model loading behind `DYNAMIC_MODEL_LOADING` env var; OTel provider registration ordering enforced - **Registry**: SSE + webhook publish notifications; npm uplink for transparent CDN fallback; Renown JWT auth in front of Verdaccio - **`ph-cmd`** now delegates `init` and all forwarded commands to the versioned `ph-cli` binary — version pinning works correctly - **`ph migrate`** now runs against the target codegen version with `--force` flag available - **`ph install`**: `--allow-build` flag supported; prompts for dist-tag on prerelease publish ## 🐞 Bug Fixes - Reactor: orphan reshuffle and cross-batch FIFO bugs fixed; documents with out-of-order `ADD_RELATIONSHIP` now correctly backfilled - Reactor: deleted documents no longer returned by queries; jobs targeting deleted documents are not retried - Reactor: GQL channel now correctly handles abort signals, backpressure, and dead-letter placement - Connect: PGlite idb cleared on storage wipe to avoid flush race; duplicate document models deduplicated by type+version - Switchboard: falls back to a free port on `EADDRINUSE` and propagates to Vetra - Switchboard: `migrate` command now honors correct env vars - Registry: concurrent tarball extraction prevented; correct package version resolved on CDN - ph-cli: lazy-loaded for faster startup; `PH_REGISTRY_URL` env takes precedence over config - Design system: static asset paths fixed post-tsdown migration; icons path corrected ## ⚠️ Breaking Changes **Node.js 24 is now the minimum supported version.** ```bash # Check your Node version node --version # must be >= 24.0.0 # Install Node 24 via nvm nvm install 24 && nvm use 24 ``` **`DriveEditor` renamed** — a bulk rename was applied across all packages. Search your codebase for old `DriveEditor` references and update as directed by TypeScript. **Generated subgraph code should be deleted** — subgraphs are now generated and loaded at runtime. Delete any `src/subgraphs/` directory in your project to avoid conflicts. ```bash rm -rf src/subgraphs/ ``` --- # Miscellaneous ## 00-Home > Source: https://academy.vetra.io/academy/Home --- ## Prerequisites > Source: https://academy.vetra.io/academy/Build/GettingStartedBuilding/Prerequisites **TIP:** This **Build** chapter is the **manual experience** — you build Powerhouse packages by hand on your own machine with the Powerhouse CLI, controlling every step (document models, editors, processors, and publishing). If you'd rather have an AI agent build for you, use the **AI-guided experience** in [**Vetra Studio**](/academy/GetStarted/VetraStudio): you describe what you want in chat and the agent writes the specs and code for you — no local setup required. The two paths produce the same kind of package, so you can mix and match: prototype with the agent, then drop down to the manual workflow for fine-grained control. The rest of this section sets up your machine for the manual path and walks you through the end-to-end package workflow. It covers Node.js 24, VS Code, Git, and the Powerhouse CLI. **INFO:** If you've already set up **Git, Node.js 24, and a package manager (pnpm or npm)**, your most important step is to install the **Powerhouse CLI** with the command: `pnpm install -g ph-cmd` or `npm install -g 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 gives you direct access to a series of Powerhouse Builder Tools. Move to the end of this page to [verify your installation.](#verify-installation) --- ## Overview Before building your Document Model, install some software on your machine. You need three tools: - Node.js 24, which runs your code. - Visual Studio Code (VS Code), where you write your code. - Git, which manages your code. Follow the steps below based on your computer's operating system. ### Windows Users: Consider Using WSL If you're on Windows, we recommend using **Windows Subsystem for Linux (WSL)** for the best development experience. WSL lets you run a full Linux environment directly on Windows without the overhead of a virtual machine. This gives you access to Linux command-line tools and utilities, which are often preferred for modern web development workflows. **To install WSL:** 1. Open PowerShell as Administrator (right-click and select "Run as administrator") 2. Run the following command: ```powershell wsl --install ``` 3. Restart your computer when prompted 4. After restart, a terminal will open asking you to create a Linux username and password Once WSL is set up, you can follow the **Linux (Ubuntu/Debian)** instructions below for installing Node.js, Git, and other tools. Your Linux environment will be accessible through the Windows Terminal or by typing `wsl` in PowerShell. **TIP:** Using WSL provides a consistent development experience that matches most production environments and online tutorials. You can still use VS Code on Windows — it integrates with WSL through the [Remote - WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl). For more details, see the official [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install). --- ### Installing Node.js 24 Node.js 24 runs your application. Install it with the steps below. #### 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 24:** - Visit the [Node.js 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. **Install a package manager (pnpm or npm):** - Open PowerShell (no need for admin mode) - For pnpm (recommended), type this command and press Enter: ```powershell npm install -g pnpm ``` - Note: Node.js comes with npm by default, so npm is already available after installing Node.js 4. **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 # or npm --version ``` - Version numbers should appear after each command (e.g., v24.x.x for Node.js). If they do, Node.js and your package manager are installed. > **Note**: If Node.js 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 24:** - In the same Terminal window, type this command and press Enter: ```bash brew install node@24 ``` - Then, optionally install pnpm (npm comes with Node.js): ```bash brew install pnpm ``` 3. **Verify Installation:** - In Terminal, type these commands one at a time and press Enter after each: ```bash node --version pnpm --version # or npm --version ``` - If version numbers appear, Node.js and your package manager are installed. #### 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 24 and optionally pnpm:** ```bash sudo apt install nodejs # Optionally install pnpm (npm comes with Node.js) sudo apt install pnpm ``` 4. **Verify Installation:** - Type these commands one at a time and press Enter after each: ```bash node --version pnpm --version # or npm --version ``` - If version numbers appear, your installation is complete. ### 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 "Shell Command: 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" ``` ### Install the Powerhouse CLI The Powerhouse CLI (installed via the `ph-cmd` package) is a command-line interface tool. It provides the `ph` command, which is essential for managing Powerhouse projects. You can get access to the Powerhouse Ecosystem tools by installing them globally using: ```bash pnpm install -g ph-cmd ``` Or if you're using npm: ```bash npm 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 Use it to create, build, and run Document Models.

How to use different branches?

When installing or using the Powerhouse CLI commands you can use the dev & staging branches. These branches contain more experimental features than the latest stable release the PH CLI uses by default. They can be used to get access to a bug fix 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 latest** | Switch all dependencies to latest stable versions | | **ph use dev** | Switch all dependencies to development versions | | **ph use staging** | Switch all dependencies to staging versions | Please be aware that these versions can contain bugs and experimental features that aren't fully tested.

Managing ph-cmd Versions and Package Information

### Switching Between Versions To change to a different version of `ph-cmd`, reinstall it globally with your package manager: ```bash # Install latest version with a specific tag npm install -g ph-cmd@staging pnpm install -g ph-cmd@dev # Install a specific version number npm install -g ph-cmd@1.2.3-staging.10 pnpm install -g ph-cmd@6.0.0-dev.33 ``` **Important:** Always use the same package manager you used for the original global install to avoid conflicting installations. ### Checking Your Installation Use the `which` command to see where your global install is located: ```bash which ph # Example output: /Users/username/Library/pnpm/ph ``` This shows which package manager was used (in this case, pnpm). ### Viewing Available Versions Use `npm view` to see all available versions and tags: ```bash npm view ph-cmd ``` **Example dist-tags output:** ``` dist-tags: latest: 5.3.0 dev: 6.0.0-dev.33 staging: 5.3.0-staging.24 test: 2.5.0-test.0 ``` ### Best Practices - Use specific version numbers instead of tags when you need exact version consistency - Check `npm view ph-cmd` before switching to see the latest available versions - Remember that without specifying a version, `@latest` is installed by default

### Verify Installation Open your terminal (command prompt) and run the following commands to verify your setup: ```bash node --version pnpm --version git --version ph --version ``` You should see version numbers displayed for all commands, similar to the example output below (your versions might be higher). The output for `ph --version` includes its version and may also show additional messages if further setup like `ph setup-globals` is needed. You're now ready to start building your first Document Model! ```bash % node --version v24.13.0 % pnpm --version 10.10.0 % git --version git version 2.39.3 % ph --version PH CMD version: 0.43.18 ------------------------------------- PH CLI is not available, please run `ph setup-globals` to generate the default global project ``` ## Up next Your machine is ready. Next, set up your [Vetra Drive](/academy/Build/GettingStartedBuilding/VetraDrive) — the workspace where you'll manage document model specifications, editors, and data integrations. --- ## Vetra Drive > Source: https://academy.vetra.io/academy/Build/GettingStartedBuilding/VetraDrive ## Introducing Vetra Drive for Builders Vetra Studio is the builder environment where you create, manage, and collaborate on Powerhouse packages. It consists of two main components: - **Vetra Studio Drive**: Serves as a hub for developers to access, manage & share specifications through a remote Vetra drive. It functions as the orchestration hub where you as a builder assemble all the necessary specifications for your intended use-case, software solution, or package. Each specification document corresponds to a **module** — a distinct building block of your package (such as a document model, editor, or data integration). - **Vetra Package Library**: Store, publish, and fork git repositories of packages in the Vetra Package Library. Visit the [Vetra Package Library here](https://vetra.io/packages) **INFO:** What is a Specification Document? A **specification document** is a configuration file that defines how a specific module in your package should behave. Think of it as a blueprint: it describes the structure, rules, and relationships that Powerhouse uses to generate the actual code for that module. Specification documents make **Specification-Driven Design & Development** possible: you communicate your solution and intent through a structured framework designed for AI collaboration. Specs are a shared language that enables precise, iterative edits. As Vetra Studio matures, each of these specification documents will offer an interface by which you as a builder get more control over the modules that make up your package. For now, the specification documents offer you a template for code generation.

Modules — The list of available modules color coded according to the 3 categories.

### Module Categories ### 1. Document Models A **document model** is a structured data type that defines what information your application can store and how it can be modified. Unlike traditional databases, document models use **operations** (actions like "add item" or "update title") rather than direct data manipulation, making them ideal for collaborative and auditable applications. - **Document model specification**: Defines the structure and operations of a document model using [GraphQL SDL](https://graphql.org/learn/schema/) (Schema Definition Language), ensuring consistent data management and processing. → [Learn more about Document Models](/academy/Build/DocumentModelCreation/WhatIsADocumentModel) ### 2. User Experiences - **Editor specification**: Outlines the interface and functionalities of a document model editor, allowing users to interact with and modify document data. - **Drive-app specification**: Specifies the UI and interactions for managing documents within a drive, providing tailored views and functionalities. → [Learn more about Building Document Editors](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors) → [Learn more about Building a Drive Explorer](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) ### 3. Data Integrations - **Subgraph specification**: Details the connections and relationships within a subgraph (a subset of your data exposed via a GraphQL API), facilitating efficient data querying and manipulation. - **Codegen Processor Specification**: Describes the process for automatically generating code from document model specifications, ensuring alignment with intended architecture. - **RelationalDb Processor Specification**: Defines how relational databases are structured and queried, supporting efficient data management and retrieval. → [Learn more about Using Subgraphs](/academy/Build/WorkWithData/UsingSubgraphs) → [Learn more about Relational DB Processor](/academy/Build/WorkWithData/RelationalDbProcessor)

The Vetra Studio Drive, a builder app that collects all of the specifications of a package.

### Configure a Vetra Drive in Your Project You can connect to a remote Vetra drive instead of using the local one auto-generated when you run `ph vetra` (where `ph` is short for "powerhouse", the CLI tool and the Organization behind Vetra). - **Without** the `--remote-drive` option: Vetra will create a local drive for you that lives in your browser's local storage. This is useful for solo development or experimentation. - **With** the `--remote-drive` argument: Vetra will connect to a remote drive instead of creating a local one. The remote drive can be hosted wherever you want (e.g., on your own server or a shared team environment). The Powerhouse config includes a Vetra URL for consistent project configuration across different environments. ```typescript vetra: { driveId: string; driveUrl: string; } ``` Imagine you are a builder and want to work on, or continue with a set of specifications from your teammates. You could then add the specific remote Vetra drive to your Powerhouse configuration in the `powerhouse.config.json` file to get going: ```json "vetra": { "driveId": "bai-specifications", "driveUrl": "https://switchboard.staging.vetra.io/d/bai-specifications" } ``` An example of a builder team building on the Powerhouse Vetra Ecosystem and its complementary Vetra Studio Drive specifications for the different packages can be found [here](https://vetra.io/builders/bai). ### Connect Claude to the Reactor MCP Claude can connect directly to your running Reactor via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), giving it live access to your drives, documents, and document model operations. Add the following configuration to your Claude MCP settings (e.g. `~/.claude/mcp.json` for Claude Code, or the MCP servers section in Claude Desktop): ```json { "mcpServers": { "reactor-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:4001/mcp"] } } } ``` This connects Claude to the Reactor running at `http://localhost:4001`. Make sure `ph vetra --watch` (or `ph reactor`) is running before starting a Claude session that uses the MCP. → See [Connecting Claude with Reactor MCP](/academy/Lookup/Cookbook#connecting-claude-with-reactor-mcp) for a step-by-step walkthrough.

📦 Vetra Remote Drive Commands

Remote drives enable collaborative development by syncing specifications across team members. **Key Commands:** - `ph init --remote-drive ` - Create or connect to a project using a remote drive - `ph vetra --watch` - Start development with a preview drive for testing local changes **Workflows:** - **Project Owner**: `ph init --remote-drive` → Create GitHub repo → Push → `ph vetra --watch` to configure - **Collaborator**: `ph init --remote-drive ` → `ph vetra --watch` to start developing **Preview Drive (`--watch` mode):** The preview drive allows you to safely test changes before they affect the shared remote drive. - The main **"Vetra" drive** syncs with the remote and contains the stable package configuration. - The **"Vetra Preview" drive** is created locally for testing document models and editors before syncing your changes to the team. - When restarting Vetra, always use `ph vetra --watch` so it loads your local documents and editors. → [Full Vetra Remote Drive Reference](/academy/Reference/CLITooling/VetraRemoteDrive)

## Up next With your drive set up, [create a package with Vetra](/academy/Build/GettingStartedBuilding/CreateAPackageWithVetra) to see the end-to-end flow, then build one by hand in the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/ExploreDemoPackage). --- ## Create a package with Vetra > Source: https://academy.vetra.io/academy/Build/GettingStartedBuilding/CreateAPackageWithVetra **INFO:** A **Powerhouse Package** is a distributable unit that bundles one or more document models, editors, and optional reactor modules into a single installable artifact. Once published to the Vetra registry, a package can be installed in any Vetra Cloud environment — extending Connect with new document types and editors, and extending Switchboard with the corresponding reactor logic.

On Vetra Cloud you'll find these steps as a quick reference for creating a package. This guide walks you through each one in detail — from installing the CLI and scaffolding your project to building and testing document models and editors. Publishing is covered separately in [Launch](/academy/Build/Launch/PublishYourProject). **WARNING:** **This tutorial is a summary for builders that are already familiar with building document models**. It summarizes the flow from initial setup to a built, tested package. Please start with the [**Manual Todo tutorial**](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) or the [**Document Model Creation**](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema) section if you are unfamiliar with building a document model.

Key commands that you'll use in this flow

- `pnpm install -g ph-cmd` or `npm install -g ph-cmd`: Installs the Powerhouse CLI globally. - `ph init`: Initializes a new Powerhouse project or sets up the local environment. - `ph vetra --interactive`: Launches Vetra Studio in interactive mode for package development. - `ph vetra --interactive --watch`: Launches Vetra Studio with dynamic reloading for document-models and editors. - `ph build`: Builds the project for production. - `pnpm run test` or `npm test`: Runs unit tests. - `ph publish`: Publishes your package to the Vetra registry. - `ph install @your-org-ph/your-package-name`: Installs a published package into a local Powerhouse environment.

## Phase 1: Setup and initialization ### 1.1. Install Powerhouse CLI Ensure you have the Powerhouse Command Line Interface (`ph-cmd`) installed. You use it to manage your Powerhouse projects. ```bash pnpm install -g ph-cmd ``` Or if you're using npm: ```bash npm install -g ph-cmd ``` **INFO:** See the [Prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites) guide for detailed installation instructions for Node.js 24, package managers (pnpm or npm), and Git if you haven't set them up yet. ### 1.2. Initialize your project environment Before creating a specific project, or if you're setting up your environment for the first time, initialize the Powerhouse environment. This command prepares your local setup, including a local Reactor configuration. ```bash ph init my-package ``` Replace `my-package` with your desired package name. If you run `ph init` without a name you will be prompted for one.

How to make use of different branches?

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 than 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** or **npm install -g ph-cmd** | Install latest stable version | | **pnpm install -g ph-cmd@dev** or **npm install -g ph-cmd@dev** | Install development version | | **pnpm install -g ph-cmd@staging** or **npm 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 latest** | Switch all dependencies to latest stable versions | | **ph use dev** | Switch all dependencies to development versions | | **ph use staging** | Switch all dependencies to staging versions | Please be aware that these versions can contain bugs and experimental features that aren't fully tested.

### 1.3. Launch Vetra Studio You can launch Vetra Studio in two modes: #### Interactive Mode (Recommended for Development) ```bash ph vetra --interactive ``` In interactive mode: - You'll receive confirmation prompts before any code generation - Changes require explicit confirmation before being processed - Provides better control and visibility over document changes #### Watch Mode ```bash ph vetra --interactive --watch ``` In watch mode: - Adding `--watch` to your command enables dynamic loading for document-models and editors in Vetra studio and switchboard. - When enabled, the system will watch for changes in these directories and reload them dynamically. **WARNING:** When you are building your document model the code can break the Vetra Studio environment. A full overview of the Vetra Studio commands can be found in the [Powerhouse CLI](/academy/Reference/CLITooling/PowerhouseCLI#vetra) #### Standard Mode ```bash ph vetra ``` In standard mode: - Changes are processed automatically with 1-second debounce - Multiple changes are batched and processed together - Uses the latest document state for processing

Alternatively: Use Connect

Connect is your local development hub. Running it in Studio Mode spins up a local instance with a local Reactor, allowing you to define, build, and test document models. ```bash ph connect ``` This command typically opens Connect in your browser at `http://localhost:3000/`. **INFO:** **Powerhouse Reactors** are essential nodes in the Powerhouse network. They store documents, manage versions, resolve conflicts, and verify document operation histories by rerunning them. Reactors can be configured for local storage (as in Studio Mode), centralized cloud storage, or decentralized storage networks.

### 1.4. Launch Claude with Reactor-MCP Vetra Studio connects to Claude through MCP (Model Context Protocol). This gives you greater control and direction over what the LLM codes for you. **INFO:** Vetra embraces **Specification Driven Design & Development** —an approach where your structured specification documents become the shared language between you and AI agents. You communicate intent through precise specs that are machine-readable and executable.

Explainer: Specification Driven AI

In the **Manual Todo tutorial** we've been making use of strict schema definition principles to communicate the intended use case of our document models. The **schema definition language** is not only a shared language that bridges the gap between developer, designer and analyst but also the gap between builder and AI-agent through **specification driven AI control**. - Communicate your solution and intent through a structured specification framework designed for AI collaboration. - Specifications enable precise, iterative edits, since all our specification documents are machine-readable and executable. #### Key Reactor MCP Features **Reactor-mcp** is a Model Context Protocol (MCP) server that bridges AI agents with Powerhouse document operations. - It supports automatic document model creation from natural language descriptions - It implements a smart editor based on the underlying document models - It automatically triggers code generation when documents reach valid state - The MCP server enables the agent to work with both existing and newly created document models - Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives **Document Operations:** - `createDocument` / `getDocument` / `deleteDocument` - Manage documents - `addActions` - Modify document state through operations **Drive Operations:** - `getDrives` / `addDrive` / `getDrive` - Manage document drives - `addRemoteDrive` - Connect to remote drives **Document Model Operations:** - `getDocumentModels` - List available document model types - `getDocumentModelSchema` - Get schema for specific models **Document Model Agent:** A specialized AI agent that guides users through document model creation with requirements gathering, design confirmation, and implementation including state schema definition, operation creation, and code generation.

#### 0. Configure the Reactor MCP Add the following to your Claude MCP settings (`~/.claude/mcp.json` for Claude Code, or the MCP servers section in Claude Desktop): ```json { "mcpServers": { "reactor-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:4001/mcp"] } } } ``` This only needs to be done once. Make sure `ph vetra` is running before starting a Claude session that uses the MCP. #### 1. Start the Reactor MCP: Make sure you are in the same directory as your project. Claude will automatically recognize the necessary files and MCP tools. ```bash claude ``` Claude also understands natural language, so similar phrasings work as well. ```bash connect to the reactor mcp ``` #### 2. Verify MCP connection: - Check that the Reactor MCP is available. - Confirm Vetra Studio shows "Connected to Reactor MCP" ```bash Connected to MCP successfully! I can see there's a "vetra-4de7fa45" drive available. The reactor-mcp server is running and ready for document model operations. or Connected to reactor MCP. You have access to 1 drive: vetra+a049e1b1== ``` ## Phase 2: Package Creation ### 2.1. Set Package Description (Required) 1. Provide a name for your package 2. Add a meaningful description 3. Add keywords to add search terms to your package 4. Confirm changes when prompted in interactive mode ### 2.2. Define Document Model (Required) You can create document models in two ways: #### Manual Creation - Define document schema with fields and types as in the **Manual Todo tutorial** - Create the necessary operations - Add the required modules to your package - The document model creation chapter in the Mastery track provides in depth support [here](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema) → [Learn more about Document Models](/academy/Build/DocumentModelCreation/WhatIsADocumentModel) #### Using MCP (AI-Assisted) - Describe your package, it's functionality and your needs in natural language in great detail. - Claude will: - Generate an appropriate schema in the document model - Create the necessary operations - Implement the required reducers - Place the document in the Vetra drive - Claude will also add the necessary interface in the form of a [document editor](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors) and scaffold the [drive-app functionality](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) when specified. → [Learn more about Building Document Editors](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors) → [Learn more about Building a Drive Explorer](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer)

Alternatively: Use Connect

Within Connect Studio Mode, navigate to the Document Model Editor. Here, you'll specify the structure of your document model using GraphQL Schema Definition Language (SDL). - **State Schema:** Describes the data fields and types within your document (e.g., `ToDoItem` with `id`, `text`, `checked` fields). - This schema is the blueprint for your document model's data. In the same editor, specify the operations (state transitions) for your document model. These are also defined using GraphQL, specifically input types. - **Operations Schema:** Specifies the actions that can be performed on the document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`). - Each input type details the parameters required for an operation. - **Best Practices:** - Clearly define operations (often aligning with CRUD principles). - Use GraphQL input types for operation parameters. - Ensure operations reflect user intent for a clean API. Once your schema and operations are defined in Connect, export the specification. This will download a `.phdm.zip` file (e.g., `YourModelName.phdm.zip`). Save this file in the root of your Powerhouse project directory. Use the Powerhouse CLI to process an exported `.phdm.zip` file and generate the necessary boilerplate code for your document model. ```bash ph generate document-model --document YourModelName.phdm.zip ``` This command creates a new directory under `document-models/YourModelName/` containing: - A JSON file with the document model specification. - A GraphQL file with the state and operation schemas. - A `gen/` folder with autogenerated TypeScript types, action creators, and utility functions based on your schema. - A `src/` folder where you'll implement your custom logic (reducers, utils).

### 2.3. Add Document Editor (Required) #### Manual Creation - Select your target document model - Configure the currently limited editor properties - Add the editor specification to Vetra Studio drive - The system will generate scaffolding code #### Using MCP (AI-Assisted) - Request Claude to create an editor for your document. Do this with the help of a detailed description of the user interface, user experience and logic that you wish to generate. Make sure to reference operations from the document model to get the best results - Claude will: - Generate editor components - Implement necessary hooks - Create required UI elements → [Learn more about Building Document Editors](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors)

Alternatively: Generate command

A document editor provides the user interface for interacting with your document model. Generate an editor template: ```bash ph generate editor --name YourModelName --document-type powerhouse/YourModelName ``` - The `--name YourModelName` flag specifies the document model this editor is for. - The `--document-type powerhouse/YourModelName` flag links the editor to the specific document type defined in your model specification. This creates a template file, typically at `editors/your-model-name/editor.tsx`. - Customize this React component to build your UI. - You can use standard HTML, Tailwind CSS (available in Connect), or import custom CSS. - Utilize components from `@powerhousedao/document-engineering` for consistency and rapid development. Learn more at [Document-Engineering](/academy/Reference/EditorsUI/DocumentEngineering)

## Phase 3: Implementation and testing ### 3.1. Implement reducer logic Reducers are pure functions that implement the state transition logic for each operation defined in your schema. Navigate to `document-models/YourModelName/src/reducers/to-do-list.ts` (or similar, based on your model name). - Implement the functions for each operation (e.g., `addTodoItemOperation`, `updateTodoItemOperation`). - These functions take the current state and an action (containing input data) and return the new state. - Powerhouse handles immutability behind the scenes. ### 3.2. Write unit tests for reducers Test your reducer logic. Write unit tests in the `document-models/YourModelName/src/reducers/tests/` directory. - Verify that each operation correctly transforms the document state. - Use the auto-generated action creators from the `gen/` folder to create operation actions for your tests. Run tests using: ```bash pnpm run test ``` Or with npm: ```bash npm test ``` ### 3.3. Test the editor Test your editor in Vetra Studio by creating a new document of your defined type. Interact with your editor, test all functionalities, and ensure it correctly dispatches actions to the reducers and reflects state changes.

Alternatively: Use Connect

Run Connect locally to see your editor in action: ```bash ph connect ``` Create a new document of your defined type. Interact with your editor, test all functionalities, and ensure it correctly dispatches actions to the reducers and reflects state changes.

**TIP:** **Working with MCP and Claude** 1. Provide clear, specific instructions. 2. Ask for clarifying questions to be answered before code generation. 3. Review generated schemas before confirmation. 4. Work in layers instead of 'one-shotting' your code. 5. Verify implementation details in generated code before continuing. 6. Always double-check proposed next actions.

Complete Guide: Tips for Working with Claude in Vetra Studio

## Before You Start **Setup Requirements:** 1. Run `ph vetra --interactive --watch` in one terminal first 2. Start Claude in a separate terminal from your project directory 3. Connect with: `claude` or `connect to the reactor mcp` 4. Verify you see the confirmation message with your drive name ## Communication Best Practices ### 1. Always Review Before Implementation **CRITICAL**: Claude will present a proposal before creating anything. You'll see: - Proposed document model structure (state schema, operations, modules) - How data will be organized - What actions users can perform **Always review and confirm** before Claude proceeds. This is your chance to adjust the design. ### 2. Be Specific and Detailed When describing what you need, include: **For Document Models:** - Purpose of the document (what problem does it solve?) - All data fields and their types (strings, numbers, dates, etc.) - What operations users should be able to perform - Any relationships between data - Business rules or constraints **For Document Editors:** - Which document model it's for - UI layout and components you want - User interactions and workflows - Specific operations to use (by name from your document model) - Any styling preferences ### 3. Use Clear Examples Good prompt for a document model: ``` Create a document model for expense tracking with: - Each expense has: amount (number), description (text), category (expense type), date, and receipt URL (optional) - Users can: add expenses, edit expense details, delete expenses, and categorize by type - Track total amount automatically ``` Good prompt for an editor: ``` Create an editor for the expense tracker with: - A form to add new expenses (amount, description, category, date) - A table showing all expenses with sort by date - Each row has edit and delete buttons - Show total at the bottom - Use the addExpense, updateExpense, and deleteExpense operations ``` ### 4. Work in Layers (Don't "One-Shot") Instead of asking for everything at once: - ✅ Start with the core document model - ✅ Test it works - ✅ Then add the editor - ✅ Then add advanced features This approach catches issues early and gives you better results. ### 5. Interactive Mode Benefits Using `ph vetra --interactive` gives you confirmation prompts: - Schema changes - Operation definitions - Code generation **Review each step** before confirming - it's easier to adjust now than later. ### 6. What to Expect After Implementation Claude will automatically: - Run TypeScript checks (`npm run tsc`) - Run linting (`npm run lint:fix`) - Report any errors found - Fix issues if needed You'll see confirmation when everything compiles successfully. ### 7. Common Issues and How to Avoid Them **Issue**: Generated model doesn't match expectations - **Solution**: Provide more detailed requirements upfront. Ask clarifying questions. **Issue**: Operations don't work as expected - **Solution**: Be explicit about all actions and their parameters. Use real-world examples. **Issue**: Editor UI doesn't look right - **Solution**: Describe the UI in detail (layout, components, interactions). Reference similar interfaces if helpful. ## Key Concepts to Know - **Document Model**: The template/blueprint for your documents (like a database schema) - **Document**: An actual instance with real data (like a database record) - **Operations**: Actions users can perform (like "add expense", "update status") - **Editor**: The user interface to interact with your documents - **Drive**: A collection that holds your documents (like a folder) ## Quick Tips 1. **Be specific**: More detail = better results 2. **Review proposals**: Always check before confirming 3. **Work incrementally**: Build in layers, not all at once 4. **Use operation names**: Reference them when describing editor functionality 5. **Ask questions**: If unsure, ask Claude to clarify or suggest options 6. **Test as you go**: Create model first, test it, then add the editor ## What Claude Can Do For You - Generate complete document models from natural language - Create all necessary operations automatically - Build React editor interfaces with your specifications - Handle all the TypeScript and boilerplate code - Fix type errors and linting issues - Add demo documents to test your models ## What You Should Focus On - Clearly describing your business requirements - Defining what data you need to track - Specifying what actions users should perform - Reviewing and confirming proposals - Testing the generated results **Remember**: Claude works best with clear, detailed requirements. Take time to explain what you want - it's faster than multiple iterations to fix misunderstandings.

## Phase 4: Package and publish With your document model and editor implemented and tested, package and publish them for distribution. Publishing is covered in one place for both the manual and Vetra workflows — it walks through configuring package details, building, versioning, and publishing to NPM or the Vetra registry: → [Publish your package](/academy/Build/Launch/PublishYourProject) ## Up next You've seen the full Vetra flow. Now build a package by hand, step by step, in the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/ExploreDemoPackage). --- ## Vetra builder tooling > Source: https://academy.vetra.io/academy/Build/GettingStartedBuilding/BuilderTools An overview of the builder tooling in the Powerhouse/Vetra ecosystem, for the manual (CLI) builder workflow. This list grows as the toolkit does. ## Powerhouse CLI The Powerhouse CLI (`ph-cmd`) is the command-line entry point for building by hand: scaffolding projects, generating code, and running Connect and the Reactor locally. - Install it and verify your setup in [Prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites). - For the full command list — `ph init`, `ph use`, `ph update`, `ph generate`, and the rest — see the [Powerhouse CLI reference](/academy/Reference/CLITooling/PowerhouseCLI). - For task-oriented walkthroughs (switching versions, managing dependencies, publishing), see the [Cookbook](/academy/Lookup/Cookbook). ## Boilerplate The Document Model boilerplate is the foundational template used for code generation when scaffolding your editors and models. It ensures compatibility with host applications like Connect and Switchboard for document model and editor integration. After installing `ph-cmd`, run `ph init` to initialize a project directory and structure; this command uses the boilerplate. The boilerplate includes scripts for generating code, linting, formatting, building, and 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 in the [Component Library documentation](/academy/Reference/EditorsUI/DocumentEngineering). ## 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) and **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, and can be customized to offer specific functionality, categorization, or tailored interfaces for your documents. ## Code generators Powerhouse provides several code generation tools: ### Document model scaffolding Generates the basic structure for new document models with `ph init`, based on the boilerplate. ### Editor generator Creates template code for document model editors: `ph generate editor --name --document-type `. ### Subgraph generator Creates GraphQL subgraph templates for data access automatically on `ph reactor`. ### Processor generator Generates processor templates for event handling automatically on `ph reactor`. ### Analytics processor generator Creates specialized processors for analytics tracking. ## Analytics engine The Analytics Engine tracks and analyzes 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 with: ```bash ph generate processor --type analytics ``` --- ## Explore the demo package > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/ExploreDemoPackage Before recreating the package yourself, install the finished version to see what you'll build. The demo is a pre-built package containing a document model, an editor, and a Drive-app — the same "To-do List Demo Package" you'll recreate across this tutorial. ## Step 1: Confirm the CLI is installed You set up `ph-cmd` in [Prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites). Verify it: ```bash ph --version ``` If the command isn't found, complete [Prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites) first. ## Step 2: Initialize a new project Now use the `ph init` command to initialize a new project and install a Powerhouse package inside the project. You'll be asked to name your project. Afterwards, move inside your project with `cd project-name` ## Step 3: Install the to-do list demo package Now, use the `ph install` command to install the demo package inside the project. ```bash # Install the package ph install @powerhousedao/todo-demo ``` This command downloads and sets up the `@powerhousedao/todo-demo`, making its features available in your Powerhouse project.

Expected CLI result

```bash installing dependencies 📦 ... WARN 19 deprecated subdependencies found: @esbuild-kit/core-utils@3.3.2, @esbuild-kit/esm-loader@2.6.5, @npmcli/move-file@1.1.2, @paulmillr/qr@0.2.1, are-we-there-yet@3.0.1, gauge@4.0.4, glob@7.2.3, graphql-language-service-interface@2.10.2, graphql-language-service-parser@1.10.4, graphql-language-service-types@1.8.7, graphql-language-service-utils@2.7.1, inflight@1.0.6, multibase@4.0.6, multicodec@3.2.1, node-domexception@1.0.0, npmlog@6.0.2, rimraf@2.7.1, rimraf@3.0.2, sudo-prompt@8.2.5 Packages: +1 + Progress: resolved 2277, reused 2106, downloaded 1, added 1, done WARN Issues with peer dependencies found . ├─┬ @powerhousedao/reactor-browser 3.1.0 │ └─┬ @powerhousedao/analytics-engine-browser 0.6.0 │ └── ✕ unmet peer @powerhousedao/analytics-engine-knex@0.5.1: found 0.6.0 ├─┬ @types/react-dom 19.1.6 │ └── ✕ unmet peer @types/react@^19.0.0: found 18.3.23 └─┬ react-native 0.80.0 ├── ✕ unmet peer @types/react@^19.1.0: found 18.3.23 ├── ✕ unmet peer react@^19.1.0: found 18.3.1 └─┬ @react-native/virtualized-lists 0.80.0 └── ✕ unmet peer @types/react@^19.0.0: found 18.3.23 dependencies: + @powerhousedao/todo-demo-package 1.1.1 ╭ Warning ───────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ Ignored build scripts: @acaldas/graphql-codegen-typescript-validation-schema, @apollo/protobufjs, │ │ @datadog/pprof, @ipshipyard/node-datachannel, @parcel/watcher, @prisma/client, @prisma/engines, │ │ @tailwindcss/oxide, bufferutil, esbuild, keccak, prisma, sqlite3, utf-8-validate. │ │ Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts. │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯ Done in 6s using pnpm v10.9.0 Dependency installed successfully 🎉 ⚙️ Updating powerhouse config file... Config file updated successfully 🎉 ```

You have now successfully installed `ph-cmd`, initalized a product project and added your first package! ## Step 4: Run the Connect host application To run the package locally in Connect, run: ```bash ph connect ``` Click the returned localhost URL and you should see Connect appear in your browser. **INFO:** **Connect** is the Powerhouse host application—a container that runs all your apps, editors, and drives. Think of it as the browser for your Powerhouse ecosystem. **Vetra Studio** (which you'll use for building) runs inside Connect, just like how a web app runs inside a browser.

Connect Home — The Powerhouse Connect interface.

When you click the settings wheel in the bottom right corner, you'll get access to the **Package Manager**. Here, you'll see that you've installed the `@powerhousedao/todo-demo`, which contains not only a **Document Model** and its accompanying editor but also a **Drive-app** specific to the todo-list document model.

## Step 5: Create a todo list document **TIP:** A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized Drive-apps for your documents. Think of a Drive-app as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases. To learn more, visit [Building a Drive-app](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) **TIP:** An **editor** is a UI component for viewing and modifying a single document. A **Drive-app** is a custom interface for managing multiple documents within a drive—providing aggregated views, progress tracking, and specialized workflows across your document collection. ### 5.1 Create a local todo-list app drive First, let's create a dedicated drive for your to-do lists: - Click the new drive icon in the interface - In the **Drive-app** field, select 'todo-list Drive-app' - This creates a specialized drive that's optimized for to-do list documents ### 5.2 Create a todo-list document Now move into the drive you've just created: - Click the button at the bottom of the page to create a new to-do list document - This opens the to-do list editor where you can start managing your tasks ### 5.3 Add a few todos and inspect the document history - Add a few to-dos that are on your mind - You'll see a statistics widget that counts the open to-dos - After closing the document, look at the todo-list Drive-app interface—you'll see that it tracks your tasks and displays a progress bar This is an example of the **usefulness and impact of Drive-apps**. They offer a customized interface that works well with the different documents inside your drive. Read more about Drive-apps in the Mastery Track: [Drive-apps](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer). A key feature of Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when.

Operations History Button — You can find the button to visit the operations history in the document model toolbar

Learn more about the [Operations History](/academy/Build/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free. ## Step 6: Enable operation signing and verification through Renown Renown is Powerhouse's **decentralized identity and reputation system** designed to address the challenge of trust within open organizations, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities. **TIP:** When signing in with Renown, use an Ethereum or blockchain address that can function as your 'identity', as this address will accrue more experience and history over time. ### 6.1 Click the renown icon and connect your Ethereum identity "**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.

Renown Login — The Renown login screen, prompting for a signature from a wallet.

### 6.2 Authorize Connect to sign document edits on your behalf This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.

Connect Address for DID — A newly generated DID and address shown within the Connect interface.

Renown Login Complete — Confirmation of a successful login with Renown.

### 6.3 Verify the signatures of new operations in the todo list With this system, every operation made to a document is cryptographically signed by the contributor's Renown identity. Each change is verifiable, traceable, and attributable to a specific pseudonymous user, giving every document a complete audit trail. Now, return to your to-do list and make some additional changes. You'll notice that these operations are now signed with your Renown identity, making every action traceable and verifiable in the operations history.

Operation History Signature — Your DID is now signing the operations that are being added to the history.

## Step 7: Export a document Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network. ### Up next Now that you have explored a Powerhouse package and discovered its basic functionalities, it is time to start building your own. Our next tutorial focuses on creating a simple to-do list document and will introduce you to the world of **Document Models**—the foundation of **Specification Driven Design & Development**, where structured specs become the shared language between you and AI agents. --- ## Create a new to-do list document > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject **TIP:** 📦 **Reference Code**: [step-1-initialize-with-ph-init](https://github.com/powerhouse-inc/todo-tutorial/tree/step-1-initialize-with-ph-init) This tutorial step has a corresponding branch in the repository. You can: - View the complete code for this step - Clone and checkout the branch to see the result - Compare your implementation using `git diff` ::: ## Overview This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **todo-list**. A Powerhouse project primarily consists of a document model and its editor. As your projects use-case expands you can add data-integrations or a specific Drive-app as seen in the demo package. For today's purpose, you'll be using **Vetra Studio**, the builder platform through which developers can access and manage specifications of your project. Vetra Studio runs inside **Connect**, the Powerhouse host application that serves as a container for all Powerhouse apps and drives. ## Prerequisites - Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd` - Node.js 24 and a package manager (pnpm or npm) installed - Visual Studio Code (or your preferred IDE) - Terminal/Command Prompt access If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites)

📖 How to use this tutorial

This tutorial is designed for you to **build your own project from scratch** while having access to reference code at each step. ### Setup: Create your project and connect to tutorial repo 1. **Create your project** following the tutorial: ```bash mkdir ph-projects cd ph-projects ph init # When prompted, enter project name: todo-tutorial cd todo-tutorial ``` 2. **Add the tutorial repository as a remote** to access reference branches: ```bash git remote add tutorial https://github.com/powerhouse-inc/todo-tutorial.git git fetch tutorial --prune ``` 3. **Create your own branch** to keep your work organized: ```bash git checkout -b my-todo-project ``` Now you have access to all tutorial step branches while working on your own code! ### Compare your work with reference steps At any point, compare what you've built with a tutorial step: ```bash # Compare your current work with step-1 git diff tutorial/step-1-initialize-with-ph-init # See what changed between tutorial steps git diff tutorial/step-1-initialize-with-ph-init..tutorial/step-2-generate-todo-list-document-model # Compare specific files git diff tutorial/step-1-initialize-with-ph-init -- package.json ``` ### Visual diff with GitHub Desktop For a more visual comparison, use GitHub Desktop: 1. **First, make your initial commit** (GitHub Desktop won't show your branch until you have at least one commit): ```bash git add . git commit -m "Initial project setup" ``` 2. **Open GitHub Desktop** and open your repository 3. **Compare branches visually**: - Click on **Branch** menu in the top menu bar - Select **"Compare to Branch..."** - Choose the tutorial branch you want to compare with (e.g., `tutorial/step-1-initialize-with-ph-init`) - GitHub Desktop will show you all file differences in a visual interface 4. **Review the differences**: - Click on any file to see side-by-side or unified diff view - See exactly what's different between your code and the reference **Tip**: You can also use VS Code's Git Graph extension or the command palette → "Git: Compare with Branch" ### If you get stuck Reset your code to match a tutorial step: ```bash # Reset to step-2 (WARNING: loses your changes) git reset --hard tutorial/step-2-generate-todo-list-document-model ```

## Quick start Create a new Powerhouse project with a single command: ```bash ph init ``` ## Before you begin 1. Open your terminal (either your system terminal or IDE's integrated terminal) 2. Optionally, create a folder first to keep your Powerhouse projects: ```bash mkdir ph-projects cd ph-projects ``` 3. Ensure you're in the correct directory before running the `ph init` command. In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter. ````bash you@yourmachine:~/ph-projects % ph init ? What is the project name? ‣ todo-tutorial ``` ```` Once the project is created, you will see output like: ```bash 🚀 Initializing a new project... ▶️ Creating directory for project "todo-tutorial"... ✅ Project directory created ▶️ Initializing git repository... ✅ Git repository initialized ▶️ Creating project boilerplate files... ✅ Project boilerplate files created ▶️ Installing project dependencies with npm... ✅ Project dependencies installed ▶️ Formatting boilerplate project files... ✅ Boilerplate files formatted 🎉 Successfully created project "todo-tutorial" 🎉 ``` Navigate to the newly created project directory: `bash cd todo-tutorial ` ## Develop a single document model in Vetra Studio **Vetra Studio** is the builder's orchestration hub for assembling all specifications needed for your package. It provides a **Vetra Studio Drive** to access, manage, and share document model specifications, editors, and data integrations—all through a visual interface. For deeper coverage, see the [Vetra Studio documentation](/academy/GetStarted/VetraStudio). Once in the project directory, run the `ph vetra --watch` command to start a Vetra Studio Drive where you'll be defining your specifications. This is the preferred way to launch your development environment. **INFO:** You'll notice "reactor-api" in the terminal output. A **Reactor** is the Powerhouse back-end service that hosts your drives, handles document synchronization, and provides the GraphQL API. When you run `ph vetra --watch`, a local Reactor starts automatically to power your development environment. ```bash ph vetra --watch ``` The host application for Vetra Studio will start and you will see the following output: ```bash ℹ [reactor-api] [package-manager] Loading packages: @powerhousedao/vetra 14:44:19 ℹ [reactor-api] [server] WebSocket server available at /graphql/subscriptions 14:44:22 ℹ [reactor-api] [graphql-manager] Registered /graphql/system subgraph. 14:44:22 ℹ [reactor-api] [graphql-manager] Registered /graphql/analytics subgraph. 14:44:22 ℹ [reactor-api] [graphql-manager] Registered /d/:drive subgraph. 14:44:22 ℹ [reactor-api] [graphql-manager] Registered /graphql supergraph 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/document-editor subgraph. 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/vetra-package subgraph. 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/subgraph-module subgraph. 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/processor-module subgraph. 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/app-module subgraph. 14:44:23 ℹ [reactor-api] [graphql-manager] Registered /graphql/vetra-read-model subgraph. 14:44:23 ℹ [reactor-api] [server] MCP server available at http://localhost:4001/mcp 14:44:24 Switchboard initialized 14:44:24 ➜ Drive URL: http://localhost:4001/d/vetra-bac239dd 14:44:24 2:44:24 PM [vite] (client) Re-optimizing dependencies because vite config has changed 14:44:24 Port 3000 is in use, trying another one... 14:44:24 ➜ Local: http://localhost:3000/ 14:44:24 ➜ Network: use --host to expose 14:44:24 ➜ press h + enter to show help ```` A new browser window will open when visiting localhost and you will see the Vetra Studio Drive

Create a new document model by clicking the Document Models 'Add new specification' button. Name your document TodoList (PascalCase, no spaces or hyphens). If you've followed the steps correctly, you'll have an empty TodoList document where you can define the 'Document Specifications' in the next step.

Alternatively: Develop a single document model in Connect (legacy)

**NOTE:** The `ph connect` command is a legacy feature. We recommend using `ph vetra --watch` for all new development, as it provides better tooling and automatic code generation. Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document. 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 ➜ Local: http://localhost:3000/ ➜ Network: http://192.168.5.110: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. You will see your local drive and a button to create a new drive. **TIP:** If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage. Clear the storage of your localhost application as it might has an old session cached. 4. Move into your local drive. Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. Name your document `TodoList` (PascalCase, no spaces or hyphens). If you've followed the steps correctly, you'll have an empty `TodoList` document where you can define the **'Document Specifications'**.

## Verify your setup At this point, your project structure should match the `step-1-initialize-with-ph-init` branch. You should have: - Empty `document-models/`, `editors/`, `processors/`, and `subgraphs/` directories - Configuration files: `powerhouse.config.json`, `powerhouse.manifest.json` - Package management files: `package.json`, `pnpm-lock.yaml` - Build configuration: `tsconfig.json`, `vite.config.ts`, `vitest.config.ts` ### Compare with reference implementation Verify your initial setup matches the tutorial: ```bash # Compare your project structure with step-1 git diff tutorial/step-1-initialize-with-ph-init # List files in the tutorial's step-1 git ls-tree -r --name-only tutorial/step-1-initialize-with-ph-init # View a specific config file from step-1 git show tutorial/step-1-initialize-with-ph-init:package.json ```` ## ph install / ph add ```bash ph install [dependencies...] [--registry ] [--local] [--allow-build ] ``` Aliases: `ph add`, `ph i` The install command adds Powerhouse dependencies to your project. By default it only registers the package in `powerhouse.config.json` with provider `"registry"` — Connect will load it from the registry CDN at runtime. With `--local`, the package is also installed into `node_modules` and marked as provider `"local"` — it will be bundled into `ph connect build` so the preview works without the registry being reachable. Resolution order for the registry URL: `--registry` flag > `PH_REGISTRY_URL` env > `powerhouse.config.json` > default ## Up next In the next tutorials, you will learn how to specify, add code and build an editor for your document model and export it to be used in your Powerhouse package. --- ## Write the document specification > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/DefineToDoListDocumentModel **TIP:** 📦 **Reference Code**: [step-2-generate-todo-list-document-model](https://github.com/powerhouse-inc/todo-tutorial/tree/step-2-generate-todo-list-document-model) This tutorial step has a corresponding branch. After completing this step, your project will have a generated document model with: - Document model specification files (`todo-list.json`, `schema.graphql`) - Auto-generated TypeScript types and action creators - Reducer scaffolding ready for implementation :::

📖 How to use this tutorial

**Prerequisites**: Complete step 1 and set up the tutorial remote (see previous step). ### Compare your generated code After running `ph generate document-model --document TodoList.phdm.zip`, compare with the reference: ```bash # Compare all generated files with step-2 git diff tutorial/step-2-generate-todo-list-document-model # Compare specific directory git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/ ``` ### See what was generated View the complete step-2 reference code: ```bash # List files in the tutorial's step-2 git ls-tree -r --name-only tutorial/step-2-generate-todo-list-document-model document-models/ # View a specific file from step-2 git show tutorial/step-2-generate-todo-list-document-model:document-models/todo-list/schema.graphql ``` ### Visual comparison with GitHub Desktop After making a commit, use GitHub Desktop for visual diff: 1. **Branch** menu → **"Compare to Branch..."** 2. Select `tutorial/step-2-generate-todo-list-document-model` 3. Review all file differences in the visual interface See step 1 for detailed GitHub Desktop instructions.

In this tutorial, you will learn how to define the specifications for a **todo-list** document model within Vetra Studio using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project. If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification. ## TodoList document specification We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model. Below, you can see the SDL for the `TodoList` document model. **INFO:** This schema defines the **data structure** of the document model and the types involved in its operations, which are detailed further as input types. Documents in Powerhouse use **event sourcing**: every state transition is an operation. GraphQL input types describe those operations and the parameters each one needs, which makes state transitions explicit, validated, and reproducible. This is the essence of **Specification Driven Design & Development**: your schema serves as a machine-readable specification that both humans and AI agents can understand and execute—turning your intent into precise, maintainable functionality.

State schema of our simplified TodoList

```graphql # The state of our TodoList - contains an array of todo items type TodoListState { items: [TodoItem!]! } # A single to-do item with its properties type TodoItem { id: OID! # Unique identifier for each to-do item text: String! # The text description of the to-do item checked: Boolean! # Status of the to-do item (checked/unchecked) } ```

Operations schema of our simplified TodoList

```graphql # Defines a GraphQL input type for adding a new to-do item # Only text is required - ID is generated automatically, checked defaults to false input AddTodoItemInput { text: String! # The text for the new todo item } # Defines a GraphQL input type for updating a to-do item # ID is required to identify which item to update # text and checked are optional - only provided fields will be updated input UpdateTodoItemInput { id: OID! # Required: which item to update text: String # Optional: new text value checked: Boolean # Optional: new checked state } # Defines a GraphQL input type for deleting a to-do item input DeleteTodoItemInput { id: OID! # The ID of the item to delete } ```

## Define the document model specification ### The steps below show you how to do this: 1. In Vetra Studio, click on **'document model'** to open the document model specification editor. 2. Name your document model `TodoList` (PascalCase, no spaces or hyphens) in the Connect application. **Pay close attention to capitalization, as it influences code generation.** 3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields. In the **Document Type** field, type `powerhouse/todo-list` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification. ![TodoList Document Model Form Metadata](../docs/docs/images/DocumentModelHeader.png) 4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language. 5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `todos`. Press enter. 6. Now there is a new field, called `Add operation`. Here you will have to add each input operation to the module, one by one. 7. Inside the `Add operation` field, type `ADD_TODO_ITEM` and press enter. A small editor will appear underneath it, 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 AddTodoItemInput { text: String! } ``` 8. Repeat the process from step 7 for the other input operations: `UPDATE_TODO_ITEM` and `DELETE_TODO_ITEM`. You may have noticed that you only need to add the name of the operation (e.g., `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`) without the `Input` suffix. It will then be generated once you press enter. 9. In the meantime Vetra has been keeping an eye on your inputs and started code generation in your directory. In your terminal you will also find any validation errors that help you to identify missing specifications. Check below screenshot for the complete implementation: ![ToDoList Document Model](../docs/docs/images/DocumentModelOperations.png) ## Verify your document model generation If you have been watching the terminal in your IDE you will see that Vetra has been tracking your changes and scaffolding your directory. It will mention: ``` ℹ [Vetra] Document model TodoList is valid, proceeding with code generation ``` Your project should have the following structure in `document-models/todo-list/`: ``` document-models/todo-list/ ├── index.ts ├── todo-list.json # Document model specification ├── v1/ │ ├── index.ts │ ├── actions.ts │ ├── hooks.ts │ ├── module.ts │ ├── schema.graphql # GraphQL schema │ ├── utils.ts │ ├── gen/ # Auto-generated code (don't edit) │ │ ├── schema/ │ │ │ └── index.ts │ │ ├── actions.ts │ │ ├── controller.ts │ │ ├── creators.ts │ │ ├── document-model.ts │ │ ├── document-schema.ts │ │ ├── document-type.ts │ │ ├── index.ts │ │ ├── ph-factories.ts │ │ ├── reducer.ts │ │ ├── types.ts │ │ ├── utils.ts │ │ └── todos/ # Per-module generated files │ │ ├── actions.ts │ │ ├── creators.ts │ │ ├── error.ts │ │ └── operations.ts │ ├── src/ # Your custom implementation │ │ ├── index.ts │ │ ├── utils.ts │ │ └── reducers/ │ │ └── todos.ts │ └── tests/ │ ├── document-model.test.ts │ └── todos.test.ts └── upgrades/ ├── index.ts ├── upgrade-manifest.ts ├── v1.ts └── versions.ts ``` **TIP:** To make sure everything works as expected: ```bash # Check types compile correctly pnpm tsc # Check linting passes pnpm lint # Compare your generated files with step-2 git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/ ``` ### Up next: reducers Up next, you'll learn how to implement the runtime logic and components that will use the `TodoList` document model specification you've just created and exported. --- ## Implement the document model reducers > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/ImplementOperationReducers **TIP:** 📦 **Reference Code**: [step-3-implement-reducer-operation-handlers](https://github.com/powerhouse-inc/todo-tutorial/tree/step-3-implement-reducer-operation-handlers) This step focuses on implementing the reducer logic for add, update, and delete operations.

📖 How to use this tutorial

### Compare your reducer implementation After implementing your reducers: ```bash # Compare your reducers with the reference git diff tutorial/step-3-implement-reducer-operation-handlers -- document-models/todo-list/src/reducers/ # View the reference reducer implementation git show tutorial/step-3-implement-reducer-operation-handlers:document-models/todo-list/src/reducers/todos.ts ``` ### Visual comparison with GitHub Desktop After committing your work, compare visually: 1. **Branch** menu → **"Compare to Branch..."** 2. Select `tutorial/step-3-implement-reducer-operation-handlers` 3. Review differences in the visual interface ### If you get stuck View or reset to a specific step: ```bash # View the reducer code git show tutorial/step-3-implement-reducer-operation-handlers:document-models/todo-list/src/reducers/todos.ts # Reset to this step (WARNING: loses your changes) git reset --hard tutorial/step-3-implement-reducer-operation-handlers ```

Now implement the operation reducers for the **todo-list** document model. In the previous step, Vetra imported the document specification and scaffolded the code and directory through live code generation. **INFO:** Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema. **Connection to schema definition language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema? The reducers provide the actual implementation of what happens when those operations are performed. ## Explore the generated reducer file Navigate to `/document-models/todo-list/src/reducers/todos.ts` and open it. You should see scaffolding code that needs to be filled for the three operations you specified: ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // TODO: Implement "addTodoItemOperation" reducer throw new Error('Reducer "addTodoItemOperation" not yet implemented'); }, updateTodoItemOperation(state, action) { // TODO: Implement "updateTodoItemOperation" reducer throw new Error('Reducer "updateTodoItemOperation" not yet implemented'); }, deleteTodoItemOperation(state, action) { // TODO: Implement "deleteTodoItemOperation" reducer throw new Error('Reducer "deleteTodoItemOperation" not yet implemented'); }, }; ``` ## Implement the operation reducers Let's implement each reducer one by one. ### Step 1: Add the import First, add the `generateId` import at the top of the file: ```typescript // added-line ``` ### Step 2: Implement addTodoItemOperation Replace the boilerplate `addTodoItemOperation` with the actual implementation: ```typescript export const todoListTodosOperations: TodoListTodosOperations = { // removed-start addTodoItemOperation(state, action) { // TODO: Implement "addTodoItemOperation" reducer throw new Error('Reducer "addTodoItemOperation" not yet implemented'); }, // removed-end // added-start addTodoItemOperation(state, action) { const id = generateId(); state.items.push({ ...action.input, id, checked: false }); }, // added-end updateTodoItemOperation(state, action) { // ... }, deleteTodoItemOperation(state, action) { // ... }, }; ``` **What's happening here:** - We generate a unique ID using `generateId()` from `document-model/core` - We push a new item to the `items` array with the input text, new ID, and `checked: false` - Under the hood, Powerhouse uses Immer.js, so this "mutation" is actually immutable ### Step 3: Implement updateTodoItemOperation Replace the boilerplate `updateTodoItemOperation`: ```typescript // removed-start updateTodoItemOperation(state, action) { // TODO: Implement "updateTodoItemOperation" reducer throw new Error('Reducer "updateTodoItemOperation" not yet implemented'); }, // removed-end // added-start updateTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (!item) return; item.text = action.input.text ?? item.text; item.checked = action.input.checked ?? item.checked; }, // added-end ``` **What's happening here:** - We find the item by its ID - We return early if the item is not found - We use nullish coalescing (`??`) to only update fields that are provided ### Step 4: Implement deleteTodoItemOperation Replace the boilerplate `deleteTodoItemOperation`: ```typescript // removed-start deleteTodoItemOperation(state, action) { // TODO: Implement "deleteTodoItemOperation" reducer throw new Error('Reducer "deleteTodoItemOperation" not yet implemented'); }, // removed-end // added-start deleteTodoItemOperation(state, action) { state.items = state.items.filter((item) => item.id !== action.input.id); }, // added-end ``` **What's happening here:** - We filter out the item with the matching ID - This creates a new array without the deleted item ## Complete reducer file Here's the complete implementation:

Complete todos.ts

```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { const id = generateId(); state.items.push({ ...action.input, id, checked: false }); }, updateTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (!item) return; item.text = action.input.text ?? item.text; item.checked = action.input.checked ?? item.checked; }, deleteTodoItemOperation(state, action) { state.items = state.items.filter((item) => item.id !== action.input.id); }, }; ```

**TIP:** To make sure everything works as expected: ```bash # Check types compile correctly pnpm tsc # Check linting passes pnpm lint # Compare with reference implementation git diff tutorial/step-3-implement-reducer-operation-handlers -- document-models/todo-list/src/reducers/ ``` ## Up next: Writing tests In the next chapter, you'll write tests to verify your reducer implementations work correctly. --- ## Write document model tests > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/WriteDocumentModelTests **TIP:** 📦 **Reference Code**: [step-4-implement-tests-for-todos-operations](https://github.com/powerhouse-inc/todo-tutorial/tree/step-4-implement-tests-for-todos-operations) This step covers writing tests for the reducers you implemented in the previous step.

📖 How to use this tutorial

### Compare your tests After writing tests: ```bash # Compare your tests with the reference git diff tutorial/step-4-implement-tests-for-todos-operations -- document-models/todo-list/src/tests/ # View the reference test implementation git show tutorial/step-4-implement-tests-for-todos-operations:document-models/todo-list/src/tests/todos.test.ts ``` ### Visual comparison with GitHub Desktop After committing your work, compare visually: 1. **Branch** menu → **"Compare to Branch..."** 2. Select `tutorial/step-4-implement-tests-for-todos-operations` 3. Review differences in the visual interface

To verify the operation reducers work as expected, write tests for them. Generating your document model code created boilerplate tests; now extend them to check the reducer logic. ## Understanding the generated test file Navigate to `/document-models/todo-list/src/tests/todos.test.ts`. You will see that we have some basic "sanity check" style tests already. These make sure that your operations at least result in a valid document model state. ```typescript reducer, utils, isTodoListDocument, addTodoItem, AddTodoItemInputSchema, updateTodoItem, UpdateTodoItemInputSchema, deleteTodoItem, DeleteTodoItemInputSchema, } from "todo-tutorial/document-models/todo-list"; describe("Todos Operations", () => { it("should handle addTodoItem operation", () => { // The `createDocument` utility function from your document model creates // a new empty document, i.e. one with your default initial state const document = utils.createDocument(); // The generateMock function takes one of your generated input schemas // and creates an object populated with random values for each field const input = generateMock(AddTodoItemInputSchema()); // We call your document model's reducer with the new document we just created // and the action we want to test, `addTodoItem` in this case. // The reducer returns a new object, which is the document with the action applied. // If successful, there will be an operation which corresponds to this action // in the updated document's operations list. const updatedDocument = reducer(document, addTodoItem(input)); // When you generate a document model, we give you validation utilities like // `isTodoListDocument` which confirms the document is of the correct form // in a way that TypeScript recognizes expect(isTodoListDocument(updatedDocument)).toBe(true); // At the start a document will have 0 operations, so after applying this action // there should now be one operation expect(updatedDocument.operations.global).toHaveLength(1); // The operation added to the list should correspond to the correct action type expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_TODO_ITEM", ); }); it("should handle updateTodoItem operation", () => { // ... boilerplate test }); it("should handle deleteTodoItem operation", () => { // ... boilerplate test }); }); ``` ## Enhance the tests The boilerplate tests check that operations are applied, but they don't verify the **actual results**. Extend them to assert on the resulting state. ### Test 1: Update the addTodoItem test The add test is already fairly complete. We just need to add type annotations: ```typescript it("should handle addTodoItem operation", () => { const document = utils.createDocument(); // added-line const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema()); const updatedDocument = reducer(document, addTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_TODO_ITEM", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); ``` ### Test 2: Replace the updateTodoItem test Delete the existing boilerplate and add two separate tests - one for updating text, one for updating the checked state: ```typescript // removed-start it("should handle updateTodoItem operation", () => { const document = utils.createDocument(); const input = generateMock(UpdateTodoItemInputSchema()); const updatedDocument = reducer(document, updateTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); // ... }); // removed-end ``` **Add the new test for updating text:** ```typescript it("should handle updateTodoItem operation to update text", () => { // We need there to already be a todo item in the document, // since we want to test updating an existing item const mockItem = generateMock(TodoItemSchema()); // We also need to generate a mock input for the update operation we are testing const input: UpdateTodoItemInput = generateMock(UpdateTodoItemInputSchema()); // Since the mocks are generated with random values, we need to set the `id` // on our mock input to match the `id` of the existing mock item input.id = mockItem.id; // We want to easily check if the item's text was updated to our new value, // so we assign a variable and use that for the mock input's text field const newText = "new text"; input.text = newText; // We are only testing updating the text here, so we want the checked field // on the input to be undefined, i.e. it should not change anything on the existing item input.checked = undefined; // We can pass a different initial state to the `createDocument` utility, // so in this case we pass in an `items` array with our existing item already in it const document = utils.createDocument({ global: { items: [mockItem], }, }); // Create an updated document by applying the reducer with the action and input const updatedDocument = reducer(document, updateTodoItem(input)); // Use our validator to check that the document conforms to the document model schema expect(isTodoListDocument(updatedDocument)).toBe(true); // There should now be one operation in the operations list expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "UPDATE_TODO_ITEM", ); // Find the updated item in the items list by its `id` const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); // The item's text should now be updated to be our new text expect(updatedItem?.text).toBe(newText); // The item's `checked` field should be unchanged expect(updatedItem?.checked).toBe(mockItem.checked); }); ``` **Add the new test for updating checked state:** ```typescript it("should handle updateTodoItem operation to update checked", () => { // Generate a mock existing item const mockItem = generateMock(TodoItemSchema()); // Generate a mock input const input: UpdateTodoItemInput = generateMock(UpdateTodoItemInputSchema()); // Set the mock input's `id` to the mock item's `id` input.id = mockItem.id; // We want the new `checked` field value to be the opposite of the // randomly generated value from the mock const newChecked = !mockItem.checked; input.checked = newChecked; // Leave the `text` field unchanged input.text = undefined; // Create a document with the existing item in it const document = utils.createDocument({ global: { items: [mockItem], }, }); // Apply the reducer with the action and the mock input const updatedDocument = reducer(document, updateTodoItem(input)); // Validate your document expect(isTodoListDocument(updatedDocument)).toBe(true); // Get the updated item by its `id` const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); // The item's `text` field should remain unchanged expect(updatedItem?.text).toBe(mockItem.text); // The item's `checked` field should be updated to our new checked value expect(updatedItem?.checked).toBe(newChecked); }); ``` ### Test 3: Update the deleteTodoItem test The boilerplate delete test passes even without an existing item to delete. Let's fix that: ```typescript it("should handle deleteTodoItem operation", () => { // removed-start const document = utils.createDocument(); const input = generateMock(DeleteTodoItemInputSchema()); // removed-end // added-start // Create an existing item to delete const mockItem = generateMock(TodoItemSchema()); const document = utils.createDocument({ global: { items: [mockItem], }, }); const input: DeleteTodoItemInput = generateMock(DeleteTodoItemInputSchema()); input.id = mockItem.id; // added-end const updatedDocument = reducer(document, deleteTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "DELETE_TODO_ITEM", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); // added-start // Verify the item was actually removed const updatedItems = updatedDocument.state.global.items; expect(updatedItems).toHaveLength(0); // added-end }); ``` ## Complete test file Here's the complete test file with all updates. Don't forget to add the missing imports:

Complete todos.test.ts

```typescript AddTodoItemInput, DeleteTodoItemInput, UpdateTodoItemInput, } from "todo-tutorial/document-models/todo-list"; reducer, utils, isTodoListDocument, addTodoItem, AddTodoItemInputSchema, updateTodoItem, UpdateTodoItemInputSchema, deleteTodoItem, DeleteTodoItemInputSchema, TodoItemSchema, } from "todo-tutorial/document-models/todo-list"; describe("Todos Operations", () => { it("should handle addTodoItem operation", () => { const document = utils.createDocument(); const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema()); const updatedDocument = reducer(document, addTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_TODO_ITEM", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); it("should handle updateTodoItem operation to update text", () => { const mockItem = generateMock(TodoItemSchema()); const input: UpdateTodoItemInput = generateMock( UpdateTodoItemInputSchema(), ); input.id = mockItem.id; const newText = "new text"; input.text = newText; input.checked = undefined; const document = utils.createDocument({ global: { items: [mockItem], }, }); const updatedDocument = reducer(document, updateTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "UPDATE_TODO_ITEM", ); const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); expect(updatedItem?.text).toBe(newText); expect(updatedItem?.checked).toBe(mockItem.checked); }); it("should handle updateTodoItem operation to update checked", () => { const mockItem = generateMock(TodoItemSchema()); const input: UpdateTodoItemInput = generateMock( UpdateTodoItemInputSchema(), ); input.id = mockItem.id; const newChecked = !mockItem.checked; input.checked = newChecked; input.text = undefined; const document = utils.createDocument({ global: { items: [mockItem], }, }); const updatedDocument = reducer(document, updateTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); expect(updatedItem?.text).toBe(mockItem.text); expect(updatedItem?.checked).toBe(newChecked); }); it("should handle deleteTodoItem operation", () => { const mockItem = generateMock(TodoItemSchema()); const document = utils.createDocument({ global: { items: [mockItem], }, }); const input: DeleteTodoItemInput = generateMock( DeleteTodoItemInputSchema(), ); input.id = mockItem.id; const updatedDocument = reducer(document, deleteTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "DELETE_TODO_ITEM", ); const updatedItems = updatedDocument.state.global.items; expect(updatedItems).toHaveLength(0); }); }); ```

**TIP:** To make sure everything works as expected: ```bash # Check types compile correctly pnpm tsc # Check linting passes pnpm lint # Run tests pnpm test # Compare with reference implementation git diff tutorial/step-4-implement-tests-for-todos-operations -- document-models/todo-list/src/tests/ ``` Expected test output: ```bash ✓ document-models/todo-list/src/tests/document-model.test.ts (3 tests) 1ms ✓ document-models/todo-list/src/tests/todos.test.ts (4 tests) 8ms Test Files 2 passed (2) Tests 7 passed (7) ``` ## Up next: Building the editor In the next chapter, you'll learn how to implement a user interface (editor) for your document model so you can interact with it visually. --- ## Build a to-do list editor > Source: https://academy.vetra.io/academy/Build/ManualTodoTutorial/BuildToDoListEditor **TIP:** 📦 **Reference Code**: - **Editor Scaffolding**: [step-5-generate-todo-list-document-editor](https://github.com/powerhouse-inc/todo-tutorial/tree/step-5-generate-todo-list-document-editor) - **Complete Editor UI**: [step-6-add-basic-todo-editor-ui-components](https://github.com/powerhouse-inc/todo-tutorial/tree/step-6-add-basic-todo-editor-ui-components) This tutorial covers two steps: 1. **Step 5**: Generating the editor template with Vetra Studio 2. **Step 6**: Building a complete, interactive UI with components for adding, editing, and deleting todos Compare implementations: `git diff step-5-generate-todo-list-document-editor step-6-add-basic-todo-editor-ui-components`

📖 How to use this tutorial

This tutorial shows building from **generated scaffolding** (step-5) to **complete UI** (step-6). ### Compare your generated editor After running `ph generate editor`: ```bash # Compare generated scaffolding with step-5 git diff tutorial/step-5-generate-todo-list-document-editor -- editors/ # View the generated editor template git show tutorial/step-5-generate-todo-list-document-editor:editors/todo-list-editor/editor.tsx ``` ### Compare your custom components After building your UI: ```bash # Compare your complete editor with step-6 git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/ # See what was added from scaffolding to complete UI git diff tutorial/step-5-generate-todo-list-document-editor..tutorial/step-6-add-basic-todo-editor-ui-components ``` ### Browse the complete implementation Explore the production-ready component structure: ```bash # List all components in step-6 git ls-tree -r --name-only tutorial/step-6-add-basic-todo-editor-ui-components editors/todo-list-editor/components/ # View a specific component git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/TodoList.tsx ``` ### Visual comparison with GitHub Desktop After committing your editor code: 1. **Branch** menu → **"Compare to Branch..."** 2. Select `tutorial/step-5-generate-todo-list-document-editor` or `tutorial/step-6-add-basic-todo-editor-ui-components` 3. See all your custom components vs. the reference implementation See step 1 for detailed GitHub Desktop instructions.

Now build the editor: the user interface for the **todo-list** document model. It runs inside Connect to create, update, and delete your todo-list items. ## Add a document editor specification in Vetra Studio. Go back to Vetra Studio and click the 'Add new specification' button in the User Experiences column under 'Editors'. This will create an editor template for your document model. Give the editor the name `todo-list-editor` and select the correct document model. In our case that's the `powerhouse/todo-list` ### Editor implementation options You have several options for styling your editor component: 1. **Default HTML Styling:** Standard HTML tags (`

`, `
`, ` ); } ``` What's happening here: - We use a form with `onSubmit` handler for better UX (Enter key support) - We extract the text value from the input field - We dispatch the `addTodoItem` action (generated from our SDL) - We reset the form after submission ### Step 4: Create the Todos list component Create `editors/todo-list-editor/components/Todos.tsx` to render the list of todos: ```tsx type Props = { todos: TodoItem[]; }; /** Shows a list of the todo items in the selected todo list */ export function Todos({ todos }: Props) { const hasTodos = todos.length > 0; if (!hasTodos) { return
Start adding things to your todo list
; } return (
{todos.map((todo) => (

))}
); } ``` What's happening here: - We accept `todos` as a prop (passed from `TodoList` parent) - We show a helpful message if the list is empty - We map over todos and render a `Todo` component for each item ### Step 5: Create the Todo item component Create `editors/todo-list-editor/components/Todo.tsx` for individual todo items with edit and delete functionality: ```tsx useState, type ChangeEventHandler, type FormEventHandler, type MouseEventHandler, } from "react"; deleteTodoItem, updateTodoItem, } from "todo-tutorial/document-models/todo-list"; type Props = { todo: TodoItem; }; /** Displays a single todo item in the selected todo list * * Allows checking/unchecking the todo item. * Allows editing the todo item text. * Allows deleting the todo item. */ export function Todo({ todo }: Props) { const [isEditing, setIsEditing] = useState(false); // Even though this component is for a single todo item and not the whole list, // we can use the exact same hook for dispatching updates to it. // The dispatch function works for any action supported by a TodoList document. const [todoList, dispatch] = useSelectedTodoListDocument(); if (!todoList) return null; const todoId = todo.id; const todoText = todo.text; const todoChecked = todo.checked; const onSubmitUpdateTodoText: FormEventHandler = (event) => { event.preventDefault(); const form = event.currentTarget; const textInput = form.elements.namedItem("todoText") as HTMLInputElement; const text = textInput.value; if (!text) return; // We can use the dispatch function for any of the actions // supported by a TodoList document dispatch(updateTodoItem({ id: todo.id, text })); setIsEditing(false); }; const onChangeTodoChecked: ChangeEventHandler = (event) => { dispatch( updateTodoItem({ id: todo.id, checked: event.target.checked, }), ); }; const onClickDeleteTodo: MouseEventHandler = () => { dispatch(deleteTodoItem({ id: todoId })); }; const onClickEditTodo: MouseEventHandler = () => { setIsEditing(true); }; const onClickCancelEditTodo: MouseEventHandler = () => { setIsEditing(false); }; if (isEditing) return (

); return (

{todoText}

); } ``` What's happening here: - We use local state (`isEditing`) to toggle between view and edit modes - We dispatch `updateTodoItem` for both checking and text editing - We dispatch `deleteTodoItem` to remove items - We use TypeScript event handlers for type safety ### Step 6: Create the TodoListName component Finally, create `editors/todo-list-editor/components/TodoListName.tsx` for displaying and editing the document name: ```tsx /** Allows editing the name of the selected todo list / export function TodoListName() { const [isEditing, setIsEditing] = useState(false); const [selectedTodoList, dispatch] = useSelectedTodoListDocument(); if (!selectedTodoList) return null; const documentName = selectedTodoList.name; const onSubmitEditName: FormEventHandler = (event) => { event.preventDefault(); const form = event.currentTarget; const nameInput = form.elements.namedItem("name") as HTMLInputElement; const name = nameInput.value; if (name) { dispatch(setName(name)); setIsEditing(false); } }; if (isEditing) { return (

); } return (
setIsEditing(true)} > {documentName}
); } ``` What's happening here: - We use the `setName` action from `document-model/document` (a built-in action) - We toggle between viewing and editing the name - Click the name to edit it ## Test your editor Now you can run the Vetra Studio Preview and see the todo-list editor in action: ```bash ph vetra --watch ``` In the bottom right corner you'll find a new Document Model that you can create: todo-list. Click on it to create a new todo-list document. INFO: The editor will update dynamically as you make changes, so you can experiment with styling and functionality while seeing your results appear in Vetra Studio in real-time. Try it out: 1. Add some todo items using the input form 2. Click on the document name to edit it 3. Check/uncheck items to mark them as complete 4. Click "Edit" on any item to modify its text 5. Click "Delete" to remove items Congratulations! 🎉 If you managed to follow this tutorial until this point, you have successfully implemented the todo-list document model with its reducer operations and editor. ## Compare with the reference implementation The tutorial repository's step-6 branch includes additional enhancements you can explore: Additional components in step-6: ``` editors/todo-list-editor/components/ ├── CloseButton.tsx # Editor close functionality ├── UndoRedoButtons.tsx # Operation history navigation └── Stats.tsx # Display metadata (creation/modification times) ``` View individual components from the reference: ```bash # See the enhanced TodoList component with all features git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/TodoList.tsx # Explore the UndoRedoButtons component git show tutorial/step-6-add-basic-todo-editor-ui-components:editors/todo-list-editor/components/UndoRedoButtons.tsx # Compare your implementation with the reference git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/todo-list-editor/ ``` TIP: To make sure everything works as expected: ```bash # Check types compile correctly pnpm tsc # Check linting passes pnpm lint # Run tests pnpm test # Test in Vetra Studio ph vetra --watch # Compare with reference implementation git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/todo-list-editor/ ``` In Connect, you should be able to: - Create a new todo-list document - Add, edit, and delete todo items - Check/uncheck items to mark them complete ## Up next You've built a working package by hand. From here you can go deeper or put it to use: - Go deeper — [Mastery Track: Document Model Creation](/academy/Build/DocumentModelCreation/WhatIsADocumentModel) — the theory behind the steps you just followed, plus an advanced version of the todo-list (computed stats), the Document Engineering UI components, and custom Drive Explorers. - Expose your data — [Work With Data](/academy/Build/WorkWithData/ConfiguringDrives) — configure drives, query documents over the GraphQL API, and build subgraphs and processors. - Ship it — [Launch](/academy/Build/Launch/PublishYourProject) — publish your package and deploy Connect and Switchboard. --- ## What is a document model? > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/WhatIsADocumentModel TIP: This chapter on Document Model Creation will help you with an in-depth practical understanding while building an advanced to-do list document model. If you have completed the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) (which includes creating a simple to-do list document model), you will revisit familiar topics and can enhance your existing document model with the advanced features covered in this Mastery Track, such as statistics tracking. Although not required, completing the Manual Todo tutorial first is recommended as it provides a hands-on foundation for the concepts explored in depth here. INFO: A Document Model is a programmable document structure that defines how data is stored, changed, and interpreted in a decentralized system. It acts like a living blueprint—capturing state, tracking changes, and enabling interaction through defined operations. For instance, an invoice document model might define fields like _issuer_, _lineItems_, and _status_, with operations such as _AddLineItem_ and _MarkAsPaid_. Document models are central to Specification Driven Design & Development—an approach where you communicate your solution and intent through structured specification documents. These specs are machine-readable and executable, serving as a shared language between developers, designers, and AI agents. This enables precise, iterative development and lays the groundwork for AI-assisted workflows. A Document Model can be understood as: - A structured software 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 blueprint that defines 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 use event sourcing, CQRS (Command Query Responsibility Segregation), and an append-only architecture for 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 # (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 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 - 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 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 document models give you Document models support: - Automation: Automate workflows using consistent, structured document logic. - Auditability: Maintain a full history of changes for compliance and transparency. - API Integration: Connect with Switchboard or external APIs for data exchange. - Data Analysis: Get real-time and historical insights through structured read models. - Version Control: Track and compare document states over time, similar to Git. - Collaboration: Let decentralized teams build, modify, and share documents asynchronously. - Extensibility: Add new fields, operations, and integrations over time without rewriting logic. - Schema Evolution: Evolve document models with [versioning](/academy/Build/DocumentModelCreation/DocumentModelVersioning): upgrade schemas while keeping backward compatibility with existing documents. ### Up next: How to build a document model Next, you'll build a To-do List document model, with the theory explained as you go. --- ## Specify the state schema > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/SpecifyTheStateSchema NOTE: This is the same step from the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/DefineToDoListDocumentModel), covered here in depth. The Mastery Track's only addition is the computed `stats` field — if you've done the basic build, skim to the stats parts. The state schema is the backbone of your document model. It defines the structure, data types, and relationships of the information your document will hold. In Powerhouse, you define this schema with the GraphQL Schema Definition Language (SDL). A well-defined state schema keeps data consistent and is what makes the document queryable. TIP: Your state schema is more than just a data structure—it's a specification that enables Specification Driven Design & Development. This schema becomes a machine-readable blueprint that AI agents can interpret and execute, enabling precise collaboration between you and AI throughout the development process. ## Core concepts ### Types At the heart of GraphQL SDL are types. Types define the shape of your data. You can define custom object types that represent the entities in your document. For example, in a `TodoList` document, you might have a `TodoListState` type and a `TodoItem` type. - `TodoListState`: This could be the root type representing the overall state of the to-do list. It might contain a list of `TodoItem` objects. - `TodoItem`: This type would represent an individual to-do item, with properties like an `id`, `text` (the task description), and `checked` (a boolean indicating if the task is completed). ### Fields Each type has fields, which represent the properties of that type. Each field has a name and a type. For instance, the `TodoItem` type would have an `id` field of type `OID!`, a `text` field of type `String!`, and a `checked` field of type `Boolean!`. ### Scalars GraphQL has a set of built-in scalar types: - `String`: A UTF‐8 character sequence. - `Int`: A signed 32‐bit integer. - `Float`: A signed double-precision floating-point value. - `Boolean`: `true` or `false`. - `ID`: A unique identifier, often used as a key for a field. It is serialized in the same way as a String; however, it is not intended to be human-readable. In addition to these standard types, the Powerhouse Document-Engineering system introduces custom scalars that are linked to reusable front-end components. These scalars are tailored for the web3 ecosystem and will be explored in the Component Library section of the documentation. TIP: Powerhouse provides the `OID` (Object ID) scalar type, which is a custom scalar specifically designed for unique identifiers in document models. It provides automatic ID generation capabilities when used with the `generateId()` function from the document-model core library. ### Lists and non-null You can modify types using lists and non-null indicators: - Lists: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[TodoItem!]!`. This means the field `items` in `TodoListState` will be a list of `TodoItem` objects. - Non-Null: To indicate that a field cannot be null, you add an exclamation mark `!` after the type name, e.g., `String!`. This means that the `text` field of a `TodoItem` must always have a value. The outer `!` in `[TodoItem!]!` means the list itself cannot be null (it must be at least an empty list), and the inner `!` on `TodoItem!` means that every item within that list must also be non-null. ## Example: TodoList state schema Revisit the `TodoList` example from the "Define the TodoList document specification" step of the Manual Todo tutorial. ### Basic schema (matching the Manual Todo tutorial) This is the same schema you built in the Manual Todo tutorial: ```graphql # The state of our TodoList type TodoListState { items: [TodoItem!]! } # A single to-do item type TodoItem { id: OID! text: String! checked: Boolean! } ``` ### Advanced schema (with statistics tracking) INFO: In this Mastery Track, we'll extend the basic schema with a `stats` field to demonstrate how you can add computed statistics to your document model. This is an optional enhancement that builds on the foundation from the Manual Todo tutorial. ```graphql # The state of our TodoList (advanced version with stats) type TodoListState { items: [TodoItem!]! stats: TodoListStats! } # A single to-do item type TodoItem { id: OID! text: String! checked: Boolean! } # The statistics on our to-do's (advanced feature) type TodoListStats { total: Int! checked: Int! unchecked: Int! } ``` ### Breakdown: - `TodoListState` type: - `items: [TodoItem!]!`: This field defines that our `TodoListState` contains a list called `items`. - `[TodoItem!]`: This signifies that `items` is a list of `TodoItem` objects. - `TodoItem!`: The `!` after `TodoItem` means that no item in the list can be null. Each entry must be a valid `TodoItem`. - The final `!` after `[TodoItem!]` means that the `items` list itself cannot be null. It can be an empty list `[]`, but it cannot be absent. - `stats: TodoListStats!` _(advanced)_: Holds aggregated statistics about the to-do items. - `TodoItem` type: - `id: OID!`: Each `TodoItem` has a unique identifier using Powerhouse's custom `OID` scalar. This is crucial for referencing specific items, for example, when updating or deleting them. - `text: String!`: The textual description of the to-do item. It cannot be null, ensuring every to-do has a description. - `checked: Boolean!`: Indicates whether the to-do item is completed. It defaults to a boolean value (true or false) and cannot be null. - `TodoListStats` type _(advanced)_: This type holds the summary statistics for the to-do list. - `total: Int!`: The total count of all to-do items. This field must be an integer and cannot be null. - `checked: Int!`: The number of to-do items that are marked as completed. This must be an integer and cannot be null. - `unchecked: Int!`: The number of to-do items that are still pending. This also must be an integer and cannot be null. ## Best practices for designing your state schema 1. Start Simple, Iterate: Begin with the core entities and properties. You can always expand and refine your schema as your understanding of the document's requirements grows. 2. Clarity and Explicitness: Name your types and fields clearly and descriptively. This makes the schema easier to understand and maintain. 3. Use Non-Null Wisely: Enforce data integrity by using non-null (`!`) for fields that must always have a value. However, be mindful not to over-constrain if a field can genuinely be optional. 4. Normalize vs. Denormalize: - Normalization: Similar to relational databases, you can normalize your data by having distinct types and linking them via IDs. This can reduce data redundancy. For example, if you had `User` and `TodoItem` and wanted to assign tasks, you might have an `assigneeId` field in `TodoItem` that links to a `User`'s `id`. - Denormalization: Sometimes, for performance or simplicity, you might embed data directly. For instance, if user information associated with a to-do item was very simple and only used in that context, you might embed user fields directly in `TodoItem`. - The choice depends on your specific use case, query patterns, and how data is updated. 5. Consider Future Needs: While you shouldn't over-engineer, think a little about potential future enhancements. For example, adding a `createdAt: String` or `dueDate: String` field to `TodoItem` might be useful later. 6. Root State Type: It's a common pattern to have a single root type for your document state (e.g., `TodoListState`). This provides a clear entry point for accessing all document data. The schema dictates how data is stored, and how it can be queried and mutated through operations. Operations are covered in the next section. ## Practical implementation: defining the state schema in Vetra Studio Now that you understand the concepts behind the state schema, let's put it into practice. This section will guide you through creating a document model specification for the TodoList example discussed above.

Tutorial: The state schema specification
### Prerequisites - You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) tutorial. - Vetra Studio is running. If not, navigate to your project directory in the terminal and run `ph vetra --watch`. ### Steps 1. Create a New Document Model: - With Vetra Studio open in your browser, you'll see the Vetra Studio Drive. - Click the Document Models 'Add new specification' button to create a new document model specification. 2. Define Document Metadata: - Name: Give your document model a descriptive name: `TodoList`. Pay close attention to capitalization, as it influences our code generation. - Document Type: In the 'Document Type' field, enter a unique identifier for this document type: `powerhouse/todo-list`. 3. Specify the State Schema: - In the code editor provided, you'll see a template for a GraphQL schema. - Replace the entire content of the editor with the advanced `TodoList` schema we've designed in this chapter: ```graphql # The state of our TodoList (advanced version with stats) type TodoListState { items: [TodoItem!]! stats: TodoListStats! } # A single to-do item type TodoItem { id: OID! text: String! checked: Boolean! } # The statistics on our to-do's (advanced feature) type TodoListStats { total: Int! checked: Int! unchecked: Int! } ``` 4. Sync Schema and View Initial State: - After pasting the schema, click the 'Sync with schema' button. - This action processes your schema and generates an initial JSON state for your document model based on the `TodoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly. For now, you can ignore the "Modules & Operations" section. We will define and implement the operations that modify this state in the upcoming sections of this Mastery Track. By completing these steps, you have successfully specified the data structure for the advanced TodoList document model. The next step is to define the operations that will allow users to interact with and change this state.

Alternatively: Define the state schema in Connect
### Prerequisites - You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) tutorial. - Connect is running. If not, navigate to your project directory in the terminal and run `ph connect`. ### Steps 1. Create a New Document Model: - With Connect open in your browser, navigate into your local drive. - At the bottom of the page in the 'New Document' section, click the `DocumentModel` button to create a new document model specification. 2. Define Document Metadata: - Name: Give your document model a descriptive name: `TodoList`. Pay close attention to capitalization, as it influences our code generation. - Document Type: In the 'Document Type' field, enter a unique identifier for this document type: `powerhouse/todo-list`. 3. Specify the State Schema: - In the code editor provided, you'll see a template for a GraphQL schema. - Replace the entire content of the editor with the advanced `TodoList` schema we've designed in this chapter: ```graphql # The state of our TodoList (advanced version with stats) type TodoListState { items: [TodoItem!]! stats: TodoListStats! } # A single to-do item type TodoItem { id: OID! text: String! checked: Boolean! } # The statistics on our to-do's (advanced feature) type TodoListStats { total: Int! checked: Int! unchecked: Int! } ``` 4. Sync Schema and View Initial State: - After pasting the schema, click the 'Sync with schema' button. - This action processes your schema and generates an initial JSON state for your document model based on the `TodoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly. For now, you can ignore the "Modules & Operations" section. We will define and implement the operations that modify this state in the upcoming sections of this Mastery Track. By completing these steps, you have successfully specified the data structure for the advanced TodoList document model. The next step is to define the operations that will allow users to interact with and change this state.
For a complete, working example, you can always have a look at the [Example TodoList Repository](/academy/Build/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track. --- ## Specify document operations > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/SpecifyDocumentOperations NOTE: You defined these operations in the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/DefineToDoListDocumentModel); this page explains them in depth and adds the operations behind the advanced `stats` feature. In the previous section, we defined the state schema for our document model. Now, we turn our attention to a critical aspect of document model creation: specifying document operations. These operations are the heart of your document's behavior, dictating how its state can be modified. ## What are document operations? In Powerhouse, document models adhere to event sourcing principles. This means that every change to a document's state is the result of a sequence of operations (or events). Instead of directly mutating the state, you define specific, named operations that describe the intended change. For example, in our `TodoList` document model, operations might include: - `ADD_TODO_ITEM`: To add a new task. - `UPDATE_TODO_ITEM`: To modify an existing task (e.g., change its text or mark it as completed). - `DELETE_TODO_ITEM`: To remove a task. Each operation acts as a command that, when applied, transitions the document from one state to the next. The complete history of these operations defines the document's journey to its current state. ## Connecting operations to the schema In the "Define TodoList Document Model" step of the Manual Todo tutorial, we used GraphQL `input` types to define the structure of the data required for each operation. Revisit that: ```graphql # Defines a GraphQL input type for adding a new to-do item input AddTodoItemInput { text: String! } # Defines a GraphQL input type for updating a to-do item input UpdateTodoItemInput { id: OID! text: String checked: Boolean } # Defines a GraphQL input type for deleting a to-do item input DeleteTodoItemInput { id: OID! } ``` These `input` types are not just abstract definitions; they are the specifications for our document operations. - `AddTodoItemInput` specifies that to execute an `ADD_TODO_ITEM` operation, we only need the `text` for the new item. The `id` is automatically generated by the reducer using Powerhouse's `generateId()` function. - `UpdateTodoItemInput` specifies that for an `UPDATE_TODO_ITEM` operation, we need the `id` of the item to update, and optionally new `text` or a `checked` status. - `DeleteTodoItemInput` specifies that a `DELETE_TODO_ITEM` operation requires the `id` of the item to be removed. TIP: Notice that `AddTodoItemInput` only requires `text` — not an `id`. This is because the ID is generated automatically in the reducer using `generateId()` from `document-model/core`. This ensures unique, consistent IDs and follows the pattern used in the [todo-demo repository](https://github.com/powerhouse-inc/todo-demo). Vetra Studio uses these GraphQL input types when you define operations within a module (e.g., the `todos` module with operations `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`). ## Designing effective document operations Careful design of your document operations is crucial for a robust and maintainable document model. Here are some key considerations: ### 1. Granularity Operations should be granular enough to represent distinct user intentions or logical changes. - Too coarse: An operation like `MODIFY_TODOLIST` that takes a whole new list of items would be too broad. It would be hard to track specific changes and could lead to complex reducer logic. - Too fine: While possible, having separate operations like `SET_TODO_ITEM_TEXT` and `SET_TODO_ITEM_CHECKED_STATUS` might be overly verbose if these are often updated together. `UPDATE_TODO_ITEM` with optional fields offers a good balance. - Just right: The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `TodoList` are good examples. They represent clear, atomic changes. ### 2. Naming conventions Clear and consistent naming makes your operations understandable. A common convention is `VERB_NOUN` or `VERB_NOUN_SUBJECT`. - Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`. - In our case: `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`. The name you provide in Vetra Studio (or Connect) (e.g., `ADD_TODO_ITEM`) directly corresponds to the operation type that will be recorded and that your reducers will handle. ### 3. Input types (payloads) The input type for an operation (its payload) should contain all the necessary information to perform that operation, and nothing more. - Completeness: If an operation needs a user ID to authorize a change, include it in the input. - Conciseness: Avoid including data that isn't directly used by the operation. - Clarity: Use descriptive field names within your input types. `action.input.text` is clearer than `action.input.t`. The GraphQL `input` types we defined earlier (`AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`) serve precisely this purpose. They ensure that whoever triggers an operation provides the correct data in the correct format. ### 4. Immutability and pure functions While not specified in the operation definition itself, remember that the _implementation_ of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions. ## Role in event sourcing and CQRS - Events: Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved. - Commands: Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated. ## From specification to implementation Specifying your document operations is the bridge between defining your data structure (the state schema) and implementing the logic that changes that data (the reducers). 1. You define the state schema (e.g., `TodoListState`, `TodoItem`). 2. You specify the operations that can alter this state, along with their required input data (e.g., `ADD_TODO_ITEM` with `AddTodoItemInput`). 3. Next, you will implement reducers for each specified operation. Each reducer will take the current state and an operation's input, and produce a new state. The generated code from `ph generate` (as seen in `03-ImplementOperationReducers.md`) will create a structure for your reducers based on the operations you specified in the Connect application (which, in turn, were based on your GraphQL input types). For example, the `TodoListTodosOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`. ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // Implementation uses action.input which matches AddTodoItemInput }, updateTodoItemOperation(state, action) { // Implementation uses action.input which matches UpdateTodoItemInput }, deleteTodoItemOperation(state, action) { // Implementation uses action.input which matches DeleteTodoItemInput }, }; ``` ## Practical implementation: Defining operations in Vetra Studio Now that you understand the theory, let's walk through the practical steps of defining these operations for our `TodoList` document model within Vetra Studio.

Tutorial: Specifying TodoList operations
Assuming you have already defined the state schema for the `TodoList` as covered in the previous section, follow these steps to add the operations: 1. Create a Module for Operations: Below the schema editor in Vetra Studio, find the input field labeled `Add module`. Modules help organize your operations. - Type `todos` into the field and press Enter. 2. Add the `ADD_TODO_ITEM` Operation: A new field, `Add operation`, will appear under your new module. - Type `ADD_TODO_ITEM` into this field and press Enter. - An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor: ```graphql # Defines a GraphQL input type for adding a new to-do item input AddTodoItemInput { text: String! } ``` :::info Notice we don't include `id` in the input — the reducer will generate it automatically using `generateId()` from `document-model/core`. ::: 3. Add the `UPDATE_TODO_ITEM` Operation: - In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter. - Paste the corresponding `input` definition into its editor: ```graphql # Defines a GraphQL input type for updating a to-do item input UpdateTodoItemInput { id: OID! text: String checked: Boolean } ``` 4. Add the `DELETE_TODO_ITEM` Operation: - Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter. - Paste its `input` definition: ```graphql # Defines a GraphQL input type for deleting a to-do item input DeleteTodoItemInput { id: OID! } ``` 5. Review: After adding all three operations, your document model specification in Vetra Studio is complete for now. You can see how each operation (`ADD_TODO_ITEM`, etc.) is now explicitly linked to an input type that defines its payload. Vetra Studio automatically tracks your document model specifications. In the next chapter, we will see how the generator is used to create code for our reducers.

Alternatively: Define operations in Connect
Assuming you have already defined the state schema for the `TodoList` as covered in the previous section, follow these steps to add the operations in Connect: 1. Create a Module for Operations: Below the schema editor in Connect, find the input field labeled `Add module`. Modules help organize your operations. - Type `todos` into the field and press Enter. 2. Add the `ADD_TODO_ITEM` Operation: A new field, `Add operation`, will appear under your new module. - Type `ADD_TODO_ITEM` into this field and press Enter. - An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor: ```graphql # Defines a GraphQL input type for adding a new to-do item input AddTodoItemInput { text: String! } ``` :::info Notice we don't include `id` in the input — the reducer will generate it automatically using `generateId()` from `document-model/core`. ::: 3. Add the `UPDATE_TODO_ITEM` Operation: - In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter. - Paste the corresponding `input` definition into its editor: ```graphql # Defines a GraphQL input type for updating a to-do item input UpdateTodoItemInput { id: OID! text: String checked: Boolean } ``` 4. Add the `DELETE_TODO_ITEM` Operation: - Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter. - Paste its `input` definition: ```graphql # Defines a GraphQL input type for deleting a to-do item input DeleteTodoItemInput { id: OID! } ``` 5. Review and Export: After adding all three operations, your document model specification in Connect is complete for now. You can see how each operation (`ADD_TODO_ITEM`, etc.) is now explicitly linked to an input type that defines its payload. The next step in a real project would be to click the `Export` button to save this specification file. In the next chapter, we will see how this exported file is used to generate code for our reducers.
## Conclusion Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the "what" (the operation and its input) before implementing the "how" (the reducer logic), you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model. In the next section, we will dive deeper into the implementation of the reducer functions for these specified operations. --- ## Use the Document Model Generator > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/UseTheDocumentModelGenerator When building document models with Vetra Studio, code generation happens automatically. As you add and update specification documents in your Vetra Studio Drive, Vetra monitors your changes and generates the necessary scaffolding in real-time. You'll receive updates directly in your terminal as Vetra processes your specifications. This article covers the manual code generation method using the `ph generate` command—an alternative approach that remains available when working with Connect and exported `.phd` specification files. While Vetra Studio is the recommended workflow for most developers, understanding the generator command provides useful context for how the scaffolding works under the hood. ## When to Use Manual Generation | Workflow | Code Generation | | ---------------- | -------------------------------------------------------------------------- | | Vetra Studio | Automatic—Vetra watches your specifications and generates code as you work | | Connect | Manual—Export a `.phd` file and run `ph generate` | If you're using Vetra Studio with `ph vetra --interactive`, you don't need to run any generation commands. Vetra handles everything for you, prompting for confirmation before processing changes. ## Prerequisites (Connect Workflow Only) If you're using the Connect workflow and need to manually generate code: 1. Powerhouse CLI (`ph-cmd`) Installed: The generator is part of the Powerhouse CLI. If you haven't installed it, see [Prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites). 2. Exported `.phd` File: You must have exported your document model specification from Connect as a `.phd` file (e.g., `TodoList.phd`). ## The Generate Command The core command to invoke the Document Model Generator is: ```bash ph generate document-model --document ``` Replace `` with the actual filename of your exported document model specification. For instance, if your exported file is named `TodoList.phd`, the command would be: ```bash ph generate document-model --document TodoList.phd ``` When executed, this command reads and parses the specification file and generates a set of files and directories within your Powerhouse project. ## Understanding the Generated Artifacts Whether generated automatically by Vetra or manually via `ph generate`, the output structure is the same. Understanding these artifacts helps you work effectively with your document model. The generator creates a new directory specific to your document model, located at: `document-models//` For example, using `TodoList.phd` would result in a directory structure under `document-models/todo-list/`. Inside this directory, you will find: ### 1. Specification Files - `todo-list.json`: A JSON representation of your document model specification containing the parsed schema, operation definitions, document type, and metadata. - `schema.graphql`: The raw GraphQL Schema Definition Language (SDL) for both the state and operations—a human-readable reference of your schema. ### 2. The `gen/` Directory (Auto-Generated Code) This directory houses all code automatically generated from your specification. Do not manually edit files within the `gen/` directory—they will be overwritten when the model is regenerated. Key files include: - `types.ts`: TypeScript interfaces derived from your GraphQL schema, including types for your document's state (e.g., `TodoListState`), complex types (e.g., `TodoItem`), and operation inputs (e.g., `AddTodoItemInput`). - `creators.ts`: Action creator functions for each operation. Instead of manually constructing action objects, you use functions like `addTodoItem({ text: 'Buy groceries' })`. - `utils.ts`: Utility functions including helpers to create initial document instances (e.g., `utils.createDocument()`). - `reducer.ts`: A TypeScript interface defining the expected shape of your reducer implementation. ### 3. The `src/` Directory (Your Implementation) This is where you write custom logic. Unlike `gen/`, these files are meant for manual editing. - `reducers/`: Contains skeleton reducer files (e.g., `todos.ts`) with function stubs for each operation that you implement with state transition logic. - `tests/`: Test files for your reducer logic. ## Versioned Document Models When your document model needs to evolve over time—adding new fields, operations, or changing behavior—you can use versioning. This allows multiple versions of the same document model to coexist, with automatic upgrade paths between them. ### Enabling Versioning Versioning is enabled by default. Simply run: ```bash ph generate document-model --document TodoList.phd ``` ### Versioned Folder Structure With versioning enabled, the generator creates a different structure: ``` document-models/ └── todo/ ├── v1/ # Version 1 code │ ├── gen/ # Auto-generated v1 types and utilities │ ├── src/reducers/ # V1 reducer implementations │ └── module.ts # Exports DocumentModelModule with version: 1 ├── v2/ # Version 2 code │ ├── gen/ │ ├── src/reducers/ │ └── module.ts # Exports DocumentModelModule with version: 2 ├── upgrades/ # Migration logic │ ├── versions.ts # Supported versions list │ ├── v2.ts # Upgrade reducer: v1 → v2 │ └── upgrade-manifest.ts └── document-models.ts # Exports all versions + manifests ``` ### Key Differences with Versioning | Standard Generation | Versioned Generation | | ------------------------------- | ----------------------------------------- | | Single `gen/` and `src/` folder | Separate `v1/`, `v2/` folders per version | | One reducer implementation | Version-specific reducers | | No upgrade logic | `upgrades/` folder with manifests | | Direct module export | Exports all versions + upgrade manifests | For comprehensive documentation on implementing versioning, including upgrade reducers and integration with Connect and Switchboard, see [Document Model Versioning](/academy/Build/DocumentModelCreation/DocumentModelVersioning). ## Benefits of Generated Scaffolding The generation process—whether automatic via Vetra or manual via `ph generate`—provides: 1. Reduced Boilerplate: Automates creation of type definitions, action creators, and utilities. 2. Type Safety: TypeScript types from your GraphQL schema catch errors at compile-time. 3. Consistency: Standardized project structure across document models. 4. Accelerated Development: Focus on business logic instead of foundational plumbing. 5. Ecosystem Alignment: Generated code integrates seamlessly with the Powerhouse ecosystem. 6. Single Source of Truth: Code stays synchronized with your specification. 7. Version Support: Optional versioning enables safe schema evolution over time. ## Practical Examples ### Using Vetra Studio (Recommended) When using Vetra Studio, code generation is automatic: 1. Start Vetra in Interactive Mode: ```bash ph vetra --interactive ``` 2. Create Your Document Model: Define your `TodoList` document model in the Vetra Studio Drive—either manually or with AI assistance through Claude and the Reactor MCP. 3. Watch the Terminal: As you add specifications, Vetra automatically detects changes and generates scaffolding. In interactive mode, you'll be prompted to confirm before generation proceeds. 4. Explore Generated Files: Once complete, find your generated files at `document-models/todo-list/`: - `todo-list.json` and `schema.graphql`: Your model definition - `gen/`: Type-safe generated code - `src/reducers/todos.ts`: Skeleton reducer functions ready for implementation ### Using Connect (Alternative Method)

Tutorial: Manual Generation with Connect
This approach is useful when working with Connect's Document Model Editor or when you need explicit control over the generation process. #### Prerequisites - `TodoList.phd` file: Your document model specification exported from Connect. #### Steps 1. Place the Specification File in Your Project: Navigate to your Powerhouse project root and copy your `TodoList.phd` file there. 2. Run the Generator Command: ```bash ph generate document-model --document TodoList.phd ``` 3. Explore the Generated Files: After the command completes, find the new directory at `document-models/todo-list/`: - `todo-list.json` and `schema.graphql`: The definition of your model - `gen/`: Type-safe generated code including `types.ts`, `creators.ts`, etc. - `src/`: Implementation skeleton, including `src/reducers/todos.ts` with empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`
## Next Steps With your document model scaffolded, the next step is implementing the reducer logic in `document-models/todo-list/src/reducers/todos.ts`. Each reducer function takes the current state and action input, returning the new document state. Subsequently, write unit tests for your reducers to ensure they behave correctly. This cycle of defining, generating, implementing, and testing forms the core loop of document model development in Powerhouse. --- ## Implement document reducers > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/ImplementDocumentReducers NOTE: This is the same step from the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/ImplementOperationReducers), covered here in depth. The Mastery Track's only addition is the reducer logic for the computed `stats` field — if you've done the basic build, skim to the stats parts. ## The heart of document logic In our journey through Powerhouse Document Model creation, we've defined the "what" – the structure of our data ([State Schema](02-SpecifyTheStateSchema.md)) and the ways it can be changed ([Document Operations](03-SpecifyDocumentOperations.md)). We've also seen how the [Document Model Generator](04-UseTheDocumentModelGenerator.md) translates these specifications into a coded scaffold. Now, we arrive at the "how": implementing Document Reducers. Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the _new_ state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way. ## Recap: The journey to reducer implementation Before diving into the specifics of writing reducers, let's recall the preceding steps: 1. State Schema Definition: You designed the GraphQL `type` definitions for your document's data structure (e.g., `TodoListState`, `TodoItem`). 2. Document Operation Specification: You defined the GraphQL `input` types that specify the parameters for each allowed modification to your document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`). These were then associated with named operations (e.g., `ADD_TODO_ITEM`) in the Connect application. 3. Code Generation: You used `ph generate ` to create the necessary TypeScript types, action creators, and, crucially, the skeleton file for your reducers (typically `document-models//src/reducers/todos.ts`). This generated reducer file is our starting point. It will contain function stubs or an object structure expecting your reducer implementations, all typed according to your schema. ## What is a reducer? ### The core principles In the context of Powerhouse and inspired by patterns like Redux, a reducer is a pure function with the following signature (conceptually): `(currentState, action) => newState` Let's break down its components and principles: - `currentState`: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as immutable. - `action`: This is an object describing the operation to be performed. It typically has: - A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`). - An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ text: 'Buy groceries' }` for `AddTodoItemInput`). - `newState`: The reducer must return a _new_ state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself. ### Key principles guiding reducer implementation: 1. Purity: - Deterministic: Given the same `currentState` and `action`, a reducer must _always_ produce the same `newState`. - No Side Effects: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state. 2. Immutability: - Never Mutate `currentState`: You must never directly modify the `currentState` object or any of its nested properties. - Always Return a New Object for Changes: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object. - This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. :::tip[Powerhouse uses Immer.js] Powerhouse uses Immer.js under the hood, which means you can write code that _looks like_ it's mutating the state directly (e.g., `state.items.push(...)`), but Immer ensures it results in an immutable update. This gives you the best of both worlds: readable code and immutable state. ::: 3. Single Source of Truth: The document state managed by reducers is the single source of truth for that document instance. All UI rendering and data queries are derived from this state. 4. Delegation to specific operation handlers: While you can write one large reducer that uses a `switch` statement or `if/else if` blocks based on `action.type`, Powerhouse's generated code typically encourages a more modular approach. You'll often implement a separate function for each operation, which are then combined into a main reducer object or map. The `ph generate` command usually sets up this structure for you. For example, in your `document-models/todo-list/src/reducers/todos.ts`, you'll find an object structure like this: ```typescript import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list"; export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // Your logic for ADD_TODO_ITEM }, updateTodoItemOperation(state, action) { // Your logic for UPDATE_TODO_ITEM }, deleteTodoItemOperation(state, action) { // Your logic for DELETE_TODO_ITEM }, }; ``` The `TodoListTodosOperations` type is generated by Powerhouse and ensures your reducer object correctly implements all defined operations. The `state` and `action` parameters within these methods will also be strongly typed based on your schema. ## Implementing reducer logic: A practical guide Let's use our familiar `TodoList` example to illustrate common patterns. ### Basic implementation (matching the Manual Todo tutorial) The basic implementation matches what you built in the Manual Todo tutorial: ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // Generate a unique ID for the new todo item const id = generateId(); // Add the new item to the state (Immer handles immutability) state.items.push({ ...action.input, id, checked: false }); }, updateTodoItemOperation(state, action) { // Find the item to update by its ID const item = state.items.find((item) => item.id === action.input.id); // Return early if item not found if (!item) return; // Update only the fields that are provided (partial update) item.text = action.input.text ?? item.text; item.checked = action.input.checked ?? item.checked; }, deleteTodoItemOperation(state, action) { // Filter out the item with the matching ID state.items = state.items.filter((item) => item.id !== action.input.id); }, }; ``` INFO: Notice that `addTodoItemOperation` uses `generateId()` from `document-model/core` to create a unique ID. This is the recommended pattern — the ID is generated in the reducer, not passed from the UI. This ensures consistent, unique IDs across all operations. ### Advanced implementation (with statistics tracking) INFO: This section extends the basic reducers with statistics tracking, matching the advanced schema from the previous section. This demonstrates how to update computed/derived state alongside your primary data. For the advanced version with `stats`, we need to update the statistics whenever items are added, updated, or deleted: ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // Generate a unique ID for the new todo item const id = generateId(); // Update statistics state.stats.total += 1; state.stats.unchecked += 1; // Add the new item to the state state.items.push({ id, text: action.input.text, checked: false, // New items always start as unchecked }); }, updateTodoItemOperation(state, action) { // Find the specific item we want to update const item = state.items.find((item) => item.id === action.input.id); if (!item) { throw new Error(`Item with id ${action.input.id} not found`); } // Update text if provided if (action.input.text !== undefined) { item.text = action.input.text; } // Handle checked status changes and update stats if ( action.input.checked !== undefined && action.input.checked !== item.checked ) { if (action.input.checked) { state.stats.unchecked -= 1; state.stats.checked += 1; } else { state.stats.unchecked += 1; state.stats.checked -= 1; } item.checked = action.input.checked; } }, deleteTodoItemOperation(state, action) { // Find the item to determine its checked status for stats const item = state.items.find((item) => item.id === action.input.id); if (item) { // Update statistics state.stats.total -= 1; if (item.checked) { state.stats.checked -= 1; } else { state.stats.unchecked -= 1; } } // Remove the item from the list state.items = state.items.filter((item) => item.id !== action.input.id); }, }; ``` ### Common patterns explained #### 1. Adding an item ```typescript addTodoItemOperation(state, action) { const id = generateId(); // Generate unique ID state.items.push({ ...action.input, id, checked: false }); } ``` - We use `generateId()` to create a unique identifier - We spread `action.input` to get the text, add the generated ID and default `checked: false` - With Immer, this "mutation" is actually immutable #### 2. Updating an item ```typescript updateTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (!item) return; item.text = action.input.text ?? item.text; item.checked = action.input.checked ?? item.checked; } ``` - We find the item by ID - We use nullish coalescing (`??`) to only update fields that were provided - This allows partial updates (e.g., just changing `checked` without touching `text`) #### 3. Deleting an item ```typescript deleteTodoItemOperation(state, action) { state.items = state.items.filter((item) => item.id !== action.input.id); } ``` - We use `filter` to create a new array without the deleted item - Immer handles making this immutable ## Leveraging generated types As highlighted in [Using the Document Model Generator](04-UseTheDocumentModelGenerator.md), `ph generate` produces TypeScript types for your state (e.g., `TodoListState`, `TodoItem`) and the inputs for your operations (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`). Always use these generated types in your reducer implementations! ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { // TypeScript knows action.input has { text: string } const id = generateId(); state.items.push({ id, text: action.input.text, checked: false }); }, // ... other reducers }; ``` Using these types provides: - Compile-time safety: Catch errors related to incorrect property names or data types before runtime. - Autocompletion and IntelliSense: Improved developer experience in your IDE. - Clearer code: Types serve as documentation for the expected data structures. ## Practical implementation: Writing the `TodoList` reducers Now that you understand the principles, let's put them into practice by implementing the reducers for our `TodoList` document model.

Tutorial: Implementing the TodoList reducers
This tutorial assumes you have followed the steps in the previous chapters, especially using `ph generate TodoList.phd` to scaffold your document model's code. ### Implement the operation reducers Navigate to `document-models/todo-list/src/reducers/todos.ts`. The generator will have created a skeleton file. Replace its contents with the following logic. Basic version (without stats): ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { const id = generateId(); state.items.push({ ...action.input, id, checked: false }); }, updateTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (!item) return; item.text = action.input.text ?? item.text; item.checked = action.input.checked ?? item.checked; }, deleteTodoItemOperation(state, action) { state.items = state.items.filter((item) => item.id !== action.input.id); }, }; ``` Advanced version (with stats): ```typescript export const todoListTodosOperations: TodoListTodosOperations = { addTodoItemOperation(state, action) { const id = generateId(); state.stats.total += 1; state.stats.unchecked += 1; state.items.push({ id, text: action.input.text, checked: false, }); }, updateTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (!item) { throw new Error(`Item with id ${action.input.id} not found`); } if (action.input.text !== undefined) { item.text = action.input.text; } if ( action.input.checked !== undefined && action.input.checked !== item.checked ) { if (action.input.checked) { state.stats.unchecked -= 1; state.stats.checked += 1; } else { state.stats.unchecked += 1; state.stats.checked -= 1; } item.checked = action.input.checked; } }, deleteTodoItemOperation(state, action) { const item = state.items.find((item) => item.id === action.input.id); if (item) { state.stats.total -= 1; if (item.checked) { state.stats.checked -= 1; } else { state.stats.unchecked -= 1; } } state.items = state.items.filter((item) => item.id !== action.input.id); }, }; ```
## Reducers and the event sourcing model Every time a reducer processes an operation and returns a new state, Powerhouse records the original operation (the "event") in an append-only log associated with the document instance. The current state of the document is effectively a "fold" or "reduction" of all past events, applied sequentially by the reducers. This is why purity and immutability are so critical: - Purity ensures that replaying the same sequence of events will always yield the exact same final state. - Immutability ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history. ## Conclusion Implementing document reducers is where you breathe life into your document model's specification. By adhering to the principles of purity and immutability, and by leveraging the type safety provided by Powerhouse's code generation, you can build predictable, testable, and maintainable business logic. These reducers form the immutable backbone of your document's state management, perfectly aligning with the event sourcing architecture that underpins Powerhouse. With your reducers implemented, your document model is now functionally complete from a data manipulation perspective. The next chapter covers how to write tests for this logic to ensure its correctness and reliability. --- ## Implement document model tests > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/ImplementDocumentModelTests NOTE: This is the same step from the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/WriteDocumentModelTests), covered here in depth. The Mastery Track's only addition is tests for the computed `stats` field — if you've done the basic build, skim to the stats parts. ## Ensuring robustness and reliability In the previous chapter, we implemented the core reducer logic for our document model. Now, we reach a critical stage that underpins the reliability and correctness of our entire model: Implementing Document Model Tests. Testing is not an afterthought; it's an integral part of the development lifecycle, especially in systems like Powerhouse where data integrity and predictable state transitions are paramount. Well-crafted tests serve as a safety net, allowing you to refactor and extend your document model with confidence. This document provides a practical, hands-on tutorial for testing the `TodoList` document model reducers you have just built. ## Practical implementation: Writing and running the TodoList tests This tutorial assumes you have implemented the `TodoList` reducers as described in the previous chapter and that the code generator has created a test file skeleton at `document-models/todo-list/src/tests/todos.test.ts`.

Tutorial: Implementing and running the TodoList reducer tests
### 1. Implement the reducer tests With the reducer logic in place, it's critical to test it. Navigate to the generated test file at `document-models/todo-list/src/tests/todos.test.ts` and replace its contents with comprehensive tests. This suite tests each operation, verifying not only that the `items` array is correct, but also that the operation itself is recorded properly in the document's history. Basic tests (matching the Manual Todo tutorial): ```typescript AddTodoItemInput, DeleteTodoItemInput, UpdateTodoItemInput, } from "todo-tutorial/document-models/todo-list"; reducer, utils, isTodoListDocument, addTodoItem, AddTodoItemInputSchema, updateTodoItem, UpdateTodoItemInputSchema, deleteTodoItem, DeleteTodoItemInputSchema, TodoItemSchema, } from "todo-tutorial/document-models/todo-list"; describe("Todos Operations", () => { it("should handle addTodoItem operation", () => { const document = utils.createDocument(); const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema()); const updatedDocument = reducer(document, addTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); // Verify the operation was recorded expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_TODO_ITEM", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); it("should handle updateTodoItem operation to update text", () => { const mockItem = generateMock(TodoItemSchema()); const input: UpdateTodoItemInput = generateMock( UpdateTodoItemInputSchema(), ); input.id = mockItem.id; const newText = "new text"; input.text = newText; input.checked = undefined; const document = utils.createDocument({ global: { items: [mockItem], }, }); const updatedDocument = reducer(document, updateTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); // Verify the operation was recorded expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "UPDATE_TODO_ITEM", ); // Verify the state was updated correctly const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); expect(updatedItem?.text).toBe(newText); expect(updatedItem?.checked).toBe(mockItem.checked); }); it("should handle updateTodoItem operation to update checked", () => { const mockItem = generateMock(TodoItemSchema()); const input: UpdateTodoItemInput = generateMock( UpdateTodoItemInputSchema(), ); input.id = mockItem.id; const newChecked = !mockItem.checked; input.checked = newChecked; input.text = undefined; const document = utils.createDocument({ global: { items: [mockItem], }, }); const updatedDocument = reducer(document, updateTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); const updatedItem = updatedDocument.state.global.items.find( (item) => item.id === input.id, ); expect(updatedItem?.text).toBe(mockItem.text); expect(updatedItem?.checked).toBe(newChecked); }); it("should handle deleteTodoItem operation", () => { const mockItem = generateMock(TodoItemSchema()); const document = utils.createDocument({ global: { items: [mockItem], }, }); const input: DeleteTodoItemInput = generateMock( DeleteTodoItemInputSchema(), ); input.id = mockItem.id; const updatedDocument = reducer(document, deleteTodoItem(input)); expect(isTodoListDocument(updatedDocument)).toBe(true); // Verify the operation was recorded expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "DELETE_TODO_ITEM", ); // Verify the item was removed from state const updatedItems = updatedDocument.state.global.items; expect(updatedItems).toHaveLength(0); }); }); ``` Advanced tests (with stats verification): INFO: If you implemented the advanced version with statistics tracking, add these additional tests to verify the stats are updated correctly. ```typescript describe("Todos Operations with Stats", () => { it("should update stats when adding a todo item", () => { const document = utils.createDocument(); const input = { text: "Buy milk" }; const updatedDocument = reducer(document, addTodoItem(input)); expect(updatedDocument.state.global.items).toHaveLength(1); expect(updatedDocument.state.global.stats.total).toBe(1); expect(updatedDocument.state.global.stats.unchecked).toBe(1); expect(updatedDocument.state.global.stats.checked).toBe(0); }); it("should update stats when checking a todo item", () => { const document = utils.createDocument(); // Add an item first const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" })); const itemId = addedDocument.state.global.items[0].id; // Now check it const updatedDocument = reducer( addedDocument, updateTodoItem({ id: itemId, checked: true }), ); expect(updatedDocument.state.global.stats.total).toBe(1); expect(updatedDocument.state.global.stats.unchecked).toBe(0); expect(updatedDocument.state.global.stats.checked).toBe(1); }); it("should update stats when deleting an unchecked todo item", () => { const document = utils.createDocument(); // Add an item const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" })); const itemId = addedDocument.state.global.items[0].id; // Delete it const updatedDocument = reducer( addedDocument, deleteTodoItem({ id: itemId }), ); expect(updatedDocument.state.global.items).toHaveLength(0); expect(updatedDocument.state.global.stats.total).toBe(0); expect(updatedDocument.state.global.stats.unchecked).toBe(0); expect(updatedDocument.state.global.stats.checked).toBe(0); }); it("should update stats when deleting a checked todo item", () => { const document = utils.createDocument(); // Add and check an item const addedDocument = reducer(document, addTodoItem({ text: "Buy milk" })); const itemId = addedDocument.state.global.items[0].id; const checkedDocument = reducer( addedDocument, updateTodoItem({ id: itemId, checked: true }), ); // Delete it const updatedDocument = reducer( checkedDocument, deleteTodoItem({ id: itemId }), ); expect(updatedDocument.state.global.items).toHaveLength(0); expect(updatedDocument.state.global.stats.total).toBe(0); expect(updatedDocument.state.global.stats.checked).toBe(0); }); }); ``` ### 2. Run the tests Now, run the tests from your project's root directory to verify your implementation. ```bash pnpm run test ``` Or with npm: ```bash npm test ``` If all tests pass, you have successfully verified the core logic of your `TodoList` document model. This ensures that the reducers you wrote behave exactly as expected.
## Best practices for document model tests While the tutorial provides a concrete example, keep these general best practices in mind when writing your tests: - Isolate Tests: Each `it` block should ideally test one specific aspect or scenario. `beforeEach` is crucial for resetting state between tests. - Descriptive Names: Name your `describe` and `it` blocks clearly so they explain what's being tested. - AAA Pattern (Arrange, Act, Assert): - Arrange: Set up the initial state and any required test data (e.g., using `utils.createDocument()` and defining `input` objects). - Act: Execute the operation by calling the `reducer` with an action from a `creator`. - Assert: Check if the outcome is as expected using `expect()`. - Test Immutability: A key assertion is to ensure the state is not mutated directly. You can check that a new array or object was created: `expect(newState.items).not.toBe(oldState.items);`. - Cover Edge Cases: Test what happens when an operation receives invalid input (e.g., trying to update an item that doesn't exist). Your test should confirm the reducer either throws an error or returns the state unchanged, depending on your implementation. - Run Tests Frequently: Integrate testing into your development workflow. Run tests after making changes to ensure you haven't broken anything. The `pnpm run test` (or `npm test`) command is your friend. ## Conclusion: The payoff of diligent testing Implementing comprehensive tests for your document model reducers is an investment that pays dividends in the long run. It leads to: - Higher Quality Models: More reliable and robust document models with fewer bugs. - Increased Confidence: Ability to make changes and refactor code without fear of breaking existing functionality. - Easier Debugging: When tests fail, they pinpoint the exact operation and scenario that's problematic. - Better Collaboration: Tests clarify the intended behavior of the document model for all team members. By following the tutorial and applying these best practices, you can build a strong suite of tests that safeguard the integrity and functionality of your document models. This diligence is a hallmark of a "Mastery Track" developer, ensuring that the solutions you build are not just functional but also stable, maintainable, and trustworthy. ## Up next In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the TodoList document model in action. For a complete, working example, you can always have a look at the [Example TodoList Repository](/academy/Build/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track. --- ## Example: Todo-demo-package > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/ExampleToDoListRepository INFO: The Todo-demo is maintained by the Powerhouse Team and serves as a reference for testing and introducing new features. It will be continuously updated alongside the accompanying documentation. https://github.com/powerhouse-inc/todo-demo There are several ways to explore this package: ### Option 1: Rebuild the Todo-demo The Todo-demo and repository are your main reference points during the Mastery Track. Follow the steps in the "Mastery Track – Document Model Creation" chapters to build along with the examples. Key patterns used in the repository: - Naming convention: `TodoList`, `TodoItem`, `TodoListState` (one word, PascalCase) - Document type: `powerhouse/todo-list` - Module name: `todos` - ID generation: Uses `generateId()` from `document-model/core` in the reducer - Hooks: Uses `useSelectedTodoListDocument` for state management in the editor ### Option 2: Clone and run the code locally The package includes: - The Document Model - Reducer Code - Reducer Tests - Editor Code - Drive-app Code You can clone the repository and run Vetra Studio to see all the code in action: ```bash git clone https://github.com/powerhouse-inc/todo-demo cd todo-demo pnpm install ph vetra --watch ```

Alternatively: Run with Connect
```bash git clone https://github.com/powerhouse-inc/todo-demo cd todo-demo pnpm install ph connect ```
### Option 3: Install the todo demo package in a (local) host app Alternatively, you can install this package in a Powerhouse project or in your deployed host apps: ```bash ph install @powerhousedao/todo-demo ``` ## Comparing the Manual Todo tutorial vs Mastery Track | Aspect | Manual Todo tutorial | Mastery Track (Advanced) | | ------------------ | -------------------------- | ------------------------------------ | | Schema | Basic `items` array only | Includes `stats` object for tracking | | Reducer complexity | Simple CRUD operations | Includes statistics updates | | Editor | Component-based with hooks | Same approach + stats display | | Tests | Basic operation tests | Includes stats verification tests | Both approaches use the same naming conventions and patterns — the Mastery Track simply extends the foundation with additional features to demonstrate more advanced concepts. --- ## Document Model Versioning > Source: https://academy.vetra.io/academy/Build/DocumentModelCreation/DocumentModelVersioning TIP: This chapter covers advanced document model versioning—a system for evolving document schemas and operations while maintaining backward compatibility with existing documents. This is essential when your document models need to change over time in production environments. ## Why Versioning? Document models in Powerhouse are event-sourced. Once a document is created with a certain schema (v1), and operations are applied to it, you can't simply change the schema without breaking existing documents. Versioning solves this problem by allowing you to: - Add new fields to the state schema - Add new operations to the document model - Modify reducer logic for new documents - Automatically upgrade old documents to new versions when needed INFO: Document Model Versioning is a system that allows multiple versions of the same document model to coexist. Each version has its own schema, operations, and reducers. Documents created with older versions continue to work with their original reducers, while new documents use the latest version. Upgrade manifests define how to migrate documents between versions. --- ## How Versioning Works ### The Problem It Solves Consider a simple Todo document model: Version 1 State: ```graphql type TodoState { todos: [Todo!]! } ``` Now you want to add a `title` field to track the list's name: Version 2 State: ```graphql type TodoState { title: String todos: [Todo!]! } ``` Without versioning, existing v1 documents would break because they don't have a `title` field. With versioning: - V1 documents continue to work with the v1 reducer - New documents are created with v2 - V1 documents can be upgraded to v2 when needed ### Key Components Document model versioning consists of four key components: | Component | Purpose | | ----------------------- | ------------------------------------------------------------------ | | Version Folders | Separate `v1/`, `v2/` directories containing version-specific code | | DocumentModelModule | Each version exports a module with explicit `version` number | | Upgrade Manifest | Declares supported versions and upgrade paths | | Upgrade Reducer | Transforms document state from one version to another | --- ## Folder Structure When versioning is enabled, the document model generator creates a versioned folder structure: ``` document-models/ └── todo/ ├── v1/ # Version 1 │ ├── gen/ # Auto-generated code (DO NOT EDIT) │ │ ├── reducer.ts │ │ ├── creators.ts │ │ ├── types.ts # V1 TypeScript types │ │ └── ... │ ├── src/ │ │ └── reducers/ # Your v1 reducer implementations │ │ └── todo-operations.ts │ └── module.ts # Exports DocumentModelModule with version: 1 │ ├── v2/ # Version 2 │ ├── gen/ │ │ └── types.ts # V2 TypeScript types (includes 'title') │ ├── src/ │ │ └── reducers/ │ └── module.ts # Exports DocumentModelModule with version: 2 │ ├── upgrades/ # Migration logic │ ├── versions.ts # Supported versions list │ ├── v2.ts # Upgrade reducer: v1 → v2 │ └── upgrade-manifest.ts # Ties everything together │ └── document-models.ts # Exports all versions + manifests ``` --- ## Core Type Definitions Understanding the underlying types helps you implement versioning correctly: ### UpgradeTransition Defines a single version upgrade: ```typescript type UpgradeTransition = { toVersion: number; upgradeReducer: UpgradeReducer; description?: string; }; ``` ### UpgradeManifest Declares all supported versions and their upgrade paths: ```typescript type UpgradeManifest = { documentType: string; latestVersion: number; supportedVersions: TVersions; upgrades: { // Keys are "v2", "v3", etc. (never "v1" - nothing to upgrade from) [V in Exclude, 1> as `v${V}`]: UpgradeTransition; }; }; ``` --- ## Implementation Guide ### Step 1: Enable Versioning in Code Generation Versioning is enabled by default when using the Powerhouse CLI: ```bash ph generate TodoList.phd ``` Or when using Vetra Studio, versioning support is configured in your project settings. ### Step 2: Version Configuration Files versions.ts - Declare supported versions: ```typescript // upgrades/versions.ts export const supportedVersions = [1, 2] as const; export const latestVersion = supportedVersions[1]; // 2 ``` ### Step 3: Document Model Module Each version exports a `DocumentModelModule` with an explicit version number: ```typescript // v1/module.ts export const Todo: DocumentModelModule = { version: 1, // Explicit version number reducer, actions, utils, documentModel: createState(defaultBaseState(), documentModel), }; ``` ```typescript // v2/module.ts export const Todo: DocumentModelModule = { version: 2, // Different version reducer, actions, utils, documentModel: createState(defaultBaseState(), documentModel), }; ``` ### Step 4: Upgrade Reducer The upgrade reducer transforms a document from one version to the next: ```typescript // upgrades/v2.ts function upgradeReducer( document: PHDocument, action: Action, ): PHDocument { return { ...document, state: { ...document.state, global: { ...document.state.global, title: "", // Initialize the new field }, }, initialState: { ...document.initialState, global: { ...document.initialState.global, title: "", // Also in initial state }, }, }; } export const v2: UpgradeTransition = { toVersion: 2, upgradeReducer, description: "Add title field to global state", }; ``` ### Step 5: Upgrade Manifest Tie everything together in the manifest: ```typescript // upgrades/upgrade-manifest.ts export const upgradeManifest: UpgradeManifest = { documentType: "my-org/todo", latestVersion, supportedVersions, upgrades: { v2 }, }; ``` ### Step 6: Export All Versions ```typescript // document-models.ts export const documentModels: DocumentModelModule[] = [TodoV1, TodoV2]; export const upgradeManifests: UpgradeManifest[] = [ todoUpgradeManifest, ]; ``` --- ## Integration with Connect and Switchboard ### How Connect Loads Versioned Documents Connect automatically loads all document model versions and upgrade manifests from your Vetra packages: ```typescript // Simplified view of Connect's reactor setup const documentModelModules = vetraPackages.flatMap( (pkg) => pkg.modules.documentModelModules, ); const upgradeManifests = vetraPackages.flatMap((pkg) => pkg.upgradeManifests); const reactor = await createBrowserReactor( documentModelModules, upgradeManifests, renown, ); ``` ### Creating Documents at Specific Versions By default, new documents are created at the latest version. You can optionally specify a version: ```typescript // Create at latest version (default) const doc = await client.createEmpty("my-org/todo"); // doc.state.document.version === 2 (latest) // Create at specific version const v1Doc = await client.createEmpty("my-org/todo", { documentModelVersion: 1, }); // v1Doc.state.document.version === 1 ``` ### Querying Documents Documents can be queried regardless of version: ```typescript // Find all todo documents (both v1 and v2) const result = await client.find({ type: "my-org/todo" }); ``` --- ## Use Cases ### 1. Adding a New Field Scenario: Your Todo document needs a `title` field. Solution: 1. Create v2 with the new field in the state schema 2. Implement upgrade reducer that sets `title: ""` 3. New documents get v2; existing v1 documents can be upgraded ### 2. Adding New Operations Scenario: V1 has `ADD_TODO`, `REMOVE_TODO`. V2 adds `EDIT_TITLE`. How it works: - V2 module includes the new operation - V1 documents don't have access to `EDIT_TITLE` until upgraded - The upgrade manifest handles the migration ### 3. Changing Reducer Behavior Scenario: V2 items should include an `addedAt` timestamp. ```typescript // V1 reducer - no timestamp function v1StateReducer(state, action) { if (action.type === "ADD_ITEM") { return { ...state, global: { items: [ ...state.global.items, { id: action.input.id, name: action.input.name, }, ], }, }; } } // V2 reducer - adds timestamp field function v2StateReducer(state, action) { if (action.type === "ADD_ITEM") { return { ...state, global: { items: [ ...state.global.items, { id: action.input.id, name: action.input.name, addedAt: action.input.addedAt, // New field from input }, ], }, }; } } ``` --- ## Best Practices ### Upgrade Reducer Guidelines 1. Always handle both `state` and `initialState` - Both need to be migrated 2. Provide sensible defaults for new fields 3. Never lose data - Transform existing data, don't delete it 4. Keep upgrade reducers pure - No side effects or async operations ### Version Compatibility - Don't remove operations from newer versions unless absolutely necessary - Don't change existing operation input schemas - add new operations instead - Document breaking changes in the upgrade transition description ### Testing Upgrades Test your upgrade reducers thoroughly: ```typescript it("should upgrade v1 document to v2", () => { const v1Doc = createV1Document(); v1Doc.state.global.todos = [{ id: "1", title: "Test", completed: false }]; const v2Doc = upgradeReducer(v1Doc, {} as Action); expect(v2Doc.state.global.title).toBe(""); // New field initialized expect(v2Doc.state.global.todos).toEqual(v1Doc.state.global.todos); // Data preserved }); ``` --- ## Summary | Concept | Description | | -------------------------- | ----------------------------------------------------------- | | Version Folders | `v1/`, `v2/` directories with version-specific code | | DocumentModelModule | Exports with explicit `version` field | | UpgradeTransition | Defines how to migrate from one version to the next | | UpgradeManifest | Declares all versions and upgrade paths for a document type | | Backward Compatibility | Old documents work with their original reducers | | Automatic Upgrades | Reactor handles version detection and migration | Document model versioning enables your applications to evolve safely while preserving the integrity of existing data. By following these patterns, you can confidently add new features, modify schemas, and improve your document models over time. --- ## Related Documentation - [Use the Document Model Generator](/academy/Build/DocumentModelCreation/UseTheDocumentModelGenerator) - [Implement Document Reducers](/academy/Build/DocumentModelCreation/ImplementDocumentReducers) - [Powerhouse CLI Reference](/academy/Reference/CLITooling/PowerhouseCLI) --- ## Build document editors > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/BuildingDocumentEditors ## Build with React on Powerhouse At Powerhouse, frontend development for document editors follows a simple and familiar flow, leveraging the power and flexibility of React. ### Development environment Vetra Studio is your primary tool for builder workflows and editor development. When you run `ph vetra --watch`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library). #### Key aspects of the Powerhouse development environment: - React Foundation: Build your editor UIs using React components, just as you would in any standard React project. - Automatic Build Processes: Tailwind CSS is installed by default and fully managed by Vetra Studio. There's no need to manually configure or run Tailwind or other build processes during development. Vetra Studio handles CSS generation and other necessary build steps automatically, especially when you publish a package. - Styling Flexibility: You are not limited to Tailwind. Regular CSS (`.css` files), inline styles, and any React-compatible styling method work exactly as you would expect. #### Powerhouse aims to keep your developer experience clean, familiar, and focused: - Build React components as you normally would. - Use styling approaches you're comfortable with. - Trust Vetra Studio to handle the setup and build processes for you.

Alternatively: Use Connect for development
You can also use Connect as your development environment by running `ph connect`. Connect provides a similar dynamic local environment where you can preview your document models and their editors live. The development experience is essentially the same, with Connect also handling Tailwind CSS and build processes automatically.
### Generating your editor template When using Vetra Studio, editor generation is automatic and integrated into your workflow. Simply create an Editor specification document in your Vetra Studio Drive, and Vetra will automatically generate the editor template code for you. #### With Vetra Studio (Recommended) 1. Open Vetra Studio (`ph vetra --watch`) 2. In your Vetra Studio Drive, click "Add new specification" in the Editors section 3. Select your document model (e.g., `TodoList`) to link the editor to 4. Name your editor (e.g., `todo-list-editor`) 5. Vetra automatically generates the `editors/todo-list-editor/editor.tsx` template That's it! No manual commands needed. Vetra watches your specifications and generates code as you work.

Alternatively: Manual generation with ph generate
If you're using Connect or prefer manual control, you can use the `ph generate` command to create an editor template: ```bash ph generate --editor todo-list-editor --document-types powerhouse/todo-list ``` This will create the template in the `editors/todo-list-editor/editor.tsx` folder. If you want a refresher on how to define your document model specification please read the chapter on [specifying the State Schema](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema)
### Styling your editor You have several options for styling your editor components: 1. Default HTML Styling: Standard HTML tags (`
`, `
`, ` ); } ``` Why hooks are recommended: - ✅ Self-contained components: Each component gets its own connection to the document - ✅ Less boilerplate: No need to pass props through multiple levels - ✅ Easier refactoring: Move components around without rewiring props - ✅ Modern React pattern: Follows React's recommended approach for state management ### Method 2: Using Props 📦 The props-based approach receives the document and dispatch function as properties passed from a parent component. ```typescript export type IProps = EditorProps; export default function Editor(props: IProps) { const { document, dispatch } = props; const state = document.state.global; // Now you'd pass state and dispatch to child components as props return (

); } ``` When props might be useful: - When you need strict control over which components can access state - When building components that should work outside of Powerhouse context - For testing purposes where you want to inject mock state ### Which should you use? | Scenario | Recommended Approach | | ------------------------------------------------- | -------------------- | | Building a standard Powerhouse editor | Hooks 🪝 | | Component needs document state | Hooks 🪝 | | Building reusable UI components (buttons, inputs) | Props 📦 | | Need to test components in isolation | Props 📦 | Bottom line: Use hooks for most Powerhouse editor development. It's simpler, cleaner, and matches the patterns used in the [todo-demo repository](https://github.com/powerhouse-inc/todo-demo). ### Additional hooks for editors Beyond the document-specific hooks (like `useSelectedTodoListDocument`), the reactor-browser package provides these hooks for your editors: | Hook | Description | | --------------------------- | --------------------------------------------- | | `useSelectedDocument` | Returns the currently selected document | | `useSelectedDocumentId` | Returns just the ID of the selected document | | `useDocumentById` | Returns a document by its ID | | `useSelectedDrive` | Returns the currently selected drive | | `useRevisionHistoryVisible` | Check and control revision history visibility | | `usePHModal` | Manage modals in your editor | Example: Using `useDocumentById` to reference another document ```typescript export function RelatedDocument({ documentId }: { documentId: string }) { const relatedDoc = useDocumentById(documentId); if (!relatedDoc) return Loading...; return (

Related: {relatedDoc.name}
{/ Display related document info /}
); } ``` Example: Showing a modal from your editor ```typescript export function CreateNewButton({ documentType }: { documentType: string }) { return ( ); } ``` For a complete list of all available hooks, see the [React Hooks API Reference](/academy/Reference/EditorsUI/ReactHooks). ## Local vs. Global State When building editors, you'll work with two types of state: - Global Document State: Data that is part of the document itself and should be saved. This is accessed via hooks (`useSelectedTodoListDocument`) or props (`document.state.global`). You modify it by dispatching actions. - Local Component State: UI-specific state that doesn't need to be saved (e.g., "is the dropdown open?", "what's in the input field before submission?"). Use React's `useState` hook for this. ```typescript export function AddTodo() { // Local state - just for this component's UI const [inputValue, setInputValue] = useState(''); // Global document state - saved in the document const [todoList, dispatch] = useSelectedTodoListDocument(); const handleSubmit = () => { if (inputValue.trim()) { dispatch(addTodoItem({ text: inputValue })); // Updates global state setInputValue(''); // Clears local state } }; return (
setInputValue(e.target.value)} />
); } ``` ## Handling dispatch errors When dispatching actions to a document, you may want to handle errors that occur during action execution. The `dispatch` function accepts an optional `onErrors` callback as its second parameter, which is invoked with any errors thrown by the reducers when processing the actions. ```typescript useSelectedTodoListDocument, addTodoItem, } from "todo-tutorial/document-models/todo-list"; export function AddTodo() { const [todoList, dispatch] = useSelectedTodoListDocument(); const handleAdd = (text: string) => { dispatch(addTodoItem({ text }), (errors) => { // Handle errors - e.g., show a toast notification console.error("Failed to add todo:", errors); alert(`Error: ${errors[0]?.message}`); }); }; // ... rest of component } ``` This pattern is useful when you need to: - Display error messages to users - Log errors for debugging - Trigger recovery actions when an operation fails ## Powerhouse component library The `@powerhousedao/document-engineering/scalars` package provides reusable UI components, many of them based on GraphQL scalar types. For more information read our chapter on the [Component Library](/academy/Reference/EditorsUI/DocumentEngineering). ### Exploring components You can explore available components, see usage examples, and understand their properties (props) using our Storybook instance: [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy) Storybook allows you to: - Visually inspect each component. - Interact with different states and variations. - View code snippets for basic implementation. - Consult the props table for detailed configuration options. ### Using components 1. Import: Add an import statement at the top of your editor file: ```typescript import { Checkbox, StringField, Form, } from "@powerhousedao/document-engineering/scalars"; ``` 2. Implement: Use the component in your JSX, configuring it with props: ```typescript // Example using StringField for an input
{ / Handle submission / }}> setTaskText(e.target.value)} /> ```

Tutorial: Implementing the TodoList Editor
## Build a TodoList editor Now build the editor: the user interface for the TodoList document model. It runs inside the Connect app to create, update, and delete TodoList items, and (if you followed the advanced version) displays the statistics from your reducers. ## Generate the editor template ### Using Vetra Studio (Recommended) With Vetra Studio running (`ph vetra --watch`), simply create an Editor specification: 1. In your Vetra Studio Drive, click "Add new specification" in the Editors section 2. Select the TodoList document model to link the editor to 3. Name your editor `todo-list-editor` 4. Vetra automatically generates `editors/todo-list-editor/editor.tsx` Once complete, navigate to the `editors/todo-list-editor/editor.tsx` file and open it in your IDE.

Alternatively: Manual generation with ph generate
If you're not using Vetra Studio, run the command below to generate the editor template: ```bash ph generate --editor todo-list-editor --document-types powerhouse/todo-list ``` This command reads the TodoList document model definition from the `document-models` folder and generates the editor template in the `editors/todo-list-editor` folder as `editor.tsx`. Notice the `--editor` flag which specifies the editor name, and the `--document-types` flag defines the document type `powerhouse/todo-list`.
### Editor implementation options You have several options for styling your editor component: 1. Default HTML Styling: Standard HTML tags (`
`, `
`, ` ); } ``` ### Todo item component ```typescript // editors/todo-list-editor/components/Todo.tsx type Props = { todo: TodoItem; }; export function Todo({ todo }: Props) { const [isEditing, setIsEditing] = useState(false); const [todoList, dispatch] = useSelectedTodoListDocument(); if (!todoList) return null; const onChangeTodoChecked: ChangeEventHandler = (event) => { dispatch(updateTodoItem({ id: todo.id, checked: event.target.checked })); }; const onClickDeleteTodo: MouseEventHandler = () => { dispatch(deleteTodoItem({ id: todo.id })); }; const onSubmitUpdateTodoText: FormEventHandler = (event) => { event.preventDefault(); const form = event.currentTarget; const textInput = form.elements.namedItem("todoText") as HTMLInputElement; const text = textInput.value; if (!text) return; dispatch(updateTodoItem({ id: todo.id, text })); setIsEditing(false); }; if (isEditing) { return (

); } return (

{todo.text}

); } ``` --- ## Advanced: Adding stats display INFO: If you implemented the advanced version with statistics tracking, you can add a stats component to display the todo counts. ```typescript // Add to TodoList.tsx export function TodoList() { const [selectedTodoList] = useSelectedTodoListDocument(); if (!selectedTodoList) return null; const { items, stats } = selectedTodoList.state.global; return (

TodoList
{/ Stats section (only show if there are items) /} {items.length >= 2 && (

Total

{stats.total}

Completed

{stats.checked}

Remaining

{stats.unchecked}

)}

); } ``` --- ## Test your editor Now you can run Vetra Studio and see the TodoList editor in action: ```bash ph vetra --watch ``` In Vetra Studio, you'll be able to create and test your TodoList documents. Click on the Document Models section and create a new TodoList document. TIP: The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Vetra Studio.

Alternatively: Test with Connect
You can also run the Connect app to see the TodoList editor in action: ```bash ph connect ``` In Connect, in the bottom right corner you'll find a new Document Model that you can create: TodoList. Click on it to create a new TodoList document. The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect.

## Up Next Next, build a [custom Drive-app](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) for your TodoList document. When you have many TodoLists sitting in a drive, a Drive-app lets you organize and track them at a glance. ### Further Reading - [React Hooks API Reference](/academy/Reference/EditorsUI/ReactHooks) — Complete reference for all available Powerhouse hooks - [Component Library](/academy/Reference/EditorsUI/DocumentEngineering) — Pre-built UI components for your editors --- ## Build a Drive-app > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/BuildingADriveExplorer Drive-apps enhance how contributors and organizations interact with document models. They create an 'app-like' experience by providing a custom interface for exploring and interacting with the contents of a drive. TIP: A Drive-app offers a tailored application designed around its document models. Think of a Drive-app as a specialized lens—it offers different ways to visualize, organize, and interact with the data stored within a drive, making it more intuitive and efficient for specific use cases. ### Drive-apps are purpose-built Organizations typically build Drive-apps for specific use cases, often packaging them with a corresponding document model. This allows for customized user experiences, streamlined workflows, and maximized efficiency for contributors. Drive-apps bridge the gap between raw data and usability, unlocking the full potential of document models within the Powerhouse framework. ### Key features of Drive-apps - Custom Views & Organization – Drive-apps can present data in formats like Kanban boards, list views, or other structured layouts to suit different workflows. - Aggregated Insights – They can provide high-level summaries of important details across document models, enabling quick decision-making. - Enhanced Interactivity – Drive-apps can include widgets, data processors, or read models to process and display document data dynamically. ## Build a Drive-app Drive-apps provide custom interfaces for interacting with the contents of a drive. Let's start with a quick overview of the steps for building a Drive-app. We will then apply these steps to create our todo-list Drive-app. ### Step 1. Generate the scaffolding code When using Vetra Studio, Drive-app generation is automatic. Simply create a Drive-app specification document in your Vetra Studio Drive: 1. Open Vetra Studio (`ph vetra --watch`) 2. In your Vetra Studio Drive, click "Add new specification" in the Apps section 3. Name your Drive-app (e.g., `todo-list-drive-explorer`) 4. Vetra automatically generates the Drive-app template code

Alternatively: Manual generation with ph generate
If you're not using Vetra Studio, use the `generate drive editor` command to create the basic template structure: ```bash ph generate --drive-editor ```
### Step 2. Update the manifest file After creating your Drive-app, you need to update its `powerhouse.manifest.json` file. This file identifies your project and its components within the Powerhouse ecosystem. ### Step 3. Customize the Drive-app Review the generated template and modify it to better suit your document model: 1. Remove unnecessary files and components 2. Add custom views specific to your data model 3. Implement specialized interactions for your use case ### About the Drive-app template The default template provides a solid foundation. It contains: - A tree structure navigation panel - Basic file/folder operations - Standard layout components But the real power comes from tailoring the interface to your specific document models. Now, let's implement a specific example for the to-do list we've been working on throughout this guide. ## Implementation example: todo-list Drive-app This example demonstrates how to create a todo-list Drive-app application using the Powerhouse platform. The application allows users to create and manage to-do lists with a visual progress indicator. WARNING: If you've been following the Mastery Track, you can continue with the to-do list document model and Powerhouse project you've created. For more details, you can refer to the [Document Model Creation guide](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema). If not, you can follow the shortened guide below to prepare your project for this tutorial.

Prepare your Powerhouse Project to create a custom drive
### 1. Create a To-do document model: - Initialize a new project with `ph init` and give it a project name. - Start by running Vetra Studio locally with `ph vetra --watch` - Follow the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/DefineToDoListDocumentModel) to create your TodoList document model specification. - Drop the downloaded file in the Vetra Studio drive. You'll find it under document models. Vetra should now automatically generate the necessary code for your project ### 2. Add the reducer code: - Copy the code from [`todos.ts`](https://github.com/powerhouse-inc/todo-tutorial/blob/step-3-complete-implement-todo-list-document-model-reducer-operation-handlers/document-models/todo-list/src/reducers/todos.ts) - Paste it into `document-models/todo-list/src/reducers/todos.ts` ### 3. Generate a document editor: In Vetra Studio, create an Editor specification: 1. Click "Add new specification" in the Editors section 2. Select the TodoList document model 3. Name your editor `TodoList` 4. Vetra automatically generates the editor template

Alternatively: Manual generation
```bash ph generate --editor TodoList --document-types powerhouse/todo-list ```
### 4. Add the editor code: - Follow the [Build TodoList Editor guide](/academy/Build/ManualTodoTutorial/BuildToDoListEditor) to implement your editor components.

Alternatively: Use Connect instead of Vetra Studio
You can also start by running Connect locally with `ph connect` instead of Vetra Studio. The workflow is the same, with Connect providing a similar development environment.

## Generate the Drive-app ### 1. Generate a Drive-app: With Vetra Studio running (`ph vetra --watch`), create a Drive-app specification: 1. In your Vetra Studio Drive, click "Add new specification" in the Apps section 2. Name your Drive-app `todo-list-drive-explorer` 3. Vetra automatically generates the Drive-app template in `editors/todo-list-drive-explorer/`

Alternatively: Manual generation with ph generate
```bash ph generate --drive-editor todo-list-drive-explorer ```
### 2. Update the `powerhouse.manifest.json` file: - The manifest file contains metadata for your package that is displayed when other users install it. Update the manifest to register your new Drive-app: ```json { "name": "To-do List Package", "description": "A simple todo-list with a dedicated Drive-app", "category": "Productivity", "publisher": { "name": "Powerhouse", "url": "https://www.powerhouse.inc/" }, "documentModels": [ { "id": "todo-list", "name": "TodoList" } ], "editors": [ { "id": "todo-list-editor", "name": "TodoList Editor", "documentTypes": ["todo-list"] } ], "apps": [ { "id": "todo-list-drive-explorer", "name": "TodoList drive-app", "driveEditor": "todo-list-drive-explorer" } ], "subgraphs": [], "importScripts": [] } ``` ### 3. Remove Unnecessary Default Components: - First, let's remove some default template files that we won't need for this specific demo. If you want to see what the default template looks like before removing files, you can run `ph connect` at any time. ```bash rm -rf editors/todo-list-drive-explorer/hooks rm -rf editors/todo-list-drive-explorer/components/FileItemsGrid.tsx rm -rf editors/todo-list-drive-explorer/components/FolderItemsGrid.tsx rm -rf editors/todo-list-drive-explorer/components/FolderTree.tsx ``` ### 4. Create custom components for your Drive-app: - Next, create the following files. These will define the data types for our todo-list items and provide the custom React components for our Drive-app.

Create `editors/todo-list-drive-explorer/types/todo.ts`
This file defines the TypeScript type `ToDoState`. It specifies the shape of todo-list document data within the Drive-app, combining the document's revision information with its global state. This ensures that our components work with a predictable and strongly-typed data structure. ```typescript import type { TodoListDocument } from "todo-tutorial/document-models/todo-list"; export type TodoState = { documentType: string; revision: { global: number; local: number; }; global: TodoListDocument["state"]["global"]; }; ```

Create `editors/todo-list-drive-explorer/components/ProgressBar.tsx`
This is a simple React component that renders a visual progress bar. It takes a `value` and `max` number to calculate the percentage of completed tasks. It also displays the percentage and has a special state for when there are no tasks. ```tsx import type { FC } from 'react'; interface ProgressBarProps { value: number; max: number; } export const ProgressBar: FC = ({ value, max }) => { if (max === 0) { return (

No tasks

); } const percentage = Math.min(100, (value / max) 100); return (

{Math.round(percentage)}%

); }; ```

Update `editors/todo-list-drive-explorer/components/DriveExplorer.tsx`
This is the main component of our Drive-app. It fetches all `powerhouse/todo-list` documents from the drive, displays them in a table with their progress, and allows a user to click on a document to open it in the `EditorContainer`. It also includes a button to create new documents. ```typescript type TodoState = { documentType: string; revision: { global: number; local: number; }; global: TodoListDocument["state"]["global"]; }; interface DriveExplorerProps { driveId: string; nodes: Node[]; onAddFolder: (name: string, parentFolder?: string) => void; onDeleteNode: (nodeId: string) => void; renameNode: (nodeId: string, name: string) => void; onCopyNode: (nodeId: string, targetName: string, parentId?: string) => void; context: DriveEditorContext; } export function DriveExplorer({ driveId, nodes, context, }: DriveExplorerProps) { const { getDocumentRevision } = context; const [activeDocumentId, setActiveDocumentId] = useState< string | undefined >(); const [openModal, setOpenModal] = useState(false); const selectedDocumentModel = useRef(null); const { addDocument, documentModels, useDriveDocumentStates } = useDriveContext(); const [state, fetchDocuments] = useDriveDocumentStates({ driveId }); useEffect(() => { fetchDocuments(driveId).catch(console.error); }, [activeDocumentId]); const { todoNodes } = useMemo(() => { return Object.keys(state).reduce( (acc, curr) => { const document = state[curr]; if (document.documentType === "powerhouse/todo-list") { acc.todoNodes[curr] = document as TodoState; } return acc; }, { todoNodes: {} as Record, }, ); }, [state]); const handleEditorClose = useCallback(() => { setActiveDocumentId(undefined); }, []); const onCreateDocument = useCallback( async (fileName: string) => { setOpenModal(false); const documentModel = selectedDocumentModel.current; if (!documentModel) return; const node = await addDocument( driveId, fileName, documentModel.documentModel.id, ); selectedDocumentModel.current = null; setActiveDocumentId(node.id); }, [addDocument, driveId], ); const onSelectDocumentModel = useCallback( (documentModel: DocumentModelModule) => { selectedDocumentModel.current = documentModel; setOpenModal(true); }, [], ); const onGetDocumentRevision = useCallback( (options?: GetDocumentOptions) => { if (!activeDocumentId) return; return getDocumentRevision?.(activeDocumentId, options); }, [getDocumentRevision, activeDocumentId], ); const filteredDocumentModels = documentModels; const fileNodes = nodes.filter((node) => node.kind === "file") as FileNode[]; // Get the active document info from nodes const activeDocument = activeDocumentId ? fileNodes.find((file) => file.id === activeDocumentId) : undefined; const documentModelModule = activeDocument ? context.getDocumentModelModule(activeDocument.documentType) : null; const editorModule = activeDocument ? context.getEditor(activeDocument.documentType) : null; return (
{/* Main Content /}
{activeDocument && documentModelModule && editorModule ? ( ) : ( <>
ToDos:

{Object.entries(todoNodes).map(([documentId, todoNode]) => ( ))}

Document ID Document Type Tasks Completed Progress

setActiveDocumentId(documentId)} className="text-blue-600 hover:text-blue-800 cursor-pointer" > {documentId}
{todoNode.documentType} {todoNode.global.stats.total} {todoNode.global.stats.checked}

{/ Create Document Section /} )}
{/ Create Document Modal /} setOpenModal(open)} open={openModal} />
); } ```

Update `editors/todo-list-drive-explorer/components/EditorContainer.tsx`
This component acts as a wrapper for the document editor. When a user selects a document in `DriveExplorer.tsx`, this component mounts the appropriate editor (`todo-list-editor` in this case) and provides it with the necessary context and properties to function. It also renders the `DocumentToolbar` which provides actions like closing, exporting, and viewing revision history. ```typescript useDriveContext, type User, type DriveEditorContext, } from "@powerhousedao/reactor-browser"; documentModelDocumentModelModule, type DocumentModelModule, type EditorContext, type EditorProps, type PHDocument, type EditorModule, type Operation, } from "document-model"; DocumentToolbar, RevisionHistory, DefaultEditorLoader, generateLargeTimeline, type TimelineItem, } from "@powerhousedao/design-system"; export interface EditorContainerProps { driveId: string; documentId: string; documentType: string; onClose: () => void; title: string; context: Omit & Pick; documentModelModule: DocumentModelModule; editorModule: EditorModule; } export const EditorContainer: React.FC = (props) => { const { driveId, documentId, documentType, onClose, title, context, documentModelModule, editorModule } = props; const [selectedTimelineItem, setSelectedTimelineItem] = useState(null); const [showRevisionHistory, setShowRevisionHistory] = useState(false); const { useDocumentEditorProps } = useDriveContext(); const user = context.user as User | undefined; const timelineItems = useTimelineItems(documentId); const { dispatch, error, document } = useDocumentEditorProps({ documentId, documentType, driveId, documentModelModule, user, }); const loadingContent = (

); if (!document) return loadingContent; const moduleWithComponent = editorModule as EditorModule; const EditorComponent = moduleWithComponent.Component; return showRevisionHistory ? ( setShowRevisionHistory(false)} /> ) : ( {}} /> ); }; ```
- In case you are getting stuck and want to verify your progress with the reference repository you can find the example repository of the [Todo Tutorial here](https://github.com/powerhouse-inc/todo-tutorial) ### 3. Run the application: - With the code for our Drive-app in place, it's time to see it in action. If you've been running Vetra Studio with `ph vetra --watch`, your Drive-app is already available. Otherwise, run Connect: ```bash ph connect ``` ## Up Next You've built a custom drive explorer. Next, style it with [CSS customization](/academy/Build/BuildingUserExperiences/CSSCustomization). --- ## CSS Customization for Connect Integration > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/CSSCustomization When your editor runs inside Connect, it's rendered within a specific container hierarchy. Understanding this structure allows you to customize your editor's appearance to match your application's design requirements. ## Understanding the Editor Container Hierarchy Connect wraps your editor component in two key containers that you can target for styling: ```
└── └──
└── ``` ### Container Details | Container ID | Default Classes | Data Attributes | Purpose | | ---------------------------- | ----------------- | ----------------------------------- | ----------------------------------------------------------- | | `#document-editor-container` | `flex-1` | `data-document-type` | Outermost wrapper, controls overall editor space allocation | | `#document-editor-context` | `relative h-full` | `data-editor`, `data-document-type` | Inner context, provides positioning context and full height | These containers are defined in Connect's source: - [`document-editor-container.tsx`](https://github.com/powerhouse-inc/ph-monorepo/blob/main/apps/connect/src/components/document-editor-container.tsx) (line 94) - [`editors.tsx`](https://github.com/powerhouse-inc/ph-monorepo/blob/main/apps/connect/src/components/editors.tsx) (line 173) ## Customizing Your Editor's Appearance ### Method 1: Inline Styles in Your Editor Component (Recommended) The simplest and most maintainable approach is to apply styles directly to your editor's root element. This keeps your styling self-contained within your editor. ```tsx export function Editor() { return (
{/ Your editor content /}
); } ``` TIP: Using `height: "100%"` ensures your editor fills the available vertical space within Connect's container hierarchy. ### Method 2: CSS File with Container Selectors For more complex customizations or when you need to override Connect's default container styles, you can target the container IDs directly in a CSS file: DANGER: Targeting container IDs directly will apply styles to ALL editors in your Connect application. For editor-specific styling, use [Method 3: Scoped Styling with Data Attributes](#method-3-scoped-styling-with-data-attributes) instead. ```css / editors/my-editor/editor.css / #document-editor-container { / Customize the outer container / background-color: #f8fafc; } #document-editor-context { / Customize the inner context / max-width: 1200px; margin: 0 auto; } / Scope styles to your editor within the context / #document-editor-context .my-editor-root { padding: 2rem; } ``` WARNING: Remember to import styles in your `styles.css` file rather than directly in `.tsx` files. Direct imports work in development but won't be included in production builds. ```css / styles.css / @import "./editors/my-editor/editor.css"; ``` ### Method 3: Scoped Styling with Data Attributes Connect adds `data-editor` and `data-document-type` attributes to editor containers, allowing you to scope CSS rules to specific editors without affecting others. ```css / Only applies to a specific editor / #document-editor-context[data-editor="document-editor-editor"] { background-color: #f0f9ff; } / Only applies to a specific document type / #document-editor-context[data-document-type="powerhouse/document-editor"] { max-width: 900px; margin: 0 auto; } / Combine both for precise targeting */ #document-editor-context[data-editor="document-editor-editor"][data-document-type="powerhouse/document-editor"] { padding: 1rem; } ``` #### Finding Your Editor ID The `data-editor` value comes from the `id` property in your editor module configuration: ```typescript // editors/my-editor/module.ts export const MyEditor: EditorModule = { config: { id: "my-custom-editor", // <-- This becomes the data-editor value documentTypes: ["my-org/my-document-model"], }, Component: MyEditorComponent, }; ``` #### Common Editor IDs | Editor ID | Document Type | Description | | ------------------------ | ---------------------------- | --------------- | | `document-editor-editor` | `powerhouse/document-editor` | Document Editor | | `vetra-drive-app` | `powerhouse/document-drive` | Drive Explorer | | `app-editor` | `powerhouse/app` | App Editor | TIP: You can inspect the `data-editor` and `data-document-type` attributes in your browser's developer tools when editing a document to find the exact values for your target editor. ## Reference Implementation: Vetra Drive App The Vetra Drive App provides a real-world example of CSS customization. Here's how it styles its editor wrapper: ```tsx // From: packages/vetra/editors/vetra-drive-app/editor.tsx

``` This example demonstrates: - `height: "100%"` - Ensures the editor fills the full container height - `bg-gray-50` - Applies a light gray background color - `p-6` - Adds consistent padding around the content - **`after:*` pseudo-element** - Creates a visual effect layer for transitions ## Common Use Cases ### Full-Height Editor with Scrollable Content When your editor needs a fixed header/toolbar with scrollable main content: ```tsx export function Editor() { return (

Document Title
{/* Toolbar buttons /}

{/ Scrollable content area /}

); } ``` ### Custom Background and Theming Apply custom backgrounds or gradients to match your application's theme: ```tsx export function Editor() { return (
{/ Themed content /}
); } ``` ### Centered Content with Max Width Constrain content width for better readability: ```tsx export function Editor() { return (

{/ Centered, width-constrained content /}

); } ``` ## Troubleshooting ### Editor Doesn't Fill Available Height Problem: Your editor content appears squished or doesn't use the full height. Solution: Ensure your root element has `height: "100%"` or uses flex utilities: ```tsx // Option 1: Inline style
// Option 2: Tailwind class
``` ### Styles Not Applied in Production Problem: Styles work in development but not in production builds. Solution: Move style imports from `.tsx` files to your `styles.css` file: ```css / styles.css - correct location for imports / @import "./editors/my-editor/editor.css"; ``` ### Z-Index Conflicts Problem: Overlays, modals, or dropdowns appear behind other elements. Solution: The `#document-editor-context` has `position: relative`. Use this as your positioning context: ```tsx
{/ Your content /}
{/ Positioned overlay /}

``` ### Content Overflows Container Problem: Content extends beyond the editor boundaries. Solution: Add overflow handling to your root element: ```tsx
{/ Scrollable when content overflows /}
// Or hide overflow
{/ Content is clipped /}
``` ## Further Reading - [Building Document Editors](/academy/Build/BuildingUserExperiences/BuildingDocumentEditors) - Fundamentals of editor development including basic styling - [Building a Drive Explorer](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) - Creating custom drive apps with styling --- ## Document Toolbar > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/DocumentTools/DocumentToolbar The `DocumentToolbar` renders a default set of document controls for common document actions: undo, redo, download, document name editing, revision history, opening in Switchboard, and closing the current document view. The toolbar can be customized by enabling or disabling built-in controls, replacing individual controls, adding custom controls to toolbar slots, replacing the toolbar containers, applying custom styles, or replacing the entire toolbar contents with `children`.

The Document Toolbar can be found at the top of any generic document.

## Basic usage ```tsx export function MyDocumentPage({ document }) { return ; } ``` When no `document` prop is provided, the toolbar falls back to the currently selected document. ```tsx ``` ## Built-in controls The default toolbar includes these controls: ```ts ["undo", "redo", "download", "name", "history", "switchboard", "close"]; ``` The controls are arranged into three slots: ```ts { first: ["undo", "redo", "download"], second: ["name"], third: ["history", "switchboard", "close"], } ``` ## Disabling controls Use `disabledControls` to remove specific built-in controls from the default toolbar. ```tsx ``` ## Enabling only specific controls Use `enabledControls` to render only a subset of the built-in controls. ```tsx ``` ## Combining enabled and disabled controls A control renders only when it is included in `enabledControls` and absent from `disabledControls`. When a control appears in both lists, `disabledControls` takes precedence. ```tsx ``` In this example, only `switchboard` and `close` render. ## Adding a custom control to a slot Use `customControls` to add controls to a specific toolbar slot. Custom controls receive the current document when available. ```tsx ( ), }, }} /> ``` ## Adding a custom control at the end of a slot By default, custom controls render at the start of their slot. Use `position: "end"` to render a custom control after the built-in controls in that slot. ```tsx ( ), }, }} /> ``` ## Adding multiple custom controls to a slot A slot can receive a list of custom controls. Each item needs a `key`. ```tsx ( ), }, { key: "custom-two", position: "end", component: ({ document }) => ( ), }, ], }} /> ``` ## Replacing the toolbar container Use `toolbarContainer` to replace the outer toolbar container. The custom toolbar container receives the toolbar children and the resolved `toolbarClassName`. ```tsx (
{children}
)} /> ``` ## Replacing the controls container Use `controlsContainer` to replace the container used for each toolbar slot. The custom controls container receives the slot children and the resolved `controlsContainerClassName`. ```tsx (
{children}
)} /> ``` ## Replacing a built-in control Use `componentOverrides` to replace individual built-in controls while keeping the default toolbar structure. This is useful when you want to reuse the built-in control behavior or styling but change part of the rendering or click behavior. ```tsx ( alert(props.document?.header.name)} > Download?? ), }} />; ``` The `name` control can also be replaced through `componentOverrides`. ```tsx ( ), }} /> ``` ## Replacing the entire toolbar contents Pass `children` when you want complete control over the toolbar contents. When `children` is provided, the built-in controls are not rendered. ```tsx <DocumentToolbar document={document}> <div>I've totally overridden the whole thing</div> </DocumentToolbar> ``` Props such as `enabledControls`, `disabledControls`, `customControls`, `componentOverrides`, `controlsContainer`, and `controlsContainerClassName` are not used in this mode. The props are typed so that the `children` mode is mutually exclusive with the default-toolbar customization props. ## Custom styles Use `toolbarClassName` to add classes to the outer toolbar container. Use `controlsContainerClassName` to add classes to each controls container. The built-in toolbar components use `tailwind-merge`, so compatible Tailwind classes passed through these props can override default classes. ```tsx <DocumentToolbar document={document} toolbarClassName="border-none bg-green-100" controlsContainerClassName="rounded-lg border border-green-300 p-2" /> ``` ## Custom control component shape Custom controls should match `ToolbarControlComponent`. ```tsx const MyControl: ToolbarControlComponent = ({ document }) => { return <button>{document?.header.name}</button>; }; ``` ## Toolbar button props The built-in toolbar button controls accept `ToolbarButtonProps`. Each toolbar button accepts: ```ts { document?: PHDocument; children?: ReactNode; className?: string; onClick?: (document?: PHDocument) => void; } ``` Providing `children` replaces the default button contents. Providing `onClick` replaces the default button behavior. ```tsx <DocumentToolbar document={document}> <ToolbarDownloadButton document={document}> Export </ToolbarDownloadButton> </DocumentToolbar> <ToolbarHistoryButton document={document} onClick={(document) => { console.log("Custom history action", document?.header.id); }} /> ``` ## Exported components ```ts DocumentToolbar; ToolbarButton; ToolbarUndoButton; ToolbarRedoButton; ToolbarDownloadButton; ToolbarSwitchboardButton; ToolbarHistoryButton; ToolbarCloseButton; ToolbarName; ToolbarInput; ToolbarContainer; ToolbarControlsContainer; ``` The individual toolbar controls are exported so they can be reused when building custom toolbar layouts or custom control components. ## Exported types ```ts DocumentToolbarProps; DocumentToolbarWithChildrenProps; DocumentToolbarWithCustomControlsProps; DocumentToolbarControlName; ToolbarButtonProps; ToolbarButtonClickHandler; ToolbarControlComponent; ToolbarControlComponents; ContainerComponent; ControlSlot; ControlPosition; CustomToolbarControl; CustomToolbarControlList; CustomToolbarControls; ``` ## Notes - `DocumentToolbar` falls back to the currently selected document when `document` is omitted. - Built-in undo and redo buttons automatically disable themselves when the corresponding action is unavailable. - The document name control supports inline renaming. - `children` mode replaces the toolbar contents completely. - `disabledControls` takes precedence over `enabledControls`. --- ## Operations history > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/DocumentTools/OperationHistory ## What is a document model? A document model in Powerhouse is the core unit for managing business data. Each document (such as an invoice, contributor agreement, or scope of work) is created from a specific document model, which defines: - State schema: What data the document contains - Operations: What actions can modify that document ## What is an operations history? Every time a user edits a document, they do so by submitting a document operation or a 'command' in CQRS (e.g., `ADD_LINE_ITEM`, `UPDATE_RECIPIENT`). These operations are: - Appended to the document's history - Immutable (you never overwrite; you always append) - Replayable — the current document state is the result of applying all past operations in sequence This design is based on event sourcing principles. ## Why use an operations history? - Auditability: Inspect every change ever made to a document. - Transparency: Contributors see what others have done. - Versioning: Revert to any prior state or resolve conflicts using branching and merging. - Interoperability: Operations are just data—they can be signed, stored on-chain, or synchronized across systems. ## Example: Invoice document Suppose you're editing a `powerhouse/invoice` document. Its operations history might look like this: ```plaintext SET_RECIPIENT(name: "Acme Corp") ADD_LINE_ITEM(description: "Design Work", unitCost: $500) UPDATE_DUE_DATE(date: "2025-06-01") ``` The document's state at any time is the result of running those operations in order. ## Visualizing the operations history ### Revision list and details In Connect the Powerhouse UI displays a chronologic list of all applied modifications to the document, each with a unique event ID, state hash, and commit message. You can inspect each revision for signatures and errors. ![Revision History List](../docs/docs/images/revision-history-list.png) ### Viewing revision hashes and event IDs Hovering over a revision reveals its event ID and state hash, providing traceability for every change. ![Revision Hash Popup](../docs/docs/images/revision-hash-popup.png) ### Signature verification Clicking the signature badge shows signature details, including signer address, hash, and verification status. This ensures every operation is cryptographically auditable. Read more about how we are using [Renown](/academy/Build/BuildingUserExperiences/Authorization/RenownAuthenticationFlow) for authentication & verification of signer data. ![Signature Details Popup](../docs/docs/images/signature-details-popup.png) ### Viewing committer addresses You can also view the committer's address for each revision, supporting full transparency and accountability. ![Committer Address Popup](../docs/docs/images/committer-address-popup.png) WARNING: This remainder of this documentation is still being written and may be incomplete. ## Replay, branch, and merge (under development) - Replay: When you load a document, the system replays all operations to build its state. - Branch: Create a parallel version of the document to test changes or handle conflicts. - Merge: Combine branches intelligently based on operations, not just raw field values. --- ## Revision history timeline > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/DocumentTools/RevisionHistoryTimeline The history 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. ## How to enable 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-list"], }; ``` This setting enables the timeline button in the document toolbar. WARNING: The revision history timeline will only become visible once your document model has some operations or 'history'. Add a few to-do's or some data in the model you are working on and the revision history timeline button in the Document Toolbar will be activated. Click the button to see the timeline expand and see the first history 'candle' appear. <figure className="image-container"> <img src={require("./images/revision-history-timeline.png").default} alt="revision history timeline" /> <figcaption>Once your document has a few operations added to it's history the revision history timeline gets activated.</figcaption> </figure> ## How to implement the timeline feature ### Default Drive-app When using the default Drive-app 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-app For custom Drive-apps, 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 ``` 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 // ... other props /> ``` 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. --- ## Inspector Modal > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/DocumentTools/InspectorModal The Inspector Modal is a development and debugging tool in Connect that provides visibility into the internal state of your application. It allows you to inspect the local database and monitor sync operations with remote servers. The Inspector Modal has two tabs: - Database - Explore tables and data in the local PGlite database - Remotes - View sync remotes and their channel states (inbox, outbox, dead letter) ## Accessing the Inspector Modal The Inspector is available to every Connect user through the Settings menu: 1. Click the Settings (⚙️) button in the Connect sidebar footer 2. Select the About tab 3. Click the Open Inspector button 4. The Inspector Modal opens with two tabs: Database and Remotes ## Database Explorer The Database tab allows you to inspect the local PGlite database that Connect uses to store documents and application data. <figure className="image-container"> <img src={require("./images/database-explorer.png").default} alt="Database Explorer interface" /> <figcaption>The Database Explorer showing the schema tree and table data view.</figcaption> </figure> ### Understanding the Interface The Database Explorer is divided into two panels: - Left panel (Schema Tree): Shows all tables in the `public` schema with their column information - Right panel (Table View): Displays the data for the selected table with pagination and sorting ### Browsing Tables 1. In the left sidebar, you'll see the schema tree with all available tables 2. Click on a table name to expand it and view its columns 3. Each column shows: - Column name - Data type (e.g., `varchar`, `boolean`, `integer`) - Whether the column is nullable <figure className="image-container"> <img src={require("./images/schema-tree.png").default} alt="Schema tree with expanded table" /> <figcaption>The schema tree showing tables and their column details.</figcaption> </figure> ### Viewing Table Data 1. Select a table from the schema tree to load its data in the right panel 2. The table view displays all rows with pagination controls at the bottom 3. Use the pagination controls to navigate through large datasets: - First page / Previous page - Page numbers - Next page / Last page 4. Click any column header to sort the data: - Click once for ascending order - Click again for descending order <figure className="image-container"> <img src={require("./images/table-view-pagination.png").default} alt="Table view with pagination" /> <figcaption>The table data view with pagination controls.</figcaption> </figure> ### Exporting the Database To create a backup of your local database: 1. Click the Export DB button in the sidebar 2. A complete SQL dump file will be downloaded to your computer 3. The file is named `database-export-{timestamp}.sql` This export contains the full database schema and all data, which can be useful for debugging or creating backups. ### Importing a Database WARNING: Importing a database will replace ALL existing data in your local Connect instance. This action cannot be undone. To import a database: 1. Click the Import DB button in the sidebar 2. Select a `.sql` or `.txt` file containing valid SQL 3. Confirm the replacement in the dialog that appears 4. The database will be cleared and replaced with the imported data 5. The schema tree will refresh automatically to show the new tables ## Remotes Explorer The Remotes tab allows you to inspect sync remotes and their channel states. This is useful for debugging synchronization issues between your local Connect instance and remote servers. <figure className="image-container"> <img src={require("./images/remotes-explorer.png").default} alt="Remotes Explorer interface" /> <figcaption>The Remotes Explorer showing configured sync remotes.</figcaption> </figure> ### Understanding Remotes Sync remotes are connections between your local Connect instance and remote reactors (servers). When you add a remote drive or sync with a cloud service, a remote is created to manage the bidirectional synchronization of document operations. ### Viewing Remote List The Remotes tab displays a table with all configured sync remotes: | Column | Description | | ------------- | -------------------------------------------------------- | | ID | Unique identifier for the remote (truncated) | | Name | Human-readable name of the remote | | Collection ID | The collection this remote is associated with | | Filter | Configuration showing branch, document, or scope filters | | Channel | "View" button to inspect the remote's channel state | ### Inspecting Remote Channels Click the View button on any remote to open the Channel Inspector. The channel shows three mailboxes that track sync operations: <figure className="image-container"> <img src={require("./images/channel-inspector.png").default} alt="Channel Inspector with mailboxes" /> <figcaption>The Channel Inspector showing Inbox, Outbox, and Dead Letter mailboxes.</figcaption> </figure> #### Inbox Operations received from the remote server: | Column | Description | | ----------- | ------------------------------------------------------ | | ID | Operation identifier | | Document ID | The document this operation affects | | Branch | The document branch (usually "main") | | Status | Current status: Pending (⏳), Applied (✅), Error (❌) | | Ops Count | Number of operations in this batch | #### Outbox Operations waiting to be sent to the remote server. Shows the same columns as Inbox. #### Dead Letter Operations that failed to sync with error information: | Column | Description | | ----------- | ------------------------------------ | | ID | Operation identifier | | Document ID | The document this operation affects | | Branch | The document branch | | Error | Error message explaining the failure | ## Use Cases The Inspector Modal is helpful for: - Debugging sync issues: Check the Remotes tab to see if operations are stuck in the inbox/outbox or if there are errors in the dead letter queue - Verifying data integrity: Browse tables to ensure documents are stored correctly - Exporting data for backup: Create SQL dumps of your local database - Understanding data flow: See how operations move between local and remote systems - Troubleshooting: Inspect table schemas and data when debugging application issues --- ## Renown authentication flow > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/Authorization/RenownAuthenticationFlow The Renown login flow leverages decentralized identity (DID) creation and the Ceramic network for credential storage and verification, ensuring secure and verifiable actions within decentralized organizations. Below is a detailed breakdown of the process, aimed at developers integrating the Renown, Connect, and Switchboard components. ### Renown in the decentralized workplace Renown provides a decentralized identity and reputation hub, where users connect their Ethereum address, creating a Decentralized Identifier (DID) tied to their wallet. #### Why an integrated identity solution? Renown is designed to address the challenge of trust within DAOs, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities. Over time, contributors can share their pseudonymous profiles with other organizations as cryptographic resumes, helping to secure new opportunities while maintaining privacy. ### Detailed login flow #### 1. User login via wallet connection - The user starts by logging into Renown using their Ethereum address. This is done by signing a message with their wallet. - The Ethereum key is used to create a DID (Decentralized Identifier), which uniquely represents the user without exposing their personal identity. <figure className="image-container"> <img src={require("./images/ConnectAddress.png").default} alt="Connect Address" /> <figcaption>Connecting your Ethereum address to generate Decentralized Identifier with Renown.</figcaption> </figure> #### 2. DID creation - A Decentralized Identifier (DID) is created based on the user's Ethereum key. The DID follows a specific format: `did:example:123456789abcdefghijk` - This DID acts as the user's digital identifier across decentralized systems. #### 3. Credential generation - A credential is generated, allowing the DID to sign operations on behalf of the user. This credential is stored on a Powerhouse-hosted identity node. - The identity node ensures that the credentials are securely stored and verifiable across the network. Credentials include the user's signing permissions and are linked to the DID. - Powerhouse aims to decentralize this identity reactor over time while maintaining an efficient hub for using your decentralized identity and reputation to explore different organizations. #### 4. Operation signing with Connect - Connect uses the newly created DID to sign operations performed by the user. For example, when a document or transaction is edited in Connect, the operation is signed with the user's DID. - This ensures that every action taken within the Connect system is linked to the user's decentralized identity, maintaining transparency and accountability. <figure className="image-container"> <img src={require("./images/OperationsHistory.png").default} alt="Renown Login" /> <figcaption>Your DID is used to sign operations performed by the user.</figcaption> </figure> #### 5. Switchboard verification - Once an operation is signed by the DID through Connect, it is sent to Switchboard for verification. - Switchboard verifies whether the DID has a valid credential stored on the Powerhouse identity node and if the DID was indeed the one that signed the operation. - The request includes critical metadata such as the user's Ethereum address, the DID, the signed operation, and other parameters required for validation. ```json { "signerAddress": "0x1234...", "hash": "did:key:2be4x...", "signatureBytes": "Xmqy8FNz...", "isVerified": true } ``` #### 6. Operation validation and execution - After Switchboard validates the operation, it ensures the operation context is accurate and the credentials match the signer. - The operation is then either approved or rejected based on the verification results. - Approved operations are processed, and changes made within the Connect system are synchronized across the relevant nodes. INFO: Key Components used during login-flow - Renown: Manages user identities via DID creation and Ethereum wallet integration. - Powerhouse Identity Node: Hosts user credentials and enables verification. Powerhouse is working towards decentralizing this identity reactor over time. - Connect: The interface for users to perform operations. It uses the DID for signing operations. - Switchboard: Responsible for verifying credentials and operation signatures to ensure authenticity. ::: This flow ensures that all actions within the Powerhouse ecosystem are secure, transparent, and verifiable, promoting trust in a pseudonymous contributor environment. --- ## Document Permission System > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/Authorization/DocumentPermissions WARNING: This documentation is still being written and may be incomplete. The feature is not yet available on production. ## Introduction The Reactor API is the API interface to a Powerhouse Reactor—a storage node responsible for storing documents, resolving conflicts, and verifying document event histories. Reactors can be configured for local storage, cloud storage, or decentralized storage networks. Within a Reactor, data is organized hierarchically: - Drives: Logical containers for organizing collections of documents (similar to a repository) - Folders: Subdirectories within drives for organizing documents - Documents: Individual Powerhouse documents based on document models (e.g., todo lists, budgets, specifications) ### Why Document Permissions? The Reactor API implements a two-layer authorization system: | Component | System | Purpose | Scope | | ----------------------- | ---------------------------------------------------------- | ---------------------------------------------------- | ------------ | | Auth & Admin | [Authentication & Admin Access](../docs/docs/04-Authorization.md) | Controls authentication and supreme admin access | Reactor-wide | | Protection & Grants | Document Permission System (this guide) | Controls access to specific documents/folders/drives | Per-document | This document permission system allows you to implement fine-grained access control—for example, you might want certain team members to have write access to a "Marketing" drive while only having read access to a "Finance" drive, even though they're both authenticated users of your Reactor. INFO: Before using document permissions, you must configure [authentication](../docs/docs/04-Authorization.md) with `AUTH_ENABLED=true`. Users need a valid authentication token to access the Reactor API. Supreme admins (listed in `ADMINS`) bypass all permission checks. ## Overview The document permission system provides: - Document-level permissions: Grant READ, WRITE, or ADMIN access to specific documents - Permission inheritance: Permissions flow down from parent documents (drives → folders → documents) - Group-based access: Organize users into groups and assign permissions to groups - Operation-level permissions: Restrict specific operations to certain users or groups ## Prerequisites Before using document permissions, you need: 1. A running Reactor: Start a local Reactor instance 2. Renown authentication: Users must authenticate via `ph login` via the CLI 3. AUTH_ENABLED=true: Global authentication must be enabled 4. DOCUMENT_PERMISSIONS_ENABLED=true: Document permissions feature flag must be set ### Starting the Reactor API The Reactor API is started when you run a local Reactor instance. You have several options: Option 1: Run Reactor directly ```bash # Start a local Reactor on port 4001 (default) ph reactor # Or specify a custom port ph reactor --port 5000 ``` Option 2: Run both Connect and Reactor together ```bash # In one terminal: start the Reactor ph reactor # In another terminal: start Connect Studio ph connect ``` All options will start a Reactor API instance, typically accessible at: - GraphQL API: `http://localhost:4001/graphql` - Drive endpoint: `http://localhost:4001/d/powerhouse` ### Accessing Remote/Production Reactors For production or remote Reactor instances (e.g., hosted on Vetra): - The Reactor is already running on a remote server - Access it via the remote URL (e.g., `https://vetra.example.com/d/your-drive-id`) - You still need to authenticate with `ph login` and obtain an access token - Include your bearer token in API requests to the remote Reactor's GraphQL endpoint via an header of the type 'Authorization' ### Configuring Authentication Once the Reactor is running, enable authentication in your `powerhouse.config.json` or via environment variables: ```bash # Environment variables AUTH_ENABLED=true DOCUMENT_PERMISSIONS_ENABLED=true ``` Or in `powerhouse.config.json`: ```json { "auth": { "enabled": true } } ``` After configuration changes, restart the Reactor for settings to take effect. ## Quick Start Here's the complete flow to set up and use document permissions: 1. Start the Reactor with auth enabled: ```bash # Set environment variables export AUTH_ENABLED=true export DOCUMENT_PERMISSIONS_ENABLED=true # Start the Reactor ph reactor ``` 2. Authenticate as a user: ```bash # Login via Renown ph login # Generate an access token ph access-token --expiry 7d ``` 3. Grant yourself admin access to a drive (via GraphQL or programmatically when creating the drive) 4. Grant permissions to other users or groups using the GraphQL mutations described below ## Permission Levels The system defines three permission levels for documents: | Level | Description | Capabilities | | ------- | ----------- | -------------------------------------------- | | `READ` | View access | Can fetch and read the document | | `WRITE` | Edit access | Can push updates and modify the document | | `ADMIN` | Full access | Can manage document permissions and settings | Permission hierarchy: Higher permission levels include all capabilities of lower levels (ADMIN includes WRITE and READ, WRITE includes READ). TIP: - READ: A team member can view a budget document but cannot make changes - WRITE: A contributor can edit a specification document and push updates - ADMIN: A project lead can modify who has access to the entire project drive ## How It Works ### Permission Resolution When a user attempts to access a document, the Reactor API checks permissions in this order: 1. [Authentication check](../docs/docs/04-Authorization.md): First, verify the user is authenticated and check if they are a supreme admin (`ADMINS`). If `AUTH_ENABLED=false`, access is granted to everyone. Supreme admins bypass all further checks 2. Direct user permission: Check if the user has explicit permission on the document 3. Group permission: Check if the user belongs to a group with permission on the document 4. Parent inheritance: Recursively check parent documents (folder → drive) Example of permission inheritance: ``` Drive (ADMIN permission for user Alice) └── Folder A (inherits ADMIN from Drive) └── Document 1 (inherits ADMIN from Folder A) └── Document 2 (inherits ADMIN from Folder A) └── Folder B (READ permission granted explicitly to Alice) └── Document 3 (inherits READ from Folder B) ``` In this example: - Alice has ADMIN on the Drive, so she inherits ADMIN on Folder A and its documents - Alice was explicitly granted READ on Folder B, so Document 3 only has READ access - Without explicitly setting permissions on Folder B, all folders would inherit ADMIN from the Drive ### Database Schema The Reactor API stores permission data in a relational database using six tables: | Table | Purpose | | -------------------------- | -------------------------------------------------------------------------- | | `DocumentPermission` | Direct user-document permissions (e.g., "Alice has WRITE on Document X") | | `Group` | Group definitions (e.g., "Engineering Team") | | `UserGroup` | User-group memberships (e.g., "Alice is in Engineering Team") | | `DocumentGroupPermission` | Group-document permissions (e.g., "Engineering Team has READ on Drive Y") | | `OperationUserPermission` | User-operation permissions (e.g., "Bob can execute DELETE_NODE") | | `OperationGroupPermission` | Group-operation permissions (e.g., "Admins group can execute DELETE_NODE") | INFO: These tables are automatically created by database migrations when you enable `DOCUMENT_PERMISSIONS_ENABLED=true`. You don't need to create them manually. <details> <summary><strong>Useful Queries</strong></summary> #### Get document access info ```graphql query GetDocumentAccess($documentId: String!) { documentAccess(documentId: $documentId) { documentId groupPermissions { documentId groupId group { id name description members } permission grantedBy } permissions { documentId userAddress permission } } } ``` #### Get current user's document permissions ```graphql query MyDocuments { userDocumentPermissions { documentId permission grantedBy createdAt } } ``` #### List all groups ```graphql query ListGroups { groups { id name description members } } ``` #### Check operation permission ```graphql query CanExecute($documentId: String!, $operation: String!) { canExecuteOperation(documentId: $documentId, operationType: $operation) } ``` #### Get group by ID ```graphql query GetGroup($id: Int!) { group(id: $id) { id name description members createdAt updatedAt } } ``` #### Get user groups ```graphql query GetUserGroups($userAddress: String!) { userGroups(userAddress: $userAddress) { id name description members } } ``` #### Get operation permissions ```graphql query GetOperationPermissions($documentId: String!, $operationType: String!) { operationPermissions(documentId: $documentId, operationType: $operationType) { documentId operationType userPermissions { documentId operationType userAddress grantedBy createdAt } groupPermissions { documentId operationType groupId group { id name } grantedBy createdAt } } } ``` #### Document Drive Operation Types For document drives specifically, the following operation permissions are available: - `ADD_FILE` - Create new files within the drive - `ADD_FOLDER` - Create new folders within the drive - `DELETE_NODE` - Delete files or folders within the drive - `UPDATE_FILE` - Modify existing files within the drive - `UPDATE_NODE` - Update properties of files or folders within the drive (including renaming documents) - `COPY_NODE` - Copy files or folders within the drive - `MOVE_NODE` - Move files or folders within the drive INFO: These operation permissions provide fine-grained control over specific actions within a document drive, separate from the general document permission levels (READ, WRITE, ADMIN). Note that renaming a document is not part of the WRITE permission on the document itself—it's an `UPDATE_NODE` operation on the drive document. If you need to set operation permissions for documents with different document models, familiarize yourself with the available operations of the installed document model package. </details> <details> <summary><strong>Useful Mutations</strong></summary> ### Document Permissions #### Grant document permission to user ```graphql mutation GrantDocumentPermission( $documentId: String! $userAddress: String! $permission: DocumentPermissionLevel! ) { grantDocumentPermission( documentId: $documentId userAddress: $userAddress permission: $permission ) { documentId userAddress permission grantedBy createdAt updatedAt } } ``` #### Revoke document permission from user ```graphql mutation RevokeDocumentPermission($documentId: String!, $userAddress: String!) { revokeDocumentPermission(documentId: $documentId, userAddress: $userAddress) } ``` ### Group Management #### Create group ```graphql mutation CreateGroup($name: String!, $description: String) { createGroup(name: $name, description: $description) { id name description createdAt updatedAt members } } ``` #### Delete group ```graphql mutation DeleteGroup($id: Int!) { deleteGroup(id: $id) } ``` #### Add user to group ```graphql mutation AddUserToGroup($userAddress: String!, $groupId: Int!) { addUserToGroup(userAddress: $userAddress, groupId: $groupId) } ``` #### Remove user from group ```graphql mutation RemoveUserFromGroup($userAddress: String!, $groupId: Int!) { removeUserFromGroup(userAddress: $userAddress, groupId: $groupId) } ``` ### Group Permissions #### Grant group permission ```graphql mutation GrantGroupPermission( $documentId: String! $groupId: Int! $permission: DocumentPermissionLevel! ) { grantGroupPermission( documentId: $documentId groupId: $groupId permission: $permission ) { documentId groupId group { id name } permission grantedBy createdAt updatedAt } } ``` #### Revoke group permission ```graphql mutation RevokeGroupPermission($documentId: String!, $groupId: Int!) { revokeGroupPermission(documentId: $documentId, groupId: $groupId) } ``` ### Operation Permissions #### Grant operation permission to user ```graphql mutation GrantOperationPermission( $documentId: String! $operationType: String! $userAddress: String! ) { grantOperationPermission( documentId: $documentId operationType: $operationType userAddress: $userAddress ) { documentId operationType userAddress grantedBy createdAt } } ``` #### Revoke operation permission from user ```graphql mutation RevokeOperationPermission( $documentId: String! $operationType: String! $userAddress: String! ) { revokeOperationPermission( documentId: $documentId operationType: $operationType userAddress: $userAddress ) } ``` #### Grant group operation permission ```graphql mutation GrantGroupOperationPermission( $documentId: String! $operationType: String! $groupId: Int! ) { grantGroupOperationPermission( documentId: $documentId operationType: $operationType groupId: $groupId ) { documentId operationType groupId group { id name } grantedBy createdAt } } ``` #### Revoke group operation permission ```graphql mutation RevokeGroupOperationPermission( $documentId: String! $operationType: String! $groupId: Int! ) { revokeGroupOperationPermission( documentId: $documentId operationType: $operationType groupId: $groupId ) } ``` <details> <summary><strong>Document Management</strong></summary> #### Create document ```graphql mutation CreateDocument($document: JSONObject!, $parentIdentifier: String) { createDocument(document: $document, parentIdentifier: $parentIdentifier) { id name documentType state createdAtUtcIso lastModifiedAtUtcIso parentId } } ``` #### Create empty document ```graphql mutation CreateEmptyDocument( $documentType: String! $parentIdentifier: String ) { createEmptyDocument( documentType: $documentType parentIdentifier: $parentIdentifier ) { id name documentType state createdAtUtcIso lastModifiedAtUtcIso parentId } } ``` #### Mutate document ```graphql mutation MutateDocument( $documentIdentifier: String! $actions: [JSONObject!]! $view: ViewFilterInput ) { mutateDocument( documentIdentifier: $documentIdentifier actions: $actions view: $view ) { id name documentType state revisionsList { scope revision } lastModifiedAtUtcIso } } ``` #### Rename document ```graphql mutation RenameDocument( $documentIdentifier: String! $name: String! $branch: String ) { renameDocument( documentIdentifier: $documentIdentifier name: $name branch: $branch ) { id name documentType lastModifiedAtUtcIso parentId } } ``` #### Delete document ```graphql mutation DeleteDocument($identifier: String!, $propagate: PropagationMode) { deleteDocument(identifier: $identifier, propagate: $propagate) } ``` </details> <details> <summary><strong>Drive Management</strong></summary> #### Add drive ```graphql mutation AddDrive( $name: String! $icon: String $id: String $slug: String $preferredEditor: String ) { addDrive( name: $name icon: $icon id: $id slug: $slug preferredEditor: $preferredEditor ) { id slug name icon preferredEditor } } ``` #### Delete drive ```graphql mutation DeleteDrive($id: String!) { deleteDrive(id: $id) } ``` #### Set drive icon ```graphql mutation SetDriveIcon($id: String!, $icon: String!) { setDriveIcon(id: $id, icon: $icon) } ``` #### Set drive name ```graphql mutation SetDriveName($id: String!, $name: String!) { setDriveName(id: $id, name: $name) } ``` </details> </details> ## GraphQL API The Reactor API exposes a GraphQL interface for all operations. When `DOCUMENT_PERMISSIONS_ENABLED=true`, an Auth subgraph is registered that adds permission-related queries and mutations to the API. TIP: All GraphQL operations below require: 1. A valid bearer token from `ph access-token` 2. The token included in the `Authorization` header followed by 'Bearer `<token>`' 3. The Reactor API running with both `AUTH_ENABLED=true` and `DOCUMENT_PERMISSIONS_ENABLED=true` as variables ## Configuration You can configure the Reactor API using either environment variables or a `powerhouse.config.json` file. Environment variables take precedence over the config file. ### Environment Variables ```bash # Enable authentication (required for document permissions) AUTH_ENABLED=true # Enable document permissions feature (requires AUTH_ENABLED=true) DOCUMENT_PERMISSIONS_ENABLED=true # Supreme admin addresses (bypass all permission checks) # These users are Reactor-wide administrators ADMINS="0x123...,0x456..." # Make all new documents protected by default (requires explicit grants for access) DEFAULT_PROTECTION=true ``` ### powerhouse.config.json Alternatively, configure authorization in your `powerhouse.config.json` file: ```json { "auth": { "enabled": true, "admins": ["0x123...", "0x456..."] } } ``` INFO: - [Authentication & Admin Access](../docs/docs/04-Authorization.md) (`AUTH_ENABLED`, `ADMINS`): Controls authentication and supreme admin bypass - Document protection: Determines whether a document requires explicit grants (configurable via `DEFAULT_PROTECTION` or per-document) - Document permissions (this guide): Manages fine-grained READ/WRITE/ADMIN grants on specific documents Users must be authenticated before document permissions are evaluated. Supreme admins (`ADMINS`) bypass all permission checks. ## Usage Examples: Company Document Access & Permissions This section provides practical examples for common permission management scenarios. These examples assume you have: - A running Reactor API with `AUTH_ENABLED=true` and `DOCUMENT_PERMISSIONS_ENABLED=true` - A valid bearer token from `ph access-token` - The Ethereum address of users you want to grant permissions to <details> <summary><strong>Complete Scenario: Company Document Access & Permissions</strong></summary> This walkthrough demonstrates setting up document access for a company with different departments and roles. We'll create a "Finance Team" group, add team members, create a confidential finance drive, and configure granular permissions for sensitive financial documents. This scenario demonstrates advanced authorization patterns for managing contributor access levels to a shared finances todo list document, focusing on role-based access control and operation-level permissions using the @powerhousedao/todo-demo package. To get access to this subgraph yourself make sure to install the package in your project with `ph install @powerhousedao/todo-demo` <details> <summary><strong>Todo Document Schema Reference</strong></summary> ```graphql type TodoList implements IDocument { id: String! name: String! documentType: String! operations(skip: Int, first: Int): [Operation!]! revision: Int! createdAtUtcIso: DateTime! lastModifiedAtUtcIso: DateTime! initialState: TodoList_TodoListState! state: TodoList_TodoListState! stateJSON: JSONObject } """ Module: Todos """ input TodoList_AddTodoItemInput { text: String! } input TodoList_DeleteTodoItemInput { id: OID! } type TodoList_TodoItem { id: OID! text: String! checked: Boolean! } type TodoList_TodoListState { items: [TodoList_TodoItem!]! } input TodoList_UpdateTodoItemInput { id: OID! text: String checked: Boolean } """ Queries: TodoList Document """ type TodoListQueries { getDocument(docId: PHID!, driveId: PHID): TodoList getDocuments(driveId: String!): [TodoList!] } ``` </details> ### Step 1: Start the Reactor with Authentication We have 3 options to configure authorization rules: - Environment variables - `powerhouse.config.json` file - CLI command during local development For this example, we'll use the CLI approach: ```bash AUTH_ENABLED=true DOCUMENT_PERMISSIONS_ENABLED=true ADMINS=0x1234...abcd ph switchboard ``` Expected CLI output: ``` [switchboard] [connect-crypto] Switchboard identity initialized: did:key:zDnaepECmgs6RCDdjVo2RTYyPxoW5ZC4hN4iHrHH9Su9cXdM1 [reactor-api] [server] Setting up Auth middleware [reactor-api] [server] Document permission migrations completed [reactor-api] [server] Document permission service initialized ``` ✅ Authorization and document permissions have been initialized successfully. ### Step 2: Authenticate and Get Access Token Now authenticate and generate a bearer token for API requests: ```bash # Authenticate with your admin wallet ph login # Generate access token (valid for 7 days) ph access-token --expiry 7d ``` Copy the access token and include it in your GraphQL requests as: `Authorization: Bearer <your-token>` ### Step 3: Create the Finance Team Group Mutation: ```graphql mutation CreateGroup($name: String!) { createGroup(name: $name) { name id } } ``` Variables: ```json { "name": "finance-team" } ``` Expected Result: ```json { "data": { "createGroup": { "name": "finance-team", "id": 1 } } } ``` ### Step 4: Add Finance Team Members Add Finance Manager (Alice): Mutation: ```graphql mutation AddUserToGroup($userAddress: String!, $groupId: Int!) { addUserToGroup(userAddress: $userAddress, groupId: $groupId) } ``` Variables: ```json { "userAddress": "0xalice...finance", "groupId": 1 } ``` Expected Result: ```json { "data": { "addUserToGroup": true } } ``` Add Financial Analyst (Bob): Use the same mutation with different variables: Variables: ```json { "userAddress": "0xbob...analyst", "groupId": 1 } ``` ### Step 5: Create a Finance Drive Mutation: ```graphql mutation AddDrive($name: String!, $addDriveId: String, $slug: String) { addDrive(name: $name, id: $addDriveId, slug: $slug) { id name slug } } ``` Variables: ```json { "name": "finance-documents", "addDriveId": null, "slug": null } ``` Expected Result: ```json { "data": { "addDrive": { "id": "drive-uuid-1234-5678-abcd", "name": "finance-documents", "slug": "finance-documents" } } } ``` 📝 Note: Copy the returned `id` for the next steps. ### Step 6: Grant Finance Team Write Access to the Drive Mutation: ```graphql mutation GrantGroupPermission( $documentId: String! $groupId: Int! $permission: DocumentPermissionLevel! ) { grantGroupPermission( documentId: $documentId groupId: $groupId permission: $permission ) { groupId grantedBy documentId group { name } } } ``` Variables: ```json { "documentId": "drive-uuid-1234-5678-abcd", "groupId": 1, "permission": "WRITE" } ``` Expected Result: ```json { "data": { "grantGroupPermission": { "groupId": 1, "grantedBy": "0x1234...abcd", "documentId": "drive-uuid-1234-5678-abcd", "group": { "name": "finance-team" } } } } ``` ### Step 7: Grant Specific Operation Permission Give Finance Manager permission to execute the `ADD_FILE` operation for creating new financial documents. See the [Document Drive Operation Types](#document-drive-operation-types) section for all available operation permissions: Mutation: ```graphql mutation GrantOperationPermission( $documentId: String! $operationType: String! $userAddress: String! ) { grantOperationPermission( documentId: $documentId operationType: $operationType userAddress: $userAddress ) { operationType userAddress documentId } } ``` Variables: ```json { "documentId": "drive-uuid-1234-5678-abcd", "operationType": "ADD_FILE", "userAddress": "0xalice...finance" } ``` Expected Result: ```json { "data": { "grantOperationPermission": { "operationType": "ADD_FILE", "userAddress": "0xalice...finance", "documentId": "2d707e84-309a-4b69-803a-400786806ebf" } } } ``` ### Step 8: Test Permission Enforcement Now let's test our permission setup by switching between different user accounts. #### Test 1: Financial Analyst tries to create a file (should fail) First, logout and login as Bob (Financial Analyst): ```bash ph login --logout ph login # Login with Bob's wallet (0xbob...analyst) ph access-token --expiry 7d ``` Mutation: ```graphql mutation TodoList_createDocument($name: String!) { TodoList_createDocument(name: $name) } ``` Variables: ```json { "name": "Q1 Budget Planning" } ``` Expected Result: ❌ Permission Denied ```json { "errors": [ { "message": "Forbidden: insufficient permissions to create documents" } ] } ``` #### Test 2: Finance Manager creates a file (should succeed) Logout and login as Alice (Finance Manager): ```bash ph login --logout ph login # Login with Alice's wallet (0xalice...finance) ph access-token --expiry 7d ``` Mutation: ```graphql mutation TodoList_createDocument($name: String!, $driveId: String) { TodoList_createDocument(name: $name, driveId: $driveId) } ``` Variables: ```json { "name": "Q1 Budget Planning", "driveId": "drive-uuid-1234-5678-abcd" } ``` Expected Result: ✅ Success ```json { "data": { "TodoList_createDocument": "document-uuid-abcd-1234-efgh" } } ``` #### Test 3: Financial Analyst adds a todo to the file (should succeed) Switch back to Bob (Financial Analyst): ```bash ph login --logout ph login # Login with Bob's wallet ph access-token --expiry 7d ``` Mutation: ```graphql mutation TodoList_addTodoItem( $docId: PHID $driveId: String $input: TodoList_AddTodoItemInput ) { TodoList_addTodoItem(docId: $docId, driveId: $driveId, input: $input) } ``` Variables: ```json { "docId": "document-uuid-abcd-1234-efgh", "driveId": "drive-uuid-1234-5678-abcd", "input": { "text": "confirm runway expectations" } } ``` Expected Result: ✅ Success ```json { "data": { "TodoList_addTodoItem": 1 } } ``` Query the todo-List to verify ```graphql query GetDocument($docId: PHID!, $driveId: PHID) { TodoList { getDocument(docId: $docId, driveId: $driveId) { id name operations { inputText } } } } ``` Variables: ```json { "docId": "document-uuid-abcd-1234-efgh", "driveId": "drive-uuid-1234-5678-abcd" } ``` Expected Result: ```json { "data": { "TodoList": { "getDocument": { "id": "23fe9b72-6540-4eee-b55e-87e414429dd2", "name": "Q1 Budget Planning" } } } } ``` ### Summary This scenario demonstrates: 1. Group-based permissions: Both finance team members have WRITE access to the finance drive through group membership 2. Operation-level permissions: Only the Finance Manager can create new financial documents (`AddFile` operation) 3. Permission inheritance: Once a document exists, all team members can perform other operations (like renaming) due to their WRITE permissions on the parent drive 4. Granular control: You can restrict specific operations while allowing broader document access, perfect for sensitive financial data </details> <details> <summary><strong>Advanced Scenario: Todo List Collaboration</strong></summary> This scenario demonstrates advanced authorization patterns for managing contributor access levels to a shared todo list document, focusing on role-based access control and operation-level permissions using the @powerhousedao/todo-demo package. To get access to this subgraph yourself make sure to install the package in your project with `ph install @powerhousedao/todo-demo` <details> <summary><strong>Todo Document Schema Reference</strong></summary> ```graphql type TodoList implements IDocument { id: String! name: String! documentType: String! operations(skip: Int, first: Int): [Operation!]! revision: Int! createdAtUtcIso: DateTime! lastModifiedAtUtcIso: DateTime! initialState: TodoList_TodoListState! state: TodoList_TodoListState! stateJSON: JSONObject } """ Module: Todos """ input TodoList_AddTodoItemInput { text: String! } input TodoList_DeleteTodoItemInput { id: OID! } type TodoList_TodoItem { id: OID! text: String! checked: Boolean! } type TodoList_TodoListState { items: [TodoList_TodoItem!]! } input TodoList_UpdateTodoItemInput { id: OID! text: String checked: Boolean } """ Queries: TodoList Document """ type TodoListQueries { getDocument(docId: PHID!, driveId: PHID): TodoList getDocuments(driveId: String!): [TodoList!] } ``` </details> ### The Setup - Project Lead (Alice): Full admin control - Core Contributors (Bob, Carol): Can add and update todo items - External Contributors (Dave, Eve): Read-only access, can only add new todo items - Team Leads (Frank): Special access to delete todo items only ### Step 1: Create Role-Based Groups Create role-based groups: ```graphql mutation CreateCoreGroup { createGroup( name: "core-contributors" description: "Team members who can add and update todo items" ) { id name } } ``` ```graphql mutation CreateExternalGroup { createGroup( name: "external-contributors" description: "External users who can only add new todo items" ) { id name } } ``` ```graphql mutation CreateLeadsGroup { createGroup( name: "team-leads" description: "Team leads who can delete todo items" ) { id name } } ``` ### Step 2: Assign Users to Groups Add core team members: ```graphql mutation AddBobToCore { addUserToGroup(userAddress: "0xbob...core", groupId: 1) } ``` ```graphql mutation AddCarolToCore { addUserToGroup(userAddress: "0xcarol...core", groupId: 1) } ``` Add external contributors: ```graphql mutation AddDaveToExternal { addUserToGroup(userAddress: "0xdave...external", groupId: 2) } ``` Add team lead: ```graphql mutation AddFrankToLeads { addUserToGroup(userAddress: "0xfrank...lead", groupId: 3) } ``` ### Step 3: Set Document-Level Permissions Create a todo document for the next steps. Grant different access levels to each group for the todo list document: ```graphql mutation GrantCoreWriteAccess { grantGroupPermission( documentId: "todo-document-id" groupId: 1 permission: WRITE ) { groupId permission group { name } } } ``` ```graphql mutation GrantExternalReadAccess { grantGroupPermission( documentId: "todo-document-id" groupId: 2 permission: READ ) { groupId permission group { name } } } ``` ```graphql mutation GrantLeadsReadAccess { grantGroupPermission( documentId: "todo-document-id" groupId: 3 permission: READ ) { groupId permission group { name } } } ``` ### Step 4: Operation-Level Permission Control External contributors can only add new todo items: ```graphql mutation AllowExternalAddTodo { grantGroupOperationPermission( documentId: "todo-document-id" operationType: "AddTodoItem" groupId: 2 ) { operationType group { name } } } ``` Only core contributors can update todo items: ```graphql mutation AllowCoreUpdateTodo { grantGroupOperationPermission( documentId: "todo-document-id" operationType: "UpdateTodoItem" groupId: 1 ) { operationType group { name } } } ``` Only team leads can delete todo items: ```graphql mutation AllowLeadsDeletion { grantGroupOperationPermission( documentId: "todo-document-id" operationType: "DeleteTodoItem" groupId: 3 ) { operationType group { name } } } ``` ### Step 5: Permission Auditing & Verification Check what permissions a user has: ```graphql query MyPermissions { userDocumentPermissions { documentId permission grantedBy createdAt } } ``` Audit all access to sensitive document: ```graphql query AuditDocumentAccess($docId: String!) { documentAccess(documentId: $docId) { permissions { userAddress permission grantedBy } groupPermissions { group { name members } permission grantedBy } } } ``` Verify if user can perform specific operation: ```graphql query CheckOperationAccess($docId: String!, $operation: String!) { canExecuteOperation(documentId: $docId, operationType: $operation) } ``` ### Step 7: Dynamic Permission Management Promote external contributor to core team: ```graphql mutation PromoteContributor($userAddress: String!) { removeUserFromGroup(userAddress: $userAddress, groupId: 2) } ``` ```graphql mutation AddToCore($userAddress: String!) { addUserToGroup(userAddress: $userAddress, groupId: 1) } ``` Remove user from all groups (suspend access): ```graphql mutation SuspendUser($userAddress: String!) { removeUserFromGroup(userAddress: $userAddress, groupId: 1) } ``` ### Authorization Patterns Demonstrated 1. Role-Based Access Control (RBAC): Groups represent roles with different permission levels 2. Document-Level Permissions: Fine-grained control over specific document access 3. Operation-Level Granularity: Fine-grained control over specific todo list operations (add vs. update vs. delete) 4. Individual Overrides: User-specific permissions that supersede group permissions 5. Audit Trail: Complete visibility into who granted what permissions when 6. Dynamic Role Management: Users can be promoted/demoted between roles 7. Principle of Least Privilege: Each role gets minimum necessary permissions This scenario showcases how to implement granular permission control for collaborative document editing using specific document model operations from installed packages like @powerhousedao/todo-demo. </details> ## Integration with Auth Flow The document permission system integrates with the Renown authentication flow. Renown provides decentralized identity using Ethereum addresses and DIDs (Decentralized Identifiers). ### Authentication Flow 1. User authenticates via `ph login`: The user connects their Ethereum wallet and creates/retrieves a DID 2. User generates a bearer token via `ph access-token`: A JWT token is created that includes the user's Ethereum address 3. Bearer token is included in API requests: The client includes the token in the `Authorization` header 4. Reactor API verifies the token: The API validates the JWT and extracts the user's Ethereum address 5. Permission checks are performed: The system uses the Ethereum address to look up document permissions ### Example: Making Authenticated Requests ```bash # Generate access token (valid for 7 days) TOKEN="$(ph access-token --expiry 7d)" # Make authenticated request to query your permissions curl -X POST http://localhost:4001/graphql \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKEN}" \ -d '{"query": "{ userDocumentPermissions { documentId permission } }"}' ``` TIP: Permissions are tied to Ethereum addresses (e.g., `0x123...`), not usernames. When granting permissions, use the user's Ethereum address as shown in their Renown profile or obtained from `ph login --status`. ## Best Practices 1. Use groups for team access: Instead of granting individual permissions, create groups and assign permissions to groups 2. Grant ADMIN sparingly: Only grant ADMIN permission to users who need to manage permissions 3. Use permission inheritance: Grant permissions at the drive or folder level, let them inherit down 4. Document your permission structure: Keep track of which groups have access to which drives 5. Regular audits: Periodically review permissions and remove stale access ## Troubleshooting Common issues and how to resolve them: ### Permission denied errors If a user receives "Permission denied" when trying to access a document: 1. Verify `AUTH_ENABLED=true` and `DOCUMENT_PERMISSIONS_ENABLED=true` in your Reactor configuration 2. Check that the user has a valid Renown credential (`ph login --status`) 3. Verify the bearer token is valid and not expired (`ph access-token` to generate a new one) 4. Check if the user has direct or group permission on the document using `documentAccess` query 5. Check if permission is inherited from a parent document (drive or folder) ### Migrations not running Ensure database migrations have run: ```bash # Migrations run automatically on startup when DOCUMENT_PERMISSIONS_ENABLED=true # Check logs for "Document permission migrations completed" ``` --- ## Signing > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/Authorization/Signing Powerhouse uses two complementary signing mechanisms to establish trust across the document lifecycle: - Header signing ties a document's identity to its creator via a cryptographic signature that becomes the document ID. - Action signing ensures every mutation to a document is attributable to a specific user and app, and can be verified offline. Both mechanisms use ECDSA with the P-256 curve and SHA-256 via the Web Crypto API. ## Header Signing (Document Identity) Every Powerhouse document has a header containing immutable identity fields. The document's `id` field is itself a cryptographic signature, meaning the document's identity is inseparable from its creator. ### How it works When a document is created, the system: 1. Generates a presigned header with placeholder values via `createPresignedHeader()`. 2. Builds a deterministic payload from the signing parameters: `documentType + createdAtUtcIso + nonce`. 3. Signs that payload with the creator's private key. 4. Sets the resulting signature as the document's `id`. The header stores everything needed for self-contained verification: | Field | Purpose | | ------------------------ | -------------------------------------------------- | | `header.id` | The cryptographic signature (also the document ID) | | `header.sig.publicKey` | The creator's public key (JWK format) | | `header.sig.nonce` | Random nonce used as salt during signing | | `header.documentType` | The document model type | | `header.createdAtUtcIso` | Creation timestamp | ### Verification Anyone can verify a document's authenticity using only its header. The `validateHeader()` function reconstructs a verification-only signer from the embedded public key, regenerates the payload from `documentType + createdAtUtcIso + nonce`, and verifies the signature matches the document ID. ```typescript // Throws if the header signature is invalid await validateHeader(document.header); ``` ### Key functions | Function | Location | Purpose | | ------------------------------- | ----------------------------------- | ----------------------------------------------------------- | | `createPresignedHeader()` | `document-model/src/core/header.ts` | Creates an unsigned header with placeholder fields | | `createSignedHeader()` | `document-model/src/core/header.ts` | Signs a presigned header, setting `id` to the signature | | `createSignedHeaderForSigner()` | `document-model/src/core/header.ts` | Convenience: creates and signs a header in one step | | `validateHeader()` | `document-model/src/core/header.ts` | Verifies a header's signature using its embedded public key | ## Action Signing (Operation Authenticity) When a user dispatches an action (e.g., editing a field, adding a record), that action can be cryptographically signed to prove who performed it and that the content has not been tampered with. ### The ISigner interface The `ISigner` interface is the core abstraction for all signing operations: ```typescript interface ISigner { user?: UserActionSigner; // { address, networkId, chainId } app?: AppActionSigner; // { name, key } publicKey: CryptoKey; sign(data: Uint8Array): Promise<Uint8Array>; verify(data: Uint8Array, signature: Uint8Array): Promise<void>; signAction(action: Action, abortSignal?: AbortSignal): Promise<Signature>; } ``` It serves two purposes: - `sign()` / `verify()` handle raw data signing, used for header signing. - `signAction()` produces a structured `Signature` tuple, used for action signing. ### The Signature tuple A signed action produces a 5-element `Signature` tuple: ``` [timestamp, signerKey, actionHash, hashField, signatureHex] ``` | Index | Field | Description | | ----- | -------------- | ----------------------------------------------------------------------------------- | | 0 | `timestamp` | Unix timestamp (seconds) when the action was signed | | 1 | `signerKey` | The signer's public key identifier (typically a `did:key` URI) | | 2 | `actionHash` | SHA-1 hash of `documentId + scope + actionType + JSON(input)` | | 3 | `hashField` | Previous state hash, or `prevStateHash:resultingStateHash` for offline verification | | 4 | `signatureHex` | The ECDSA signature bytes as a `0x`-prefixed hex string | The signed message uses the prefix `\x19Signed Operation:\n{length}` followed by the concatenation of elements 0-3, matching the pattern used by Ethereum-style message signing. ### ActionSigner context Each signed action carries an `ActionSigner` context that identifies both the user and the application: ```typescript type ActionSigner = { user: UserActionSigner; // { address, networkId (CAIP-2), chainId (CAIP-10) } app: AppActionSigner; // { name, key (DID) } signatures: Signature[]; }; ``` This context is attached to the action's `context.signer` field and flows through the entire system -- from the client, through the reactor, into storage, and out through the GQL API. ### Key functions | Function | Location | Purpose | | ---------------------------------- | ------------------------------------ | ------------------------------------------------------------ | | `buildOperationSignature()` | `document-model/src/core/actions.ts` | Creates a Signature tuple from an action context | | `buildSignedAction()` | `document-model/src/core/actions.ts` | Reduces an action, signs it, and attaches the signer context | | `verifyOperationSignature()` | `document-model/src/core/actions.ts` | Verifies a Signature tuple against its signer | | `buildOperationSignatureParams()` | `document-model/src/core/crypto.ts` | Builds the 4-element params from action context | | `buildOperationSignatureMessage()` | `document-model/src/core/crypto.ts` | Constructs the prefixed message for signing | ## ReactorClient Auto-Signing The `ReactorClient` automatically signs all actions before submitting them to the reactor. You do not need to manually sign actions when using the client. ### How it works `ReactorClient` holds an `ISigner` instance. Every mutation method -- `execute()`, `create()`, `createChild()`, `add()`, `remove()`, `move()` -- calls `signActions()` internally before submitting to the reactor. If an action already has valid signatures, it is passed through unchanged. ```typescript // From reactor/src/core/utils.ts const signAction = async (action, signer, signal?) => { // Skip if already signed const existingSignatures = action.context?.signer?.signatures; if (existingSignatures && existingSignatures.length > 0) { return action; } const signature = await signer.signAction(action, signal); return { ...action, context: { ...action.context, signer: { user: { address: signer.user?.address || "", ... }, app: { name: signer.app?.name || "", key: signer.app?.key || "" }, signatures: [signature], }, }, }; }; ``` ### Wiring a signer Use `ReactorClientBuilder.withSigner()` to configure signing. It accepts either a bare `ISigner` or a `SignerConfig` that includes an optional verifier: ```typescript // Option 1: Signing only (no server-side verification) const client = await new ReactorClientBuilder() .withReactorBuilder(reactorBuilder) .withSigner(mySigner) .build(); // Option 2: Signing + verification const client = await new ReactorClientBuilder() .withReactorBuilder(reactorBuilder) .withSigner({ signer: mySigner, verifier: createSignatureVerifier(), }) .build(); ``` If no signer is provided, the client defaults to `PassthroughSigner` -- a no-op implementation that returns empty signatures, effectively disabling signing. ### ISigner implementations | Implementation | Package | Purpose | | -------------------- | --------- | ----------------------------------------------------------- | | `PassthroughSigner` | `reactor` | No-op signer, used when signing is disabled | | `RenownCryptoSigner` | `renown` | Production signer using ECDSA P-256 with `did:key` identity | `RenownCryptoSigner` is the standard production implementation. It derives signing keys from the Renown identity system and identifies signers using DID URIs (`did:key:z...`). ## Signature Verification Signature verification is optional and runs in the reactor's executor before actions are processed. ### How it works The `SignatureVerifier` class sits in the executor pipeline. When a `SignatureVerificationHandler` is configured, it: 1. Inspects each incoming action for a `context.signer`. 2. If a signer is present but has no signatures, the action is rejected. 3. Calls the handler to verify the signature against the signer's public key. 4. Throws `InvalidSignatureError` if verification fails. This applies to both action jobs (new mutations) and load jobs (operations arriving from sync). ### Configuration Verification is enabled by passing a `verifier` in the `SignerConfig`: ```typescript const client = await new ReactorClientBuilder() .withReactorBuilder(reactorBuilder) .withSigner({ signer: mySigner, verifier: createSignatureVerifier(), }) .build(); ``` The `createSignatureVerifier()` function from the `renown` package returns a handler that uses the Web Crypto API to verify ECDSA P-256 signatures. It extracts the public key from the signer's DID and verifies the signature against the reconstructed message. If no verifier is provided, all actions are accepted regardless of their signature status. ## Signing at the GQL / Switchboard Level When you interact with a reactor through its GraphQL API (the switchboard), signing is handled for you depending on how actions are submitted. ### Submitting actions via GQL mutations The GQL mutations `mutateDocument` and `mutateDocumentAsync` accept actions as JSON objects. These actions are passed through the switchboard's `ReactorClient`, which auto-signs them using whatever `ISigner` was configured on that reactor instance. This means: - If you submit unsigned actions through the GQL API, the switchboard signs them on your behalf using its configured signer. - If you submit pre-signed actions (actions that already have a `context.signer` with signatures), the switchboard passes them through unchanged -- it does not re-sign. ### When the switchboard signs The switchboard signs actions during any mutation that flows through the `ReactorClient`: | Mutation | What gets signed | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `createDocument` | CREATE_DOCUMENT + UPGRADE_DOCUMENT actions, plus parent relationship action if a parent is specified | | `createEmptyDocument` | Same as above, using a default initial state | | `mutateDocument` / `mutateDocumentAsync` | All submitted actions | | `addRelationship` / `removeRelationship` / `moveRelationship` | Relationship actions on the source document(s) | | `deleteDocument` / `deleteDocuments` | DELETE_DOCUMENT actions for the target and its descendants | ### When you should pre-sign If your client has its own `ISigner` (e.g., a `RenownCryptoSigner` tied to a specific user identity), you should sign actions before submitting them to the GQL API. This ensures the signatures reflect the actual user who performed the action, rather than the switchboard's server-side identity. Pre-signed actions are detected by checking for existing signatures in `action.context.signer.signatures` -- if any are present, the `ReactorClient` skips signing. --- ## Reactor API Authorization > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/Authorization/Authorization WARNING: This documentation is still being written and may be incomplete. This guide explains how to configure authorization for the Powerhouse Reactor API. Authorization controls who can access your Reactor and what they can do. ## Introduction The Reactor API is the API interface to a Powerhouse Reactor—a storage node responsible for storing documents, resolving conflicts, and verifying document event histories. Before users can interact with documents in your Reactor, they must pass through authorization checks. ### Authorization Model The Reactor API uses a layered authorization model: | Component | Purpose | Scope | | ------------------------------------------------------- | ---------------------------------------------------------- | ------------ | | Supreme Admin (`ADMINS` env var) | Full bypass of all permission checks | Reactor-wide | | Document Protection | Determines whether a document requires explicit grants | Per-document | | [Document Permissions](../docs/docs/02-DocumentPermissions.md) | Fine-grained READ/WRITE/ADMIN grants on specific documents | Per-document | TIP: - For simple setups, configure `ADMINS` and leave documents unprotected — any authenticated user can read and write - When you need fine-grained control, protect specific documents and manage access with [document permissions](../docs/docs/02-DocumentPermissions.md) ::: ## Prerequisites Before configuring authorization, you need: 1. A running Reactor: See [Document Permissions - Starting the Reactor API](../docs/docs/02-DocumentPermissions.md#starting-the-reactor-api) for setup instructions 2. User Ethereum addresses: Addresses of users you want to grant admin access to ## Basic Configuration The Reactor API supports two main ways to configure authorization: 1. Using environment variables 2. Using the powerhouse configuration file ### Environment Variables Configure authorization using environment variables before starting the Reactor: ```bash # Required: Enable/disable authentication AUTH_ENABLED=true # Optional: Comma-separated list of admin wallet addresses (full access, bypasses all checks) ADMINS="0x123...,0x456..." # Optional: Make all new documents protected by default (requires explicit grants) DEFAULT_PROTECTION=true # Optional: Enable per-document permission management DOCUMENT_PERMISSIONS_ENABLED=true ``` Important notes: - Use full Ethereum addresses (e.g., `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb`) - ADMINS: These addresses bypass all permission checks entirely - DEFAULT_PROTECTION=true: New documents are created as protected, requiring explicit grants for access - DEFAULT_PROTECTION=false (default): New documents are unprotected — anyone can read, authenticated users can write - DOCUMENT_PERMISSIONS_ENABLED=true: Enables the per-document permission system for managing grants - If `AUTH_ENABLED=false`, all authorization checks are bypassed (not recommended for production) ### Powerhouse configuration Alternatively, you can configure authorization in your `powerhouse.config.json`: ```json { "auth": { "enabled": true, "admins": ["0x123", "0x456"] } } ``` ## How Authorization Works ### Supreme Admin Addresses listed in `ADMINS` have full access to the entire Reactor. They bypass all permission checks, including document protection. Use this for system administrators and project owners. ### Document Protection Each document (drive, folder, or document) can be either protected or unprotected: | State | Read Access | Write Access | | --------------- | ------------------------------- | ------------------------------- | | Unprotected | Anyone | Any authenticated user | | Protected | Only users with explicit grants | Only users with explicit grants | - Use `DEFAULT_PROTECTION=true` to make all new documents protected by default - Protection can also be toggled per-document via the GraphQL API ### Per-Document Grants When a document is protected, users need explicit grants to access it. Grants are managed through the [Document Permission System](../docs/docs/02-DocumentPermissions.md) and support: - Direct grants: Assigned to a specific user address - Group grants: Assigned to a group of users - Inherited grants: Flow down from parent (drive → folder → document) - Grant levels: READ, WRITE, or ADMIN ## Docker Configuration When running the Reactor API in Docker, you can pass these configurations as environment variables: ```bash docker run -e AUTH_ENABLED=true \ -e ADMINS="0x123,0x456" \ -e DEFAULT_PROTECTION=true \ -e DOCUMENT_PERMISSIONS_ENABLED=true \ your-reactor-api-image ``` ## Authorization Flow Understanding how authorization checks work: ``` User makes API request | Is AUTH_ENABLED=true? |-- No --> Access granted (no auth required) +-- Yes --> Continue to auth check | Does user have valid bearer token? |-- No --> 401 Unauthorized +-- Yes --> Extract Ethereum address from token | Is user's address in ADMINS? |-- Yes --> Full access (bypass all checks) +-- No --> Check document protection | Is the target document protected? |-- No --> Read: allow, Write: allow (user is authenticated) +-- Yes --> Check grants | Does user have a grant for this document? |-- Yes --> Grant-level access (READ/WRITE/ADMIN) +-- No --> 403 Forbidden ``` ### Step-by-Step 1. Authentication check: If `AUTH_ENABLED=false`, all requests are allowed (skip remaining steps) 2. Token validation: User must include valid bearer token from `ph access-token` 3. Supreme admin check: If the user's address is in `ADMINS`, grant full access 4. Document protection check: If the document is unprotected, allow read for everyone and write for authenticated users 5. Grant check (protected documents only): Check [document-level permissions](../docs/docs/02-DocumentPermissions.md) for READ/WRITE/ADMIN grants TIP: - Authentication ([Renown flow](../docs/docs/01-RenownAuthenticationFlow.md)): Proves who you are (`ph login`) - Authorization (this guide): Determines what you can access ::: ## Common Scenarios ### Scenario 1: Open Development Environment You want a local Reactor where anyone can access everything: ```bash AUTH_ENABLED=false ``` Use case: Local development, testing, demos ### Scenario 2: Protected Production Environment Only admins have unrestricted access, all documents require explicit grants: ```bash AUTH_ENABLED=true ADMINS="0xProjectLead" DEFAULT_PROTECTION=true DOCUMENT_PERMISSIONS_ENABLED=true ``` Use case: Private team workspace, sensitive data. Use [document permissions](../docs/docs/02-DocumentPermissions.md) to grant access to specific users. ### Scenario 3: Open Collaboration with Admin Oversight Any authenticated user can read and write, admins manage the Reactor: ```bash AUTH_ENABLED=true ADMINS="0xProjectLead" ``` Use case: Open source projects, community collaboration. Documents are unprotected by default, so any authenticated user can contribute. Protect specific documents as needed. ### Scenario 4: Mixed Access Some documents are open, others are restricted: ```bash AUTH_ENABLED=true ADMINS="0xProjectLead" DOCUMENT_PERMISSIONS_ENABLED=true ``` Use case: Team workspace where most content is open but certain drives/documents are protected with explicit grants. ## Security Best Practices 1. Secure admin addresses: Keep admin wallet private keys secure 2. Use HTTPS in production: Never expose the Reactor API over plain HTTP 3. Regular access audits: Review admin list and document grants periodically 4. Development vs Production: Use `AUTH_ENABLED=false` only in local development 5. Protect sensitive documents: Use `DEFAULT_PROTECTION=true` or protect individual documents containing sensitive data 6. Use document permissions: For production, combine admin access with [document-level permissions](../docs/docs/02-DocumentPermissions.md) for fine-grained control ## Troubleshooting Common issues and solutions: ### "403 Forbidden" Error Problem: User has valid token but cannot access a document Solutions: 1. Check if the document is protected — if so, the user needs an explicit grant 2. Verify the user's address is in `ADMINS` if they need full access 3. Use [document permissions](../docs/docs/02-DocumentPermissions.md) to grant the user access to the specific document 4. Verify wallet addresses are correctly formatted (full addresses, no typos) ### "401 Unauthorized" Error Problem: Request is rejected before reaching authorization Solutions: 1. User needs to authenticate: `ph login` 2. Generate valid bearer token: `ph access-token` 3. Include token in request header: `Authorization: Bearer <token>` 4. Check token hasn't expired ### Configuration Not Taking Effect Problem: Changed configuration but nothing happens Solutions: 1. Restart the Reactor after configuration changes 2. Check environment variables are set in the correct shell/environment 3. Verify `powerhouse.config.json` syntax is valid JSON 4. Environment variables override config file - check for conflicts ### How to Find a User's Ethereum Address ```bash # User checks their own address ph login --status ``` The address is shown in the authentication status output. ## Next Steps - Document Permissions: Set up [fine-grained document permissions](../docs/docs/02-DocumentPermissions.md) - Authentication: Learn about the [Renown authentication flow](../docs/docs/01-RenownAuthenticationFlow.md) - API Usage: Explore [using the GraphQL API](../docs/../04-WorkWithData/02-UsingTheAPI.mdx) --- ## Enforcing Authorization in Subgraphs > Source: https://academy.vetra.io/academy/Build/BuildingUserExperiences/Authorization/EnforcingAuthorizationInSubgraphs WARNING: This documentation is still being written and may be incomplete. The other pages in this section explain how an operator configures authorization for a Reactor ([Reactor API Authorization](../docs/docs/04-Authorization.md)) and how grants are managed ([Document Permissions](../docs/docs/02-DocumentPermissions.md)). This page is for builders: when you write a [custom subgraph](../docs/../04-WorkWithData/03-UsingSubgraphs.md), your resolvers run with full access to the Reactor, so you are responsible for enforcing authorization on the data they read and write. ## Why your resolvers must enforce authorization The Reactor's built-in subgraphs (`r`, `auth`, `document-drive`, the document-model subgraphs) already guard every resolver. A custom subgraph you generate with `ph generate subgraph` does not — the generated resolvers call the Reactor client directly and will happily return data regardless of who is asking. Consider the search resolver from the [Using subgraphs](../docs/../04-WorkWithData/03-UsingSubgraphs.md) tutorial: ```typescript searchTodos: async (parent, args: { driveId: string; searchTerm: string }) => { const children = await reactorClient.getOutgoingRelationships( args.driveId, "child", ); // ...returns every matching document id, with no permission check }; ``` If the Reactor is configured with document permissions, this resolver leaks the existence — and ids — of documents the caller is not allowed to read. The enforcement helpers on `BaseSubgraph` exist to close exactly this gap. ## The model you are enforcing against Authorization is decided by a single service selected once at boot by the Reactor's [policy](../docs/docs/04-Authorization.md#how-authorization-works). You do not branch on the policy yourself — you call the same helpers in every resolver and the active policy decides the outcome: | Policy | When | What the helpers do | | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------- | | OPEN | `AUTH_ENABLED=false` | Every check passes for everyone, including anonymous callers. | | ADMIN_ONLY | `AUTH_ENABLED=true`, document permissions off | Only addresses in `ADMINS` pass any check. | | DOCUMENT_PERMISSIONS | `DOCUMENT_PERMISSIONS_ENABLED=true` | Full per-document protection + READ/WRITE/ADMIN grants, with inheritance. | Because the policy is resolved centrally, the right approach is to write one enforcement path and let it behave correctly under all three policies. Calling a helper is always safe: under OPEN it is effectively a no-op, and under the stricter policies it fails closed. ## Where the helpers live The helpers are public methods on `BaseSubgraph`. The scaffold produced by `ph generate subgraph` hands you the subgraph instance as the `subgraph` parameter of `getResolvers`, so call them directly as `subgraph.assertCanRead(...)`: ```typescript // subgraphs/search-todos/resolvers.ts export const getResolvers = ( subgraph: BaseSubgraph, ): Record<string, unknown> => { const reactor = subgraph.reactorClient; return { Query: { document: async ( _parent: unknown, args: { identifier: string }, ctx: Context, ) => { const handle = await subgraph.assertCanRead(args.identifier, ctx); return reactor.get(handle.fetchIdentifier); }, }, }; }; ``` TIP: If you define resolvers inside your subgraph class instead of in `getResolvers`, call the helpers on `this` (`this.assertCanRead(...)`). That is the style the Reactor's built-in subgraphs use. Both forms reach the same public methods. The caller's verified identity is on the request `Context` as `ctx.user`: ```typescript ctx.user?.address; // the verified Ethereum address, or undefined for anonymous callers ``` You never read identity from headers or arguments — `ctx.user` is the only trustworthy source, and it is `undefined` until the [authentication flow](../docs/docs/01-RenownAuthenticationFlow.md) has verified a token. ## Identifiers: slugs, canonical ids, and the handle Resolvers usually receive an identifier that may be either a document id or a slug. Permission rows, however, are keyed on the canonical document id. If you authorized a slug but then fetched by that same slug through a different code path, a caller could alias one document's slug onto another and slip past the check. The identifier-accepting asserts solve this for you. Each returns an `AuthorizedDocumentHandle` whose `fetchIdentifier` is always safe to fetch with — it is the canonical id when a check ran, or the original identifier when the check was skipped for a policy-wide caller (OPEN or a supreme admin): ```typescript const handle = await subgraph.assertCanRead(args.identifier, ctx); // throws if denied const doc = await subgraph.reactorClient.get(handle.fetchIdentifier); // never args.identifier ``` Rule of thumb: after any `assertCan` that takes an identifier, perform the data fetch with `handle.fetchIdentifier`, never with the original argument. ## The helper reference All of the following are public methods on `BaseSubgraph`, called on the `subgraph` instance (or `this` from a class-field resolver): | Helper | Use when | On failure | | -------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ | | `assertCanRead(identifier, ctx)` | Reading one document the caller named (id or slug). | throws `Forbidden` | | `assertCanWrite(identifier, ctx)` | Mutating one document the caller named. | throws `Forbidden` | | `assertCanExecuteOperation(identifier, type, ctx)` | Executing a specific operation type on a document. | throws `Forbidden` | | `assertCanCreate(ctx)` | Creating a new top-level document (no parent to check write against). | throws `Forbidden` | | `canReadDocument(canonicalId, ctx)` | Filtering a list — a non-throwing read check on an id from the data layer. | returns `boolean` | | `authorizationService.isSupremeAdmin(address)` | Short-circuiting per-item filtering for policy-wide callers. | returns `boolean` | Each `assertCan` that takes an `identifier` returns an `AuthorizedDocumentHandle`; use its `fetchIdentifier` for the subsequent fetch. There are also lower-level `Canonical` variants (`assertCanReadCanonical`, etc.) used by the built-in subgraphs when an id has already been resolved by the data layer; prefer the identifier-accepting variants in your own code. The supporting types are exported from `@powerhousedao/reactor-api` when you need to name them — `Context`, `CanonicalDocumentId`, `AuthorizationPolicy`, `AuthorizedDocumentHandle`, and `IAuthorizationService`. ## Patterns ### Guard a single-document read ```typescript document: async (_parent, args: { identifier: string }, ctx: Context) => { const handle = await subgraph.assertCanRead(args.identifier, ctx); return subgraph.reactorClient.get(handle.fetchIdentifier); }; ``` ### Guard a write ```typescript renameDocument: async ( _parent, args: { identifier: string; name: string }, ctx: Context, ) => { const handle = await subgraph.assertCanWrite(args.identifier, ctx); return doRename(handle.fetchIdentifier, args.name); }; ``` ### Guard a specific operation type When a write should be allowed only for callers permitted to run a _particular_ operation (operation-level grants): ```typescript addTodoItem: async ( _parent, args: { docId: string; input: AddTodoItemInput }, ctx: Context, ) => { const handle = await subgraph.assertCanExecuteOperation( args.docId, "ADD_TODO_ITEM", ctx, ); return applyOperation(handle.fetchIdentifier, "ADD_TODO_ITEM", args.input); }; ``` ### Guard document creation If you are creating a document under a parent, the meaningful check is write access on that parent, so resolve and assert against it. Only use `assertCanCreate` for a genuinely top-level document with no parent: ```typescript createTodoList: async ( _parent, args: { parentIdentifier?: string; name: string }, ctx: Context, ) => { if (args.parentIdentifier) { const handle = await subgraph.assertCanWrite(args.parentIdentifier, ctx); return createUnder(handle.fetchIdentifier, args.name); } subgraph.assertCanCreate(ctx); // throws if the caller may not create documents return createTopLevel(args.name); }; ``` ### Filter a list of documents A resolver that returns _many_ documents must not throw on the first forbidden one — it must drop the documents the caller cannot read and return the rest. Supreme admins (and OPEN) see everything, so skip the per-item work for them: ```typescript searchTodos: async ( _parent, args: { driveId: string; searchTerm: string }, ctx: Context, ) => { const matches = await runSearch(args.driveId, args.searchTerm); // returns document ids // Policy-wide callers see everything; skip the per-item check. if (subgraph.authorizationService.isSupremeAdmin(ctx.user?.address)) { return matches; } const visible: string[] = []; for (const id of matches) { // canReadDocument is non-throwing; ids returned by the Reactor are already canonical if (await subgraph.canReadDocument(id as CanonicalDocumentId, ctx)) { visible.push(id); } } return visible; }; ``` This is the same shape the built-in `findDocuments` and relationship resolvers use. Filtering on read also means you never leak the _existence_ of a protected document through a list endpoint. ## Best practices 1. Fail closed. Authorize _before_ you fetch or mutate, and let a denial throw. Never fetch first and filter the response shape afterwards. 2. Fetch with `handle.fetchIdentifier`. Never re-use the raw identifier the caller passed in after an `assertCan` check. 3. Trust only `ctx.user`. Do not read identity from arguments or headers. 4. Filter lists, don't throw on them. Use `canReadDocument` + `isSupremeAdmin` for collection resolvers; reserve the throwing asserts for single-target resolvers. 5. Pick the tightest check. Read endpoints use `assertCanRead`; mutations use `assertCanWrite`; operation-restricted mutations use `assertCanExecuteOperation`. 6. Write the check unconditionally. Don't special-case OPEN or ADMIN_ONLY in your resolver — the helpers already collapse to the correct behavior per policy. TIP: Inside the `reactor-api` package, a default-deny test (`test/authorization-coverage.test.ts`) fails CI if any resolver on the built-in subgraphs references neither the authorization service nor a reviewed exemption. Custom subgraphs in your own project are not covered by that test — the responsibility for the patterns above is yours. ## Next steps - Configure the Reactor: [Reactor API Authorization](../docs/docs/04-Authorization.md) - Manage grants: [Document Permissions](../docs/docs/02-DocumentPermissions.md) - Authentication flow: [Renown authentication](../docs/docs/01-RenownAuthenticationFlow.md) - Build a subgraph: [Using subgraphs](../docs/../04-WorkWithData/03-UsingSubgraphs.md) --- ## Configure a drive > Source: https://academy.vetra.io/academy/Build/WorkWithData/ConfiguringDrives A drive in Powerhouse is a container for documents and data. It's a place where you can organize and store your documents and share them with others. This guide walks you through configuring and managing drives in your Powerhouse environment. INFO: Before configuring a drive, ensure you have: - Powerhouse [CLI installed](/academy/Build/GettingStartedBuilding/Prerequisites) - Access to a Powerhouse instance - Appropriate permissions to create and manage drives ::: ## Understanding drives ### Local drives A local drive is a container for local documents and data, hosted on your local machine. Technically, a drive is itself a document that contains a list of the documents inside it. When you run Connect locally with `ph connect`, a local drive is automatically added. You can also create a new local drive by clicking 'Create New Drive' in Connect. ### Remote drives vs. reactors Remote drives let you connect to and work with data stored in external systems or cloud services. They act as bridges between Powerhouse contributors or other data sources, syncing data between them. Drives can exist in three types of locations: - Local Storage: For offline or on-device access. - Cloud Storage: For centralized, scalable data management. - Decentralized Storage: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options. TIP: Powerhouse Reactors are the nodes in the network that store and synchronize documents and drives, resolve conflicts, and rerun operations to verify document event histories. Reactors can be configured for local storage, centralized cloud storage, or a decentralized storage network. A reactor allows you to store multiple documents and host drives and Drive-apps with different organizational purposes, users, access rights, and more. A drive uses a reactor and its underlying storage layer. A reactor is the low-level component that enables the synchronization of documents and drives. ### Drive-apps Drive-apps are specialized interfaces that enhance how users interact with documents within a drive. As mentioned, a drive is technically just another document containing a list of other documents. This means you can create a custom editor for your drive document. These customized editors are called Drive-apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive-app might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing. To learn more about building and customizing Drive-apps, check out our [Building a Drive-app](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) guide. ## Creating a new drive <figure className="image-container"> <img src={require("./images/CreateDrive.png").default} alt="Create a new drive" /> <figcaption>The drive management modal after clicking the 'Create New Drive' button.</figcaption> </figure> To create a new drive in Powerhouse, follow these steps: 1. Click the "Create New Drive" button in the Connect interface or the + icon in the Connect sidebar. 2. In the modal that appears, enter a name for your drive in the "Drive Name" field. 3. Select the desired Drive-app (such as the Generic Drive-app, or any other Drive-app you've installed). 4. Choose the location for your drive: Local (only available to you), Cloud (available to people in this drive), or Public (available to everyone). 5. (Optional) Enable the "Make available offline" toggle if you want to keep a local backup of your drive. 6. Once all options are set, click the "Create new drive" button to finalize and create your drive. ## Add a new remote drive via GraphQL mutation You can also add a new remote drive to your Connect environment programmatically using GraphQL mutations. This is especially useful for automation, scripting, or integrating with external systems. INFO: - Access to the Switchboard or remote reactor (server node) of your Connect instance. In your local project, you can start your Reactor by running the following command in a different terminal from Connect Studio. `bash ph reactor ` - The GraphQL endpoint of your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql` (this is a supergraph gateway. Read more about [subgraphs and supergraphs here](/academy/Build/WorkWithData/UsingSubgraphs). - Appropriate permissions to perform mutations. ::: <figure className="image-container"> <img src={require("./images/CreateNewDrive.png").default} alt="Create a new drive" /> <figcaption>The GraphQL interface for creating a new drive through a mutation.</figcaption> </figure> ### 1. Navigate to the GraphQL Playground or use a GraphQL client - Open [https://switchboard.phd/graphql](https://switchboard.phd/graphql) in your browser, or use a tool like [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/). ### 2. Prepare the Mutation - Use the following mutation to create a new drive. Since a drive is itself a document of type `DocumentDrive`, you use the `DocumentDrive` mutation namespace: ```graphql title="Create Drive Mutation" mutation CreateDrive($name: String!, $slug: String) { DocumentDrive { createDocument(name: $name, slug: $slug) { id name slug documentType state { global { name icon } } } } } ``` - These are the example variables; change them as needed: ```json title="Example Variables" { "name": "AcademyTest", "slug": null } ``` - You can also provide a custom `slug` if needed. ### 3. Execute the Mutation - Run the mutation. On success, you will receive a response containing the new drive's details: ```json title="Successful Response" { "data": { "DocumentDrive": { "createDocument": { "id": "6461580b-d317-4596-942d-f6b3d1bfc8fd", "name": "AcademyTest", "slug": "6461580b-d317-4596-942d-f6b3d1bfc8fd", "documentType": "powerhouse/document-drive", "state": { "global": { "name": "AcademyTest", "icon": null } } } } } } ``` ### 4. Construct the Drive URL - Once you have the `id` or `slug`, you can construct the drive URL for Connect: - Format: `domain/d/<driveId>` or `domain/d/<driveSlug>` - Depending on whether you are using a hosted or a local environment, the domain in your URL will change. - Example: `https://connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd` - Example: `https://localhost:4001/d/6461580b-d317-4596-942d-f6b3d1bfc8fd` ### 5. Add the Drive in Connect - Use the constructed URL to add or access the drive in your Connect environment via the 'Add Drive' button. <figure className="image-container"> <img src={require("./images/AddDrive.png").default} alt="Create a new drive" /> <figcaption>The 'Add Drive' button that allows you to enter your constructed Drive URL.</figcaption> </figure> --- This approach allows you to automate drive creation and integration with other systems, making it easy to manage drives at scale. ## Up next You've now experienced the use of GraphQL to modify or read data captured in Powerhouse for the first time. You can now either continue with: - User interfaces and [build custom Drive-apps](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) - Keep playing with data and the [Switchboard API](/academy/Build/WorkWithData/UsingTheAPI) Enjoy! --- ## Using the API > Source: https://academy.vetra.io/academy/Build/WorkWithData/UsingTheAPI ## Introduction to Switchboard Switchboard is the API interface that enables developers and data engineers to access data captured through document models in Connect and Fusion. Once you've structured and captured data from your business processes, use Switchboard to build experiences in external websites, create interactive drive widgets, or generate reports and dashboards in Fusion. TIP: Since your document models are 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 documents. <details> <summary>New to GraphQL? Click here for a primer on GraphQL concepts at Powerhouse</summary> GraphQL plays a fundamental role in defining document model data schemas, handling data access patterns, and enabling event-driven workflows within 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. GraphQL SDL is the backbone of Specification Driven Design & Development at Powerhouse. By defining your document models in SDL, you create machine-readable specifications that developers, designers, and AI agents all work from. ### 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. ### 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 and 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 } } ``` ### GraphQL Subgraphs in Powerhouse Powerhouse structures its data into subgraphs, which are modular GraphQL services that connect to the Reactor (Powerhouse's core data infrastructure) or Data Stores fueled by data from processors. Each subgraph has its own SDL, ensuring modularity and flexibility while working within the ecosystem. Fetching data from the Reactor: Powerhouse uses GraphQL to expose system-level data, such as drives, users, and operational records through the Reactor Subgraph, which 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. For example, a subgraph can track file uploads and expose this data via GraphQL queries. ### CQRS Architecture with GraphQL Powerhouse uses CQRS (Command Query Responsibility Segregation) 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 | For more information about GraphQL fundamentals, visit the [Introduction to GraphQL](https://graphql.org/learn/) documentation. </details> ## Querying a document with the GraphQL API ### Starting the reactor locally Use a GraphQL query to read a document model. This continues with the To-do List example from the [introduction tutorial](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject), but the process applies to any document model. To make our document model available in the Apollo Studio Sandbox, we'll need to store it on a remote [Reactor](/academy/Reference/Reactor/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 a decentralized storage network. Just as you can run Connect locally in studio mode, you can also run a Reactor locally. Use the following command in the terminal from within your Powerhouse project directory: ```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 ``` This 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 (+) 'Create New Drive' button in the Connect drive navigation and using the localhost URL to add a new drive with its underlying reactor. Usually, this is http://localhost:4001/d/powerhouse. Get access to an organization's drive instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive URL. Click the (+) 'Create New Drive' to add a public drive. To add a new drive, you'll have to know the correct public URL of the drive. Read more about [configuring drives](/academy/Reference/Reactor/WorkingWithTheReactor). <figure className="image-container"> <img src={require("./images/AddNewDriveURL.png").default} alt="Add a drive through an URL" /> <figcaption> The 'Add Drive' button that allows you to enter a Drive URL. </figcaption> </figure> ## Query the state of a document With the remote reactor and/or drive running, store a document model on it. Create a new to-do list document in Connect Studio named 'Powerhouse-onboarding-tasks'. Add the following to-dos to your list: - [ ] Sign up for Powerhouse - [ ] Do the work - [ ] Deliver the work - [ ] Send the invoice - [ ] Get paid Below is the operation history of the to-do list document. As you can see, the operations are logged in the order they were executed. <figure className="image-container"> <img src={require("./images/OnboardingTasks.png").default} alt="Operation history in Connect" /> <figcaption> The operation history of the to-do list document, showing each change made. </figcaption> </figure> Now that we have some data in our document model, we can query it through the GraphQL API. ### Option 1: Query your document via the Switchboard API Button. Whenever you want to start a query from a document within Connect, you can open Switchboard by clicking the Switchboard icon in the top right-hand corner of the document editor interface. The Switchboard API button at the top of your document model will get you the complete state of your current document. This will prepopulate the Apollo Studio Sandbox with the correct DocumentID for your document model. <figure className="image-container"> <img src={require("./images/SwitchboardButton.png").default} alt="Switchboard button in document editor" /> <figcaption> The Switchboard button provides a direct link to the GraphQL API for the document. </figcaption> </figure> ### Option 2: Query your document by document ID In your Document Toolbar, you will find an icon to visit your operations history. At the top of the toolbar, you will find your document ID. Copy this ID to use it in the Switchboard API. <figure className="image-container"> <img src={require("./images/DocumentID.png").default} alt="Copy the DocumentID" /> <figcaption> You can copy your Document ID from your operations history. </figcaption> </figure> When you navigate to your Switchboard endpoint by adding `/graphql` to the end of your URL (e.g., http://localhost:4001/graphql, https://switchboard.phd/graphql, or add it to a custom domain), you can use this document ID to query the state of your document. The documentation on the left-hand side of the Apollo Sandbox will show you all the different fields that are available to query. <figure className="image-container"> <img src={require("./images/QueryDocumentID.png").default} alt="Apollo Studio with document query" /> <figcaption> The Apollo Studio Sandbox showing the available fields for querying a document. </figcaption> </figure> ### Option 3: Search for your document ID via GraphQL Alternatively, we can use our Reactor URL and endpoint to figure out the document ID. e.g., http://localhost:4001/graphql, https://switchboard.phd/graphql, or your custom https://switchboard.domain/graphql We can find out the ID of our document by querying the drive for its documents. Since we only have one document in our drive, this query will return the ID of our to-do list document. ```graphQL title="Document ID Query" query Query { ToDoList { ToDoList_documents { items { id name documentType revisionsList { scope revision } createdAtUtcIso lastModifiedAtUtcIso } } } } ``` This example query is structured to request all documents of type `ToDoList`. It extracts common metadata fields such as id, name, documentType, revisionsList, createdAtUtcIso, and lastModifiedAtUtcIso. ### Get the state of the document Once you've found your document via any of the three options above, you'll be able to query its state. The previous step queried for document metadata. Now query for the actual content of the document state. ```graphql title="Get the Document state" query getDocument($identifier: String!) { ToDoList { document(identifier: $identifier) { document { id name createdAtUtcIso lastModifiedAtUtcIso revisionsList { scope revision } state { global { items { id text checked } stats { total checked unchecked } } } } } } } ``` ```json title="Example variables" { "identifier": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af" } ``` This query will return the current state of the document, including all to-do items and stats. <figure className="image-container"> <img src={require("./images/OperationsQuery.png").default} alt="Executing a mutation for a to-do item in Apollo Studio" /> <figcaption> The Apollo Studio Sandbox showing the <code>addTodoItem</code> mutation. You can see the variables passed in and the response from the server. </figcaption> </figure> ## Mutate the state of a document Now that we know how to query the state of a document, we can start to write to it. To perform write operations, we use GraphQL Mutations. Mutations are similar to queries, but they are used to create, update, or delete data. For our To-do List, we'll want to add, check, and remove items. ### Adding a new to-do item Add a new item to the list. The document model for the to-do list has an `ADD_TODO_ITEM` operation, which translates to an `addTodoItem` mutation in GraphQL. To use this mutation, you need to provide the `docId` of the to-do list you want to modify, and the `text` and `id` for the new to-do item. We'll specify these via variables. Here is an example of how to structure the mutation: ```graphql title="example-add-mutation" mutation AddTodoItem($docId: PHID!, $input: ToDoList_AddTodoItemInput!) { ToDoList { addTodoItem(docId: $docId, input: $input) { id name revisionsList { scope revision } } } } ``` ```json title="example-variables" { "docId": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af", "input": { "text": "My new to-do from GraphQL", "id": "1" } } ``` Replace the example `docId` with the actual ID of your document. You can get this ID by querying as we did before. When you execute this mutation in Apollo Studio, it will add the new item to your to-do list. The response will return the updated document with its new revision. ### Deleting a to-do item To delete an item, you'll need its unique identifier. When you query for the to-do items in your list, each one will have an `id`. You'll use this `id` to specify which item to delete. The document model provides a `DELETE_TODO_ITEM` operation, which corresponds to a `deleteTodoItem` mutation. Here's how you can use it: ```graphql title="example-delete-mutation" mutation DeleteTodoItem($docId: PHID!, $input: ToDoList_DeleteTodoItemInput!) { ToDoList { deleteTodoItem(docId: $docId, input: $input) { id name revisionsList { scope revision } } } } ``` ```json title="example-variables" { "docId": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af", "input": { "id": "0.6325811781889789" } } ``` Make sure to replace the `docId` and `id` with the appropriate values for your document and the item you wish to delete. After executing this mutation, the specified to-do item will be removed from your list. ### Verifying the changes After performing a write mutation, you can verify that the change was successful in a couple of ways: 1. Query the document state again: Rerun the `document` query from earlier in this tutorial. You should see the new item in the list or the deleted item removed. 2. Check the Operation History: The operation history in Connect will show the new `ADD_TODO_ITEM` or `DELETE_TODO_ITEM` operation, along with who performed it and when. This provides a complete audit trail of all changes to the document. ### Next You can now read and write documents over the GraphQL API. To expose your own queries and mutations on top of this data, see [Using Subgraphs](/academy/Build/WorkWithData/UsingSubgraphs). --- ## Using subgraphs > Source: https://academy.vetra.io/academy/Build/WorkWithData/UsingSubgraphs Create and customize a subgraph, using the to-do list project as an example. This starts with the basics and adds more complex features as it goes. ## What is a subgraph? A subgraph in Powerhouse is a GraphQL-based modular data component that extends the functionality of your document models. While document models handle the core state and operations, subgraphs can: 1. Connect to external APIs or databases 2. Add custom queries and mutations 3. Automate interactions between different document models 4. Provide additional backend functionality ### Subgraphs can retrieve data from - The Reactor – The core Powerhouse data system or network node. - Relational Data Stores – Structured data storage for operational processes, offering real-time updates, for querying structured data. - Analytics Stores – Aggregated historical data, useful for insights, reporting and business intelligence. ### Subgraphs consist of - A schema — Which defines the GraphQL Queries and Mutations. - Resolvers — Which handle data fetching and logic. - Context Fields — Additional metadata that helps in resolving data efficiently. #### Additionally, context fields allow resolvers to access extra information, such as: - User authentication (e.g., checking if a user is an admin). - External data sources (e.g., analytics). ## Example: Implement a search subgraph based on data from the reactor In this example we implement a subgraph which allows to search through todo-list documents in a specific document drive. First we will generate the subgraph with the help of the Powerhouse CLI, then we will define the GraphQL schema and implement the resolvers and finally we will start the reactor and execute a query through the GraphQL Gateway. ### 1. Generate the subgraph Generate a new subgraph within the to-do list project you created in the previous chapters. Open your project and start your terminal. The Powerhouse Vetra toolkit has a command-line utility to create new subgraphs. ```bash title="Run the following command to generate a new subgraph" ph generate subgraph --name search-todos ``` ```bash title="Expected Output" FORCED: ./subgraphs/search-todos/index.ts FORCED: ./subgraphs/search-todos/resolvers.ts FORCED: ./subgraphs/search-todos/schema.ts ``` After generating the subgraph, build your project with a build step. ```bash title="Build your project" pnpm build ``` ### What happened? 1. A new subgraph was created in `./subgraphs/search-todos/` 2. The subgraph was automatically registered in your project's registry 3. Basic boilerplate code was generated with an example query If we now run `ph reactor` we will see the new subgraph being registered during the startup of the Reactor. > Registered /graphql/search-todos subgraph. ``` Initializing Subgraph Manager... > Registered /graphql/auth subgraph. > Registered /graphql/r subgraph. > Registered /graphql/analytics subgraph. > Registered /d/:drive subgraph. > Updating router > Registered /graphql supergraph > Registered /graphql/document-drive subgraph. > Registered /graphql/to-do-list subgraph. > Registered /graphql/search-todos subgraph. > Updating router > Registered /graphql supergraph ➜ Reactor: http://localhost:4001/d/powerhouse ``` ## 2. Building a search subgraph Now that we've generated our subgraph its time to define the GraphQL schema and implement the resolvers. Step 1: Define the schema in `subgraphs/search-todos/schema.ts` by creating the file: ```typescript export const schema: DocumentNode = gql` """ Subgraph definition """ type Query { searchTodos(driveId: String!, searchTerm: String!): [String!]! } `; ``` Step 2: Create resolvers in `subgraphs/search-todos/resolvers.ts`: ```typescript // subgraphs/search-todos/resolvers.ts export const getResolvers = (subgraph: BaseSubgraph) => { const reactorClient = subgraph.reactorClient; return { Query: { searchTodos: async ( parent: unknown, args: { driveId: string; searchTerm: string }, ) => { const children = await reactorClient.getOutgoingRelationships( args.driveId, "child", ); const todoItems: string[] = []; for (const doc of children.results) { if (doc.header.documentType !== "powerhouse/todo-list") { continue; } const todoDoc = doc as TodoListDocument; const amountEntries = todoDoc.state.global.items.filter((e) => e.text.includes(args.searchTerm), ).length; if (amountEntries > 0) { todoItems.push(doc.header.id); } } return todoItems; }, }, }; }; ``` WARNING: The resolver above returns data with no permission check. Custom subgraphs run with full access to the Reactor, so guarding reads, writes, and document creation is your responsibility. See [Enforcing Authorization in Subgraphs](../docs/03-BuildingUserExperiences/07-Authorization/05-EnforcingAuthorizationInSubgraphs.md) for the `assertCanRead` / `assertCanWrite` / `canReadDocument` patterns. ## 3. Testing the to-do list subgraph ### 3.1. Start the reactor To activate the subgraph, run: ```bash ph reactor ``` You should see the subgraph being registered in the console output: ``` > Registered /graphql/search-todos subgraph. ``` ### 3.2. Create some test data Before testing queries, create some to-do list documents with test data: 1. Start Connect ```bash ph connect ``` 1. Open Connect at `http://localhost:3000` in the browser 2. Add the 'remote' drive that is running locally via the (+) 'Add Drive' button. Add 'http://localhost:4001/d/powerhouse' 3. Create a new to-do list document 4. Add some test items: - "Learn about subgraphs" (leave unchecked) - "Build a to-do list subgraph" (mark as checked) - "Test the subgraph" (leave unchecked) ### 3.3. Access GraphQL playground Open your browser and go to: ```bash http://localhost:4001/graphql ``` ### 3.4. Test the queries Query 1: Search for Todos ```graphql query { searchTodos(driveId: "powerhouse", searchTerm: "test") } ``` You should get a list of the document Ids which contain the search term "Test". If you want to see the full state of your document use this query. ```graphql query GetDocument($identifier: String!) { ToDoList { document(identifier: $identifier) { document { state { global { items { checked id text } } } } } } } ``` ### 3.5. Test real-time updates To verify that your subgraph stays synchronized with document changes: 1. Keep the GraphQL playground open 2. In another tab, open your to-do list document in Connect 3. Add a new item or check/uncheck an existing item 4. Return to the GraphQL playground and re-run your queries 5. You should see the updated data immediately This demonstrates the real-time synchronization between the document model and the subgraph through event processing. TIP: Since you've gotten this far we'll explain a bit more in depth how the GraphQL API or Gateway works! ## 4. Working with the GraphQL Gateway The GraphQL Gateway is a GraphQL schema that combines multiple underlying GraphQL APIs, known as subgraphs, into a single, unified graph. This architecture allows different teams to work independently on their respective services (subgraphs) while providing a single entry point for clients or users to query all available data. ### 4.1 Key concepts - Subgraph: An independent GraphQL service with its own schema. Each subgraph typically represents a specific domain or microservice within a larger system. - Gateway/Router: A server that sits in front of the subgraphs. It receives client queries, consults the supergraph schema, and routes parts of the query to the relevant subgraphs. It then stitches the results back together before sending the final response to the client. ### 4.2 Benefits of using a supergraph - Federated Architecture: Enables a microservices-based approach where different teams can own and operate their services independently. - Scalability: Individual subgraphs can be scaled independently based on their specific needs. - Improved Developer Experience: Clients interact with a single, consistent GraphQL API, simplifying data fetching and reducing the need to manage multiple endpoints. - Schema Evolution: Subgraphs can evolve their schemas independently, and the supergraph can be updated without breaking existing clients, as long as breaking changes are managed carefully. - Clear Separation of Concerns: Each subgraph focuses on a specific domain, leading to more maintainable and understandable codebases. ### 4.3 Use the Powerhouse supergraph The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph. - Start the reactor: ```bash ph reactor ``` - Open the GraphQL editor in your browser: ``` http://localhost:4001/graphql ``` The supergraph allows you to both query & mutate data from the same endpoint. Example: Using the supergraph with to-do list documents 1. Create a todo document in the `powerhouse` drive using the `ToDoList` `createDocument` mutation: ```graphql mutation CreateTodoList($name: String!, $parentIdentifier: String) { ToDoList { createDocument(name: $name, parentIdentifier: $parentIdentifier) { id name } } } ``` Variables: ```json { "name": "My Test To-do List", "parentIdentifier": "powerhouse" } ``` This returns the document with its ID (e.g., `"abc123"`). Save this ID for the next steps. 2. Add some items to your to-do list using the `addTodoItem` mutation: ```graphql mutation AddTodoItem($docId: PHID!, $input: ToDoList_AddTodoItemInput!) { ToDoList { addTodoItem(docId: $docId, input: $input) { id name revisionsList { scope revision } } } } ``` Variables: ```json { "docId": "abc123", "input": { "text": "Learn about supergraphs" } } ``` This returns the updated document with its new revision. 3. Query the document state using the `document` query: ```graphql query GetTodoList($identifier: String!) { ToDoList { document(identifier: $identifier) { document { id name state { global { items { id text checked } } } } } } } ``` Variables: ```json { "identifier": "abc123" } ``` 4. Use the `searchTodos` subgraph query to search for items across your to-do lists: ```graphql query SearchTodos($driveId: String!, $searchTerm: String!) { searchTodos(driveId: $driveId, searchTerm: $searchTerm) } ``` Variables: ```json { "driveId": "powerhouse", "searchTerm": "supergraph" } ``` This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint. ## 5. What you built You now have a to-do list subgraph: an operational data store, event processing that keeps it in sync with the document model, and a supergraph that exposes it through a single GraphQL endpoint. ## Subgraphs are particularly useful for 1. Cross-Document Interactions: For example, connecting a to-do list with an Invoice document model: - When an invoice-related task is marked complete, update the invoice status - When an invoice is paid, automatically check off related tasks 2. External Integrations: - Sync tasks with external project management tools - Connect with notification systems - Integrate with analytics platforms 3. Custom Business Logic: - Implement complex task prioritization - Add automated task assignments - Create custom reporting functionality ### Future enhancements Bridge Processors and Subgraphs — Currently, there's a gap in how processors and subgraphs interact. Powerhouse might improve this in future updates. --- ## Building a processor > Source: https://academy.vetra.io/academy/Build/WorkWithData/BuildingAProcessor Processors are components that receive document operations from the reactor and perform side effects. While specialized processor types like [relational database processors](/academy/Build/WorkWithData/RelationalDbProcessor) exist, you can build a plain processor by implementing the `IProcessor` interface directly. In this tutorial you'll build a logging processor that prints a structured summary of every operation to the console. ## What is a processor? A processor implements two methods: - `onOperations(operations)` — called when document operations match the processor's filter - `onDisconnect()` — called when the processor is disconnected (for cleanup) The reactor calls your processor's `onOperations` method with a list of `OperationWithContext` items. Each item pairs an `Operation` (what happened) with an `OperationContext` (where it happened). ## Key types ```typescript IProcessor, ProcessorFilter, ProcessorRecord, ProcessorFactory, IProcessorHostModule, } from "@powerhousedao/reactor-browser"; ``` INFO: `@powerhousedao/reactor-browser` re-exports these types for convenience in browser environments. If you are working outside the browser (Node.js scripts, CLI tools, server-side code), import directly from `@powerhousedao/reactor`. ### `OperationWithContext` Each item your processor receives contains: `context` — where the operation happened: | Field | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------- | | `documentId` | `string` | The document that was modified | | `documentType` | `string` | e.g. `"powerhouse/todo-list"` | | `scope` | `string` | The scope (e.g. `"global"`, `"local"`) | | `branch` | `string` | The branch (e.g. `"main"`) | | `ordinal` | `number` | Global monotonically increasing ordinal for cross-document ordering | | `resultingState` | `string?` | JSON string of the document state after the operation | `operation` — what happened: | Field | Type | Description | | ---------------- | -------- | ---------------------------------------------------- | | `action` | `Action` | Contains `type` (e.g. `"ADD_TODO_ITEM"`) and `input` | | `index` | `number` | Position in the operation history | | `timestampUtcMs` | `string` | When the operation was created | | `hash` | `string` | Hash of the resulting document state | ### `ProcessorFilter` Determines which operations your processor receives. All fields are optional arrays — when provided, operations must match at least one value in each specified field. When a field is omitted, it matches everything. ```typescript type ProcessorFilter = { documentType?: string[]; // e.g. ["powerhouse/todo-list"] scope?: string[]; // e.g. ["global"] branch?: string[]; // e.g. ["main"] documentId?: string[]; // e.g. [""] for all documents }; ``` ## 1. Implement the processor Create `processors/operation-logger/index.ts`: ```typescript export class OperationLoggerProcessor implements IProcessor { private driveId: string; constructor(driveId: string) { this.driveId = driveId; console.log(`[OperationLogger] Initialized for drive: ${driveId}`); } async onOperations(operations: OperationWithContext[]): Promise<void> { for (const { operation, context } of operations) { console.log( `[OperationLogger] drive=${this.driveId}`, `doc=${context.documentId}`, `type=${context.documentType}`, `action=${operation.action.type}`, `index=${operation.index}`, `ordinal=${context.ordinal}`, `scope=${context.scope}`, `branch=${context.branch}`, ); } } async onDisconnect(): Promise<void> { console.log(`[OperationLogger] Disconnected from drive: ${this.driveId}`); } } ``` The processor is straightforward: it receives operations and logs a structured summary for each one. In a real-world scenario, you might send these to an external logging service, a webhook endpoint, or a monitoring system. ## 2. Write the processor factory The factory is responsible for creating processor instances. The reactor calls your factory once per drive. Create `processors/operation-logger/factory.ts`: ```typescript ProcessorRecord, ProcessorFilter, IProcessorHostModule, } from "@powerhousedao/reactor-browser"; export const operationLoggerProcessorFactory = (module: IProcessorHostModule) => async (driveHeader: PHDocumentHeader): Promise<ProcessorRecord[]> => { const filter: ProcessorFilter = { branch: ["main"], documentId: [""], scope: ["global"], // Omit documentType to receive operations for ALL document types }; const processor = new OperationLoggerProcessor(driveHeader.id); return [ { processor, filter, }, ]; }; ``` How the factory pattern works: 1. The outer function `(module: IProcessorHostModule) => ...` is called once at initialization. The `module` object provides access to shared resources like `analyticsStore`, `relationalDb`, and `config`. 2. The returned function `(driveHeader: PHDocumentHeader) => ProcessorRecord[]` is called once per drive. The `driveHeader` provides access to `driveHeader.id`, `driveHeader.name`, `driveHeader.documentType`, and other header fields. 3. Each factory can return multiple `ProcessorRecord` entries — useful when you want different filters for different aspects of processing (e.g., one processor per document type). ### Filter options explained | Field | Description | | -------------- | ------------------------------------------------------------------ | | `branch` | Which branches to monitor — usually `["main"]` for production data | | `documentId` | Specific document IDs, or `[""]` for all documents | | `scope` | `["global"]` for shared state, `["local"]` for user-specific state | | `documentType` | Document types to process — omit to match all types | ### Starting position By default, new processors catch up from the beginning — they replay all existing operations. You can change this by setting `startFrom` on the `ProcessorRecord`: ```typescript return [ { processor, filter, startFrom: "current", // Skip historical operations, only process new ones }, ]; ``` ## 3. Register the factory Your processor factory is automatically registered when it is included in your project's processor exports. After creating the files above, make sure they are exported from your `processors/index.ts`: ```typescript export { operationLoggerProcessorFactory } from "./operation-logger/factory.js"; ``` ## 4. Test it Start the reactor: ```bash ph reactor ``` Create or modify documents in the drive. You should see log output like: ``` [OperationLogger] Initialized for drive: powerhouse [OperationLogger] drive=powerhouse doc=abc123 type=powerhouse/todo-list action=ADD_TODO_ITEM index=0 ordinal=1 scope=global branch=main [OperationLogger] drive=powerhouse doc=abc123 type=powerhouse/todo-list action=ADD_TODO_ITEM index=1 ordinal=2 scope=global branch=main ``` ## Summary You've built a plain processor from scratch. The key concepts are: - `IProcessor` — the interface your processor implements (`onOperations`, `onDisconnect`) - `ProcessorFactory` — a function that creates `ProcessorRecord[]` per drive - `ProcessorFilter` — determines which operations your processor receives - `OperationWithContext` — the data your processor receives, pairing operations with their document context For processors that need a relational database, see the [Relational Database Processor](/academy/Build/WorkWithData/RelationalDbProcessor) tutorial, which builds on these concepts with database migrations and type-safe queries. --- ## Processor best practices > Source: https://academy.vetra.io/academy/Build/WorkWithData/ProcessorBestPractices This guide covers advanced patterns for processors that need to mutate documents or query indexed data. It builds on the concepts from [Building a Processor](/academy/Build/WorkWithData/BuildingAProcessor) — read that first if you haven't already. TIP: Before reading this guide, make sure you're familiar with the basics: - [Building a Processor](/academy/Build/WorkWithData/BuildingAProcessor) — processor interface, factories, and filters ## One-way data flow Processors should follow a one-way data flow: operations flow in via `onOperations`, and mutations flow out via `dispatch`. ![Processor data flow: operations in via onOperations, mutations out via dispatch](../docs/docs/images/processor-data-flow.png) The key principle: never block on a reactor operation from inside a processor. When a processor dispatches actions, the job is submitted asynchronously — the processor does not wait for it to complete. If the processor needs to react to the result, it will receive the resulting operations in a future `onOperations` call. This design keeps processors predictable, avoids circular dependencies, and prevents scenarios where a processor waits on work that depends on that same processor finishing. ## Dispatching actions with `dispatch` The `dispatch` API lets a processor mutate documents by executing actions. It is available on the `IProcessorHostModule` object passed to your factory. ```typescript interface IProcessorDispatch { execute( docId: string, branch: string, actions: Action[], signal?: AbortSignal, meta?: Record<string, unknown>, ): Promise<ProcessorDispatchResult>; } type ProcessorDispatchResult = { id: string; // Job ID status: string; // Job status at time of submission }; ``` Under the hood, `dispatch.execute()` calls `reactorClient.executeAsync()` — it submits the job to the reactor and returns immediately with the job info. The processor does not wait for the job to complete. ### Accessing `dispatch` in a factory Capture `module.dispatch` in your factory and pass it to your processor: ```typescript IProcessor, IProcessorDispatch, IProcessorHostModule, ProcessorRecord, ProcessorFilter, } from "@powerhousedao/reactor-browser"; export const myProcessorFactory = (module: IProcessorHostModule) => async (driveHeader: PHDocumentHeader): Promise<ProcessorRecord[]> => { const processor = new MyProcessor(module.dispatch); const filter: ProcessorFilter = { branch: ["main"], documentId: [""], documentType: ["powerhouse/invoice"], scope: ["global"], }; return [{ processor, filter }]; }; ``` ### Example: cross-document automation A processor that watches for approved invoices and dispatches a payment action to a separate document: ```typescript IProcessor, IProcessorDispatch, } from "@powerhousedao/reactor-browser"; export class InvoiceApprovalProcessor implements IProcessor { constructor( private dispatch: IProcessorDispatch, private paymentDocId: string, ) {} async onOperations(operations: OperationWithContext[]): Promise<void> { for (const { operation, context } of operations) { if ( operation.action.type === "SET_STATUS" && operation.action.input?.status === "approved" ) { await this.dispatch.execute(this.paymentDocId, "main", [ { type: "CREATE_PAYMENT", input: { invoiceId: context.documentId, amount: operation.action.input.amount, }, scope: "global", }, ]); } } } async onDisconnect(): Promise<void> {} } ``` The processor dispatches the `CREATE_PAYMENT` action and moves on. It does not wait for the payment document to be updated. If the processor needs to know the payment was created, it can subscribe to `powerhouse/payment` operations via its filter. ### Parameter reference | Parameter | Type | Required | Description | | --------- | ------------------------- | -------- | --------------------------------------------- | | `docId` | `string` | Yes | Target document ID | | `branch` | `string` | Yes | Branch to apply actions to (usually `"main"`) | | `actions` | `Action[]` | Yes | Actions to dispatch | | `signal` | `AbortSignal` | No | Cancellation signal | | `meta` | `Record<string, unknown>` | No | Additional metadata for the job | ### Why not `reactorClient`? WARNING: Do not use `reactorClient` methods directly from inside a processor. Use `dispatch` instead. Why: 1. Potential blocking. Methods like `reactorClient.execute()` wait for the job to reach `READ_READY` status before returning. This means the call could potentially wait on processors to finish their current batch — including the very processor making the call. 2. Unnecessary round-trip. The processor will receive the resulting operations through `onOperations` anyway. Waiting for the result synchronously adds latency without benefit. 3. One-way flow. Processors should be written with a one-way data flow: react to operations, dispatch new work, and move on. If you need the result of a dispatch, handle it in a future `onOperations` call — don't block waiting for it. Instead of: ```typescript // Bad: blocks until job completes const doc = await reactorClient.execute(docId, "main", actions); ``` Use: ```typescript // Good: submits and returns immediately await this.dispatch.execute(docId, "main", actions); ``` ## Querying data with `getReadModel` The `getReadModel` API lets a processor look up a registered read model by name. Read models are materialized views maintained by the reactor — they are updated as operations are written and provide efficient query access to indexed data. ```typescript getReadModel<T>(name: string): T ``` Pass the read model's `name` property and cast to the expected type. Throws an error if the read model is not found. ### Default read models The reactor registers several built-in read models that processors can access: | Name | Type | Description | | ----------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | | `"document-view"` | `IDocumentView` | Maintains document snapshots for reads; provides `get()`, `find()`, and consistency tracking | | `"document-indexer"` | `IDocumentIndexer` | Tracks document relationships (parent/child) and metadata | | `"processor-manager"` | `IProcessorManager` | Routes operations to registered processors | | `"subscription-notification"` | `SubscriptionNotificationReadModel` | Notifies subscription callbacks when documents change | For example, to look up a document snapshot from inside a processor: ```typescript const documentView = module.getReadModel<IDocumentView>("document-view"); ``` Custom read models registered via `IReadModelCoordinator` are also available by their `name` property. ### Example: querying indexed data A processor that checks a budget read model before dispatching a payment: ```typescript IProcessor, IProcessorDispatch, } from "@powerhousedao/reactor-browser"; interface IBudgetReadModel { getRemainingBudget(departmentId: string): Promise<number>; } export class BudgetCheckProcessor implements IProcessor { constructor( private dispatch: IProcessorDispatch, private budgetModel: IBudgetReadModel, ) {} async onOperations(operations: OperationWithContext[]): Promise<void> { for (const { operation, context } of operations) { if (operation.action.type !== "REQUEST_PAYMENT") continue; const { departmentId, amount } = operation.action.input; const remaining = await this.budgetModel.getRemainingBudget(departmentId); if (remaining >= amount) { await this.dispatch.execute(context.documentId, "main", [ { type: "APPROVE_PAYMENT", input: { departmentId, amount }, scope: "global", }, ]); } } } async onDisconnect(): Promise<void> {} } ``` The factory wires the read model: ```typescript export const budgetCheckProcessorFactory = (module: IProcessorHostModule) => async (driveHeader: PHDocumentHeader): Promise<ProcessorRecord[]> => { const budgetModel = module.getReadModel<IBudgetReadModel>("budget"); const processor = new BudgetCheckProcessor(module.dispatch, budgetModel); return [ { processor, filter: { branch: ["main"], documentId: [""], documentType: ["powerhouse/expense-report"], scope: ["global"], }, }, ]; }; ``` INFO: `getReadModel` throws if the read model is not registered. Ensure the read model is registered with the reactor before your processor factory runs. If the read model is optional, wrap the call in a try/catch in your factory and handle the missing case gracefully. ## `IProcessorHostModule` reference The `IProcessorHostModule` is passed to your factory's outer function and provides access to all processor APIs: ```typescript interface IProcessorHostModule { analyticsStore: IAnalyticsStore; relationalDb: IRelationalDb; processorApp: ProcessorApp; dispatch: IProcessorDispatch; getReadModel<T>(name: string): T; config?: Map<string, unknown>; } ``` | Field | Type | Description | | ---------------- | ------------------------ | ----------------------------------------------------- | | `analyticsStore` | `IAnalyticsStore` | Time-series analytics store for writing metrics | | `relationalDb` | `IRelationalDb` | Relational database for creating namespaced stores | | `processorApp` | `ProcessorApp` | The host application (`"connect"` or `"switchboard"`) | | `dispatch` | `IProcessorDispatch` | Fire-and-forget action dispatch (see above) | | `getReadModel` | `<T>(name: string) => T` | Read model lookup by name (see above) | | `config` | `Map<string, unknown>` | Optional processor-specific configuration | INFO: `@powerhousedao/reactor-browser` re-exports these types for convenience in browser environments. If you are working outside the browser (Node.js, CLI tools, server-side code), import directly from `@powerhousedao/reactor` or `@powerhousedao/shared`. ## Summary - Use `dispatch.execute()` to mutate documents from processors — never `reactorClient` directly - Use `getReadModel()` to query indexed data for lookups and validation - Design for one-way data flow: operations in via `onOperations`, mutations out via `dispatch` - Never block on reactor operations that might circle back to the processor pipeline - React asynchronously: if you need the result of a dispatch, handle it in a future `onOperations` call - Access all APIs through `IProcessorHostModule` in your factory function ### Related pages - [Building a Processor](/academy/Build/WorkWithData/BuildingAProcessor) — processor basics - [Relational Database Processor](/academy/Build/WorkWithData/RelationalDbProcessor) — database-backed processors - [Processor Migration Guide](/academy/Reference/Processors/ProcessorMigrationGuide) — migrating from the legacy strand-based API --- ## Relational database processor > Source: https://academy.vetra.io/academy/Build/WorkWithData/RelationalDbProcessor In this chapter you'll implement a Todo-List relational database processor. This processor receives operations from the reactor and can use `resultingState` (from the operation context) or data from the operations themselves to populate a database. What is a Relational Database Processor? A relational database processor is a specialized component that listens to document changes in your Powerhouse application and transforms that data into a traditional relational database format (like PostgreSQL, MySQL, or SQLite). This is incredibly useful for: - Analytics and Reporting: Running complex SQL queries on your document data - Integration: Connecting with existing business intelligence tools TIP: This tutorial builds on the plain processor concepts covered in [Building a Processor](/academy/Build/WorkWithData/BuildingAProcessor). If you are new to processors, start there first. INFO: The code examples below import from `@powerhousedao/reactor-browser`, which re-exports all reactor types for convenience in browser environments (editors, drive-apps, subgraphs). If you are working outside the browser — for example in a standalone Node.js script, CLI tool, or server-side processor — import directly from `@powerhousedao/reactor`. ## Generate the Processor To generate a relational database processor, run the following command: ```bash ph generate processor --name todo-indexer --type relationalDb --document-types powerhouse/todo-list ``` Breaking down this command: - `--processor todo-indexer`: Creates a processor with the name "todo-indexer" - `--processor-type relationalDb`: Specifies we want a relational database processor (vs other types like analytics or webhook processors) - `--document-types powerhouse/todo-list`: Tells the processor to only listen for changes to documents of type "powerhouse/todo-list" This command creates a processor named `todo-indexer` of type `relational database` that listens for changes from documents of type `powerhouse/todo-list`. What gets generated: - A processor class file (`processors/todo-indexer/index.ts`) - A database migration file (`processors/todo-indexer/migrations.ts`) - A factory file for configuration (`processors/todo-indexer/factory.ts`) - A schema file for TypeScript types (`processors/todo-indexer/schema.ts`) ## Define Your Database Schema Next, define your database schema in the `processors/todo-indexer/migration.ts` file. Understanding Database Migrations Migrations are version-controlled database changes that ensure your database schema evolves safely over time. They contain: - `up()` function: Creates or modifies database structures when the processor starts - `down()` function: Safely removes changes when the processor is removed This approach ensures your database schema stays in sync across different environments (development, staging, production). The migration file contains `up` and `down` functions that are called when the processor is added or removed, respectively. In the migration.ts file you'll find an example of the todo table default schema: ```ts export async function up(db: IRelationalDb<any>): Promise<void> { // Create table - this runs when the processor starts await db.schema .createTable("todo") // Creates a new table named "todo" .addColumn("task", "varchar(255)") // Text column for the task description (max 255 characters) .addColumn("status", "boolean") // Boolean column for completion status (true/false) .addPrimaryKeyConstraint("todo_pkey", ["task"]) // Makes "task" the primary key (unique identifier) .ifNotExists() // Only create if table doesn't already exist .execute(); // Execute the SQL command } export async function down(db: IRelationalDb<any>): Promise<void> { // Drop table - this runs when the processor is removed await db.schema.dropTable("todo").execute(); } ``` Design Considerations: - We're using `task` as the primary key, which means each task description must be unique - The `varchar(255)` limit ensures reasonable memory usage - The `boolean` status makes it easy to filter completed vs. incomplete tasks - Consider adding timestamps (`created_at`, `updated_at`) for audit trails in production applications ## Generate Database Types After defining your database schema, generate TypeScript types for type-safe queries and better IDE support: ```bash ph generate migration-file --path processors/todo-indexer/migrations.ts ``` Why Generate Types? TypeScript types provide several benefits: - Type Safety: Catch errors at compile time instead of runtime - IDE Support: Get autocomplete and IntelliSense for your database queries - Documentation: Types serve as living documentation of your database structure - Refactoring: Safe renaming and restructuring of database fields Check your `processors/todo-indexer/schema.ts` file after generation - it will contain the TypeScript types for your database schema. Example of generated types: ```ts // This is what gets auto-generated based on your migration export interface Database { todo: { task: string; status: boolean; }; } ``` ## Configure the Processor Filter This give you the opportunity to configure the processor filter in `processors/todo-indexer/factory.ts`: Understanding Processor Filters Filters determine which document changes your processor will respond to. This is crucial for performance and functionality: - Performance: Only process relevant changes to avoid unnecessary work - Isolation: Different processors can handle different document types - Scalability: Distribute processing load across multiple processors ```ts ProcessorRecord, IProcessorHostModule, ProcessorFilter, } from "@powerhousedao/reactor-browser"; export const todoIndexerProcessorFactory = (module: IProcessorHostModule) => async ( driveHeader: PHDocumentHeader, processorApp?: ProcessorApp, ): Promise<ProcessorRecord[]> => { // Create a namespace for the processor and the provided drive id // Namespaces prevent data collisions between different drives const namespace = TodoIndexerProcessor.getNamespace(driveHeader.id); // Create a namespaced db for the processor // This ensures each drive gets its own isolated database tables const store = await module.relationalDb.createNamespace<TodoIndexerProcessor>( namespace, ); // Create a filter for the processor // This determines which document changes trigger the processor const filter: ProcessorFilter = { branch: ["main"], // Only process changes from the "main" branch documentId: [""], // Process changes from any document ID ( = wildcard) documentType: ["powerhouse/todo-list"], // Only process todo-list documents scope: ["global"], // Process global changes (not user-specific) }; // Create the processor instance const processor = new TodoIndexerProcessor(namespace, filter, store); return [ { processor, filter, }, ]; }; ``` Filter Options Explained: - `branch`: Which document branches to monitor (usually "main" for production data) - `documentId`: Specific document IDs to watch ("\" means all documents) - `documentType`: Document types to process (ensures type safety) - `scope`: Whether to process global changes or user-specific ones ## Implement the Processor Logic Now implement the actual processor logic in `processors/todo-indexer/index.ts` by copying the code underneath: Understanding the Processor Lifecycle The processor has several key methods: - `initAndUpgrade()`: Runs once when the processor starts (perfect for running migrations) - `onOperations()`: Runs every time relevant document changes occur (this is where the main logic goes) - `onDisconnect()`: Cleanup when the processor shuts down What is `OperationWithContext`? Processors receive a flat list of `OperationWithContext[]` items. Each item carries both the operation and its context: - `context`: `documentId`, `documentType`, `scope`, `branch`, `ordinal` (global ordering), and `resultingState` (JSON string of the document state after the operation) - `operation`: `action` (with `type` and `input`), `index`, `timestampUtcMs`, `hash` ```ts export class TodoIndexerProcessor extends RelationalDbProcessor<DB> { // Generate a unique namespace for this processor based on the drive ID // This prevents data conflicts between different drives static override getNamespace(driveId: string): string { // Default namespace: `${this.name}_${driveId.replaceAll("-", "_")}` return super.getNamespace(driveId); } // Initialize the processor and run database migrations // This method runs once when the processor starts up override async initAndUpgrade(): Promise<void> { await up(this.relationalDb); // Run the database migration to create tables } // Main processing logic - handles incoming document changes // This method is called whenever there are new document operations override async onOperations( operations: OperationWithContext[], ): Promise<void> { // Early return if no changes to process if (operations.length === 0) { return; } // Process each operation for (const { operation, context } of operations) { // Insert a record for each operation into the database // This is a simple example - you might want more sophisticated logic await this.relationalDb .insertInto("todo") .values({ // Create a unique task identifier combining document ID, operation index, and type task: `${context.documentId}-${operation.index}: ${operation.action.type}`, status: true, // Default to completed status }) // Handle conflicts by doing nothing if the task already exists // This prevents duplicate entries if operations are replayed .onConflict((oc) => oc.column("task").doNothing()) .execute(); // Execute the database query } } // Cleanup method called when the processor disconnects // Use this for closing connections, clearing caches, etc. async onDisconnect() { // Add any cleanup logic here } } ``` ## Expose Data Through a Subgraph ### Generate a Subgraph Generate a new subgraph to expose your processor data: ```bash ph generate subgraph --name todo ``` What is a Subgraph? A subgraph is a GraphQL schema that exposes your processed data to clients. It: - Provides a standardized API for accessing your relational database data - Integrates with the Powerhouse supergraph for unified data access - Supports both queries (reading data) and mutations (modifying data) - Can join data across multiple processors and document types ### Configure the Subgraph Open `./subgraphs/todo/schema.ts` and configure the schema: ```ts export const schema: DocumentNode = gql` # Define the structure of a todo item as returned by GraphQL type TodoListEntry { task: String! # The task description (! means required/non-null) status: Boolean! # The completion status (true = done, false = pending) } # Define available queries type Query { todos(driveId: ID!): [TodoListEntry] # Get array of todos for a specific drive } `; ``` Open `./subgraphs/todo/resolvers.ts` and configure the resolvers: ```ts // subgraphs/search-todos/resolvers.ts export const getResolvers = (subgraph: BaseSubgraph) => { const reactorClient = subgraph.reactorClient; const relationalDb = subgraph.relationalDb; return { Query: { todos: { // Resolver function for the "todos" query // Arguments: parent object, query arguments, context, GraphQL info resolve: async (_: any, args: { driveId: string }) => { // Query the database using the processor's static query method // This gives us access to the namespaced database for the specific drive const todos = await TodoIndexerProcessor.query( args.driveId, relationalDb, ) .selectFrom("todo") // Select from the "todo" table .selectAll() // Get all columns .execute(); // Execute the query // Transform database results to match GraphQL schema return todos.map((todo) => ({ task: todo.task, // Map database "task" column to GraphQL "task" field status: todo.status, // Map database "status" column to GraphQL "status" field })); }, }, }, }; }; ``` ## Now query the data via the supergraph. Understanding the Supergraph The Powerhouse supergraph is a unified GraphQL endpoint that combines: - Document Models: Direct access to your Powerhouse documents - Subgraphs: Custom data views from your processors - Built-in APIs: System functionality like authentication and drives This unified approach means you can query document state AND processed data in a single request, which is perfect for building rich user interfaces. The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph. - Start the reactor: ```bash ph reactor ``` - This will return an endpoint, but you'll need to change the url of the endpoint to the following URL: ``` http://localhost:4001/graphql ``` The supergraph allows you to both query & mutate data from the same endpoint. Read more about [subgraphs](/academy/Build/WorkWithData/UsingSubgraphs) <details> <summary>Example: Complete Data Flow from Document Operations to Relational Database</summary> Understanding the Complete Data Pipeline This example demonstrates the entire data flow in a Powerhouse application: 1. Storage Layer: Create a drive (document storage container) 2. Document Layer: Create a todo document and add operations 3. Processing Layer: Watch the relational database processor automatically index changes 4. API Layer: Query both original document state AND processed relational data 5. Analysis: Compare the different data representations --- ### Step 1: Create a Drive (Storage Container) What's Happening: Every document needs a "drive" - think of it as a folder or database that contains related documents. This is where your todo documents will live. ```graphql mutation DriveCreation($name: String!) { addDrive(name: $name) { id slug name } } ``` Variables: ```json { "name": "tutorial" } ``` 💡 Behind the Scenes: This creates a new drive namespace. Your relational database processor will create isolated tables for this drive using the namespace pattern we defined earlier. --- ### Step 2: Create a Todo Document What's Happening: Now we're creating an actual todo list document inside our drive. This uses the document model we built in previous chapters. ```graphql mutation TodoDocument($driveId: String, $name: String!) { TodoList_createDocument(driveId: $driveId, name: $name) } ``` Variables: ```json { "driveId": "fc29ec1b-9934-410b-8682-4731b810d441", "name": "tutorial" } ``` Result: ```json { "data": { "TodoList_createDocument": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b" } } ``` 💡 Key Insight: The returned UUID (`72b73d31-4874-4b71-8cc3-289ed4cfbe2b`) is crucial - this is the document ID that will appear in our processor's database records, linking operations back to their source document. You will receive a different UUID. --- ### Step 3: Add Todo Items (Generate Operations) What's Happening: Each time we add a todo item, we're creating a new operation in the document's history. Our relational database processor is listening for these operations in real-time. ```graphql mutation AddTodo( $driveId: String $docId: PHID $input: TodoList_AddTodoItemInput ) { TodoList_addTodoItem(driveId: $driveId, docId: $docId, input: $input) } ``` Variables: ```json { "driveId": "fc29ec1b-9934-410b-8682-4731b810d441", "docId": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b", "input": { "text": "complete mutation" } } ``` Result: ```json { "data": { "TodoList_addTodoItem": 1 } } ``` 💡 What Happens Next: 1. Document Model: Stores the operation and updates document state 2. Reactor: Packages the operation as an `OperationWithContext` (with `documentId`, `documentType`, `scope`, etc.) and routes it to matching processors via `onOperations()` 3. Our Processor: Automatically receives the `OperationWithContext` and creates a database record 4. Database: Now contains: `"72b73d31-4874-4b71-8cc3-289ed4cfbe2b-0: ADD_TODO_ITEM"` 🔄 Repeat this step 2-3 times with different todo items to see multiple operations get processed. Each operation will have an incrementing revision number or index --- ### Step 4: Query Both Data Sources Dual data access: You can now query both the original document state and the processed relational data in a single GraphQL request. ```graphql query GetTodoList($docId: PHID!, $driveId: PHID) { TodoList { getDocument(docId: $docId, driveId: $driveId) { id name revision state { items { id text checked } } } } } ``` Variables: ```json { "driveId": "fc29ec1b-9934-410b-8682-4731b810d441", "docId": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b" } ``` Response: ```json { "data": { "todos": [ { "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-0: ADD_TODO_ITEM", "status": true }, { "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-1: ADD_TODO_ITEM", "status": true }, { "task": "72b73d31-4874-4b71-8cc3-289ed4cfbe2b-2: ADD_TODO_ITEM", "status": true } ], "TodoList": { "getDocument": [ { "state": { "items": [ { "text": "complete mutation" }, { "text": "add another todo" }, { "text": "Now check the data" } ] } } ] } } } ``` --- ### 🔍 Data Analysis: Understanding What You're Seeing Document Model Data (`ToDoList.getDocuments`): - ✅ Current State: Shows the final todo items as they exist in the document - ✅ User-Friendly: Displays actual todo text like "complete mutation" - ✅ Real-Time: Always reflects the latest document state - ❌ Limited History: Doesn't show how the document changed over time Processed Relational Data (`todos`): - ✅ Operation History: Shows each individual operation that occurred - ✅ Audit Trail: You can see the sequence (0, 1, 2) of operations - ✅ Analytics Ready: Perfect for counting operations, tracking changes - ✅ Integration Friendly: Standard SQL database that other tools can access - ❌ Less User-Friendly: Shows operation metadata rather than final state --- Key Differences: - Document Query: Gets the current state directly from the document model - Subgraph Query: Gets processed/transformed data from your relational database - Combined Power: You can query both in a single GraphQL request for rich UIs This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint. </details> ## Use the Data in Frontend Applications Integration Options Your processed data can now be consumed by any GraphQL client: - React: Using Apollo Client, urql, or Relay - Next.js: API routes, getServerSideProps, or app router - Mobile Apps: React Native, Flutter, or native iOS/Android - Desktop Apps: Electron, Tauri, or other frameworks - Third-party Tools: Any tool that supports GraphQL APIs ### React Hooks Coming Soon: This section will cover how to use React hooks to consume your subgraph data in React applications. For now, you can use standard GraphQL clients like Apollo or urql to query your supergraph endpoint. ### Next.js API Route Example Why API Routes? Next.js API routes are useful when you need to: - Add server-side authentication or authorization - Transform data before sending to the client - Implement caching or rate limiting - Proxy requests to avoid CORS issues - Add logging or monitoring ```ts // pages/api/todos.ts export default async function handler( req: NextApiRequest, res: NextApiResponse, ) { // Only allow GET requests for this endpoint if (req.method !== "GET") { return res.status(405).json({ message: "Method not allowed" }); } // Extract driveId from query parameters, default to "powerhouse" const { driveId = "powerhouse" } = req.query; try { // Query your subgraph or database directly // In production, you might want to add authentication headers here const response = await fetch("http://localhost:4001/graphql", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: ` query GetTodoList($driveId: String) { todoList(driveId: $driveId) { id name completed createdAt updatedAt } } `, variables: { driveId }, }), }); const data = await response.json(); // Return the todos array from the GraphQL response res.status(200).json(data.data.todoList); } catch (error) { // Log the error for debugging (in production, use proper logging) console.error("Failed to fetch todos:", error); // Return a generic error message to the client res.status(500).json({ error: "Failed to fetch todos" }); } } ``` ## Summary You've successfully created a relational database processor that: 1. ✅ Listens for document changes - Automatically detects when todo documents are modified 2. ✅ Stores data in a structured database - Transforms document operations into relational data 3. ✅ Provides type-safe database operations - Uses TypeScript for compile-time safety 4. ✅ Exposes data through GraphQL - Makes processed data available via a unified API 5. ✅ Can be consumed by frontend applications - Ready for integration with any GraphQL client This processor will automatically sync your document changes to the relational database, making the data available for complex queries, reporting, and integration with other systems. Real-World Applications: This pattern is commonly used for: - Analytics dashboards showing document usage patterns - Business intelligence reports on document data - Integration with existing enterprise systems - Search and filtering with complex SQL queries - Data archival and compliance requirements --- ## Publish your package > Source: https://academy.vetra.io/academy/Build/Launch/PublishYourProject WARNING: This guide assumes familiarity with building document models in Vetra Studio. Please start with the [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) or the [Document Model Creation](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema) section if you are new to building document models. This guide covers the process of building and publishing a Powerhouse package to NPM. INFO: - Powerhouse Package: A collection of modules published to NPM that can be installed on a server instance or locally. Organizations build packages for specific purposes or workflows. - Powerhouse Modules: The building blocks of your package—document models, editors, processors, or scripts. - Vetra Studio: The development hub where you assemble specifications for your package. Each module is defined through specification documents that drive code generation. - Powerhouse Drive-apps: Customized drive interfaces that enhance document functionality and workflows within a drive. ![Key Concepts](images/keyconcepts.png) ## 1. Building your project ### 1.1. Initialize your project Start by initializing a new Powerhouse project: ```bash ph init ``` You'll be prompted to name your project, which will become the package name when published to NPM. <details> <summary>Command not working? Did you install `ph-cmd`?</summary> The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. Install it globally using: ```bash pnpm install -g ph-cmd ``` Key commands include: - `ph vetra --watch` for launching Vetra Studio - `ph connect` for running Connect locally (alternative) - `ph switchboard` or `ph reactor` for starting the API service - `ph init` to start a new project - `ph help` to get an overview of all available commands </details> <details> <summary>How to use different branches?</summary> When using the Powerhouse CLI, you can access dev & staging branches for experimental features or bugfixes 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 latest | Switch all dependencies to latest stable versions | | ph use dev | Switch all dependencies to development versions | | ph use staging | Switch all dependencies to staging versions | Please be aware that these versions can contain bugs and experimental features that aren't fully tested. </details> ### 1.2. Launch Vetra Studio Launch Vetra Studio in interactive watch mode for development: ```bash ph vetra --interactive --watch ``` This mode provides: - Interactive confirmations before code generation - Dynamic reloading for document-models and editors - Live preview of your changes in Vetra Studio <details> <summary>Alternatively: Use Connect</summary> You can also use Connect for local development: ```bash ph connect ``` This opens Connect in your browser at `http://localhost:3000/`, providing a local Reactor for testing. </details> ### 1.3. Configure package details In Vetra Studio, navigate to the Package Details section of your Vetra Studio drive to configure: - Package name: Use the format `@your-org-ph/package-name` (the `-ph` suffix identifies Powerhouse ecosystem packages) - Description: A meaningful description of your package - Keywords: Search terms for discoverability - Version: Following semantic versioning (e.g., `1.0.0`) - Author and License information These details are stored in your `package.json` and a `manifest.json` file is automatically generated from this configuration. ```json { "name": "@your-org-ph/package-name", "version": "1.0.0", "author": "Your Name", "license": "AGPL-3.0-only", "publishConfig": { "access": "public" } } ``` ### 1.4. Build your modules With Vetra Studio running, build your package modules: 1. Document Models: Define your document model specifications in Vetra Studio. The state schema and operations are automatically generated into code. 2. Editors: Create editor specifications linked to your document models. Vetra generates the scaffolding code. 3. Reducers: Implement the state transition logic in the generated reducer files. 4. Unit Tests: Write tests for your reducer logic in the `tests/` directory. Run tests to verify your implementation: ```bash pnpm run test ``` ### 1.5. Verify your build Build your project to verify everything compiles correctly: ```bash pnpm build ``` This creates an optimized build output ready for distribution. Test the build locally: ```bash ph vetra --interactive --watch ``` Create documents of your defined types and verify all functionality works as expected. ### 1.6. Store in version control Initialize a git repository to track changes: ```bash git init git add . git commit -m "Initial commit" ``` ## 2. Publishing your project ### 2.1. Set up NPM organization Create an organization on [NPM](https://www.npmjs.com/) using the naming convention `@yourorganization-ph`: - The `-ph` suffix identifies Powerhouse ecosystem packages - Example: `@acme-ph` We recommend using a dedicated NPM account for your organization rather than a personal account. ### 2.2. Log in to NPM ```bash npm login ``` Follow the prompts in your terminal or browser to authenticate. ### 2.3. Version your package Use semantic versioning to update your package version. The `pnpm version` command will: - Update the `version` in `package.json` - Create a Git commit for the version change - Create a Git tag (e.g., `v1.0.1`) ```bash # Patch release (1.0.0 → 1.0.1) - bugfixes pnpm version patch # Minor release (1.0.1 → 1.1.0) - new features pnpm version minor # Major release (1.1.0 → 2.0.0) - breaking changes pnpm version major ``` ### 2.4. Push to Git Push your commits and version tag to your remote repository: ```bash git push origin main git push origin vX.Y.Z # Replace with your actual tag ``` ### 2.5. Publish to NPM ```bash pnpm publish ``` For scoped packages intended to be public, ensure your `package.json` includes the `publishConfig` shown earlier, or use: ```bash pnpm publish --access public ``` To publish a pre-release version: ```bash # Ensure your version reflects the pre-release (e.g., 1.1.0-beta.0) pnpm publish --tag beta ``` INFO: - Git Tags: Markers in your repository history (e.g., `v1.0.0`) created by `pnpm version` - NPM Dist-Tags: Labels pointing to published versions (`latest`, `beta`, `next`). When publishing without a tag, the version gets the `latest` tag by default. ::: ## 3. Installing your package Once published, install your package in any Powerhouse environment: ```bash ph install @your-org-ph/package-name ``` This makes your document models and editors available within that Powerhouse instance. ### Package Manager UI A visual package manager can be found in Connect's settings (bottom left settings wheel), allowing installation at the click of a button. ![package manager](images/package-installer.png) --- ## 4. Publishing to the Vetra Registry (v6.0.0-dev.153+) INFO: Starting with `ph-cmd` version 6.0.0-dev.153, packages can be published to the Vetra package registry using `ph publish`. This enables dynamic package loading — Connect can detect the required package from a document file and prompt the user to install it directly from the registry. This flow applies to newly created projects initialized with v6.0.0-dev.153 or later. Existing projects will need to be migrated. ### 4.1. Set up your environment Install or update the Powerhouse CLI: ```bash pnpm install -g ph-cmd@6.0.0-dev.153 ``` Create a new project pinned to this version: ```bash ph init --pnpm --version=6.0.0-dev.153 your-test-project ``` Start Vetra in watch mode: ```bash cd your-test-project && ph vetra --watch ``` ### 4.2. Build your package 1. Create a document model and editor in Vetra Studio. Using Claude is recommended for faster scaffolding. 2. Create an example document in Connect and export it — you will use this to test dynamic loading later. ### 4.3. Configure package metadata (first publish only) Before publishing for the first time, update two files: - `powerhouse.manifest.json` — set `name`, `description`, and `publisher` - `package.json` — update the `name` field to match Then create an account on the Vetra dev registry: ```bash npm adduser --registry=https://registry.dev.vetra.io ``` ### 4.4. Publish ```bash ph publish --registry=https://registry.dev.vetra.io ``` Your package will be available at: - Registry index: `https://registry.dev.vetra.io/` - Package page: `https://registry.dev.vetra.io/your-package-name` TIP: Bump the `version` field in `package.json` before every subsequent publish. ### 4.5. Test dynamic loading in Connect 1. Open your Connect instance on [staging.vetra.io](https://staging.vetra.io) (or use `https://connect.sharp-dove-96.vetra.io/`) 2. Create a local drive 3. Drag and drop the exported document into the drive 4. Connect will detect the required package and prompt you to install it from the registry 5. Once installed, open the document with your editor --- Congratulations on publishing your package! Your document models and editors are now available for installation across the Powerhouse ecosystem. --- ## Setup your environment > Source: https://academy.vetra.io/academy/Build/Launch/SetupEnvironment This guide sets up the Powerhouse CLI and configures a server machine to run Powerhouse services, for both development and production deployment. TIP: This guide covers VM/server-based deployment with direct installation. If you prefer containerized deployment, see the [Docker Deployment Guide](../docs/docs/05-DockerDeployment.md). Choose Docker if: You want the fastest path to production, prefer containerized workflows, or are deploying to cloud platforms. Choose Direct Installation if: You need maximum performance, want full control, or are setting up a dedicated server. ## Prerequisites Before you begin, ensure you have a Linux-based system (Ubuntu or Debian recommended), sudo privileges, and a stable internet connection. These are essential for the installation and configuration process. The system should have at least 1GB of RAM and 10GB of free disk space for optimal performance. While these are minimum requirements, more resources will provide better performance, especially when running multiple services. Also make sure you have your preferred domain registered and created subdomains for your Connect & Switchboard instances. <details> <summary>Setting up a Droplet (Digital Ocean) instance and connecting your domain</summary> This tutorial will guide you through the process of creating a new virtual private server (called a "Droplet") on DigitalOcean and then pointing your custom domain name to it. This will allow users to access your server using a memorable URL like `www.yourdomain.com`. Current Date: May 15, 2024 ## Part 1: Setting up your DigitalOcean droplet A Droplet is a scalable virtual machine that you can configure to host your websites, applications, or other services. ### Step 1: Sign up or log in to DigitalOcean - If you don't have an account, go to [digitalocean.com](https://digitalocean.com) and sign up. You'll likely need to provide payment information. - If you already have an account, log in. ### Step 2: Create a new droplet 1. From your DigitalOcean dashboard, click the green "Create" button in the top right corner and select "Droplets". 2. Choose an Image: - Distributions: Select a base Linux distribution like Ubuntu (a popular choice, e.g., Ubuntu 22.04 LTS), Fedora, Debian, etc. - Marketplace: You can also choose from pre-configured 1-Click Apps (e.g., WordPress, Docker, LAMP stack). This can save you setup time. For this general tutorial, we'll assume a base distribution. 3. Choose a Plan (Size): - Shared CPU: Good for smaller projects, development, or low-traffic sites. Options like "Basic" Droplets fall here. - Dedicated CPU: For production applications needing consistent performance (General Purpose, CPU-Optimized, Memory-Optimized, Storage-Optimized Droplets). - Start with a basic plan that fits your budget and expected needs; you can resize your Droplet later if necessary. 4. Choose a Datacenter Region: - Select a server location closest to your target audience to minimize latency. - For example, if your users are primarily in Europe, choose a European datacenter like Amsterdam, Frankfurt, or London. 5. Authentication: - SSH Keys (Recommended for security): If you have an SSH key pair, you can add your public key. This is more secure than using passwords. Click "New SSH Key" and paste your public key if it's not already added. - Password: If you choose this, create a strong root password. You'll use this to log in via SSH initially. 6. Additional Options (Customize as needed): - VPC Network: By default, your Droplet will be in your default VPC for the chosen region. You can change this if you have custom networking setups. - Monitoring: A free metrics monitoring service. It's a good idea to enable this. - User Data: Allows you to run initial configuration scripts when the Droplet is first created. - Backups (Recommended for production): Enable automated weekly backups for a small additional fee. - Volume (Additional Storage): Attach block storage if you need more disk space than the Droplet plan offers. 7. Finalize and Create: - Choose a Hostname: Give your Droplet a name (e.g., `my-web-server`). This is for your reference within DigitalOcean. - Add Tags (Optional): Organize your resources with tags. - Select Project: Assign the Droplet to a project. - Review your selections and click the "Create Droplet" button at the bottom. ### Step 3: Access your droplet It will take a minute or two for your Droplet to be provisioned. Once it's ready, its IP address will be displayed in your Droplets list. To log in via SSH: 1. Open a terminal (on macOS/Linux) or an SSH client like PuTTY (on Windows). You can also use Digital Ocean's web 'Console'. 2. Use one of these commands: ```bash # If using password authentication ssh root@YOUR_DROPLET_IP # If using SSH key for a specific user ssh your_user@YOUR_DROPLET_IP # If using a specific SSH key ssh -i /path/to/your/private_key root@YOUR_DROPLET_IP ``` 3. If you used a password, you'll be prompted to enter it. 4. If it's your first time logging in, you might be asked to change the root password. Now your Droplet is running! Now you can continue with the Powerhouse tutorial or any next steps. ### DNS configuration #### Option A: Using DigitalOcean's nameservers (recommended) 1. Add Your Domain to DigitalOcean: - Go to "Networking" → "Domains" - Enter your domain name (e.g., `yourdomain.com`) - Click "Add Domain" 2. Start with Updating Nameservers at Your Domain Registrar: - Log in to your domain registrar - Update nameservers to: ``` ns1.digitalocean.com ns2.digitalocean.com ns3.digitalocean.com ``` 3. Create DNS Records: - Root Domain (A Record): - TYPE: A - HOSTNAME: @ - WILL DIRECT TO: Your Droplet's IP - TTL: 3600 - WWW Subdomain (A Record): - TYPE: A - HOSTNAME: www - WILL DIRECT TO: Your Droplet's IP - TTL: 3600 - Connect Subdomain (A Record): - TYPE: A - HOSTNAME: connect - WILL DIRECT TO: Your Droplet's IP - TTL: 3600 - Switchboard Subdomain (A Record): - TYPE: A - HOSTNAME: switchboard - WILL DIRECT TO: Your Droplet's IP - TTL: 3600 #### Option B: Using your existing nameservers (NS locked) 1. Just Create DNS Records at Your Registrar: - Root Domain (A Record): - TYPE: A - HOSTNAME: @ - VALUE: Your Droplet's IP - TTL: 3600 - WWW Subdomain (A Record): - TYPE: A - HOSTNAME: www - VALUE: Your Droplet's IP - TTL: 3600 - Connect Subdomain (A Record): - TYPE: A - HOSTNAME: connect - VALUE: Your Droplet's IP - TTL: 3600 - Switchboard Subdomain (A Record): - TYPE: A - HOSTNAME: switchboard - VALUE: Your Droplet's IP - TTL: 3600 Note: DNS changes may take up to 48 hours to propagate globally. ### Verify configuration 1. Use DNS lookup tools to verify your records: ```bash dig +short yourdomain.com dig +short www.yourdomain.com dig +short connect.yourdomain.com dig +short switchboard.yourdomain.com ``` 2. All should return your Droplet's IP address Congratulations! You have successfully set up your DigitalOcean Droplet and configured your domain. Your server is now ready to host your Powerhouse services. </details> <details> <summary> Setting up an EC2 instance and connecting your domain </summary> This tutorial will guide you through the process of assigning a static IP (Elastic IP) to your EC2 instance and configuring your domain to point to it. Current Date: May 15, 2024 - Make sure your region is set to eu-west-1 (Ireland) - Name your instance something like `cloud-server` or your project's name - Select Ubuntu 24.04 LTS - Architecture 64-bit (x86) - Scroll down to Instance type and select t2.medium (recommended) - 2 vCPUs and 4 GiB of memory are the recommended minimum specs - For larger projects or higher load, consider t2.large or t2.xlarge - Create a new key pair and save it in a secure location from which you can connect to your instance with the SSH client later. - Configure the security group to allow inbound traffic: - SSH (Port 22) from your IP address - HTTP (Port 80) from anywhere - HTTPS (Port 443) from anywhere - Custom TCP (Port 8442) for Connect - Custom TCP (Port 8441) for Switchboard - Launch the instance WARNING: Make sure to keep your key pair file (.pem) secure and never share it. Without it, you won't be able to access your instance. Also, consider setting up AWS IAM roles and policies for better security management. ## Part 1: Assigning a static IP to EC2 instance ### Step 1: Allocate elastic IP 1. Navigate to the EC2 service in the AWS console 2. Choose "Elastic IPs" from the navigation pane 3. Select "Allocate new address" 4. Select the VPC where your EC2 instance is located 5. Click "Allocate" ### Step 2: Associate elastic IP 1. Go back to the EC2 console and select your instance 2. From the "Networking" tab, expand "Network interfaces" 3. Note the "Interface ID" of the network interface 4. Select the "Interface ID" to manage its IP addresses 5. Choose "Actions", then "Manage IP Addresses" 6. Find the Elastic IP you allocated and click "Associate" ## Part 2: DNS configuration ### Option A: Using AWS Route 53 (recommended) 1. Add Your Domain to Route 53: - Go to Route 53 → "Hosted zones" - Click "Create hosted zone" - Enter your domain name (e.g., `yourdomain.com`) - Click "Create" 2. Update Nameservers at Your Domain Registrar: - Log in to your domain registrar - Update nameservers to the ones provided by Route 53 - They will look like: ``` ns-1234.awsdns-12.org ns-567.awsdns-34.com ns-890.awsdns-56.net ns-1234.awsdns-78.co.uk ``` 3. Create DNS Records: - Root Domain (A Record): - TYPE: A - HOSTNAME: @ - VALUE: Your Elastic IP - TTL: 3600 - WWW Subdomain (A Record): - TYPE: A - HOSTNAME: www - VALUE: Your Elastic IP - TTL: 3600 - Connect Subdomain (A Record): - TYPE: A - HOSTNAME: connect - VALUE: Your Elastic IP - TTL: 3600 - Switchboard Subdomain (A Record): - TYPE: A - HOSTNAME: switchboard - VALUE: Your Elastic IP - TTL: 3600 ### Option B: Using your existing nameservers 1. Create DNS Records at Your Registrar: - Root Domain (A Record): - TYPE: A - HOSTNAME: @ - VALUE: Your Elastic IP - TTL: 3600 - WWW Subdomain (A Record): - TYPE: A - HOSTNAME: www - VALUE: Your Elastic IP - TTL: 3600 - Connect Subdomain (A Record): - TYPE: A - HOSTNAME: connect - VALUE: Your Elastic IP - TTL: 3600 - Switchboard Subdomain (A Record): - TYPE: A - HOSTNAME: switchboard - VALUE: Your Elastic IP - TTL: 3600 1. Set Up DNS First: - Create A records for all subdomains before running the setup script - Point them to your EC2 instance's public IP address - Wait for DNS propagation before requesting SSL certificates ### Verify configuration 1. Use DNS lookup tools to verify your records: ```bash dig +short yourdomain.com dig +short www.yourdomain.com dig +short connect.yourdomain.com dig +short switchboard.yourdomain.com ``` 2. All should return your Elastic IP address Congratulations! You have successfully set up your EC2 instance with a static IP and configured your domain. Your server is now ready to host your Powerhouse services. </details> ## 1. Setting up a new cloud environment The `install` script provides a streamlined way to install the Powerhouse CLI tool and all its necessary dependencies. This script handles the installation of Node.js 24, pnpm, and the Powerhouse CLI itself. It's designed to work across different Linux distributions, though it's optimized for Ubuntu and Debian-based systems. It also prepares your machine for running Powerhouse services. It handles everything from package installation to service configuration, making the setup process straightforward and automated. This script is particularly useful for setting up new servers or reconfiguring existing ones. ### Installation 1. Run the setup script: ```bash curl -fsSL https://apps.powerhouse.io/install | bash # for macOS, Linux, and WSL ``` 2. After installation, source your shell configuration: ```bash source ~/.bashrc # or source ~/.zshrc if using zsh ``` 3. Verify that the Powerhouse CLI is ready to be installed in the next step: ```bash ph --version ``` You will see that `ph-cli` is not yet installed. This is expected, as it will be installed by the service setup command. 4. Create a project with `ph-init <projectname>`. 5. After creation, move into the project with `cd <projectname>`. Up next is the configurations of your services. ### Service configuration Next, run ```bash ph service setup ``` Follow the interactive prompts. This command installs the Powerhouse services (Connect and Switchboard) and guides you through their configuration. INFO: The script takes care of all the necessary service configuration automatically. It installs and configures Nginx as a reverse proxy, sets up SSL certificates, and configures the proxy settings for optimal performance. It also installs PM2 for process management and starts your services with the appropriate configuration based on your SSL choice. The Nginx configuration includes optimizations for WebSocket connections, static file serving, and security headers. PM2 is configured to automatically restart services if they crash and to start them on system boot. The setup command will prompt you for the following information: #### Package installation During this phase, you can enter package names that you want to install. For example, you might want to `ph install @powerhousedao/todo-demo-package` or other Powerhouse packages. This step is crucial for adding the specific functionality you need. You can also press Enter to skip this step and install packages later using the `ph install` command. #### Database configuration The script offers two options for database configuration: - Option 1: Local Database Sets up a local PostgreSQL database, which is ideal for development or small deployments. It automatically creates a database user with a secure random password and configures the database to accept local connections. This option is perfect for getting started quickly. - Option 2: Remote Database Allows you to connect to a remote PostgreSQL database by providing a connection URL in the format `postgres://user:password@host:port/db`. This is recommended for production environments. #### SSL configuration For SSL configuration, you have two choices: - Option 1: Let's Encrypt (Recommended for Production) This option requires you to provide a base domain (e.g., `powerhouse.xyz`) and subdomains for your services. The script will automatically obtain and configure SSL certificates for your domains. - Option 2: Self-signed Certificate This is suitable for development or testing. It uses your machine's hostname and generates a self-signed certificate. Browsers will show security warnings with this option. #### Domain setup You will be asked to enter your `connect` and `switchboard` subdomains to complete the setup. If you need more information, revisit the cloud provider setup sections at the beginning of this guide. #### Security features Security is a top priority. The script implements automatic SSL certificate management, generates secure database passwords, and configures security headers in Nginx, and sets up proper proxy settings to support WebSocket connections securely. ## 2. Verifying the setup After the installation is complete, it's important to verify that everything is working correctly. You can check the status of your services using PM2, verify the Nginx configuration, and ensure your SSL certificates are properly installed. This step is crucial for identifying any potential issues before they affect your users. 1. Check service status of switchboard and connect: ```bash ph service status ``` You can also use ```bash ph service start | stop | restart ``` to start | stop | restart switchboard and connect 2. View Nginx configuration: ```bash sudo nginx -t ``` 3. Check SSL certificates: ```bash sudo certbot certificates # if using Let's Encrypt ``` ## 3. Accessing the services Once everything is set up, you can access your services through the configured domains. If you chose Let's Encrypt, your services will be available at their respective subdomains. With a self-signed certificate, you'll access the services through your machine's hostname with the appropriate base paths. The services are configured to use HTTPS by default, ensuring secure communication. ### With Let's Encrypt - Connect: `https://connect.yourdomain.com` - Switchboard: `https://switchboard.yourdomain.com` ### With self-signed certificate - Connect: `https://your-hostname/connect` - Switchboard: `https://your-hostname/switchboard` ## 4. Troubleshooting When issues arise, there are several common problems you might encounter. - The "`ph`: command not found" error usually means you need to source your shell configuration file. - Nginx configuration errors can be investigated through the error logs, and service issues can be diagnosed using PM2 logs. - SSL certificate problems often relate to DNS settings or certificate paths. Understanding these common issues and their solutions will help you maintain a stable Powerhouse installation. ### Common issues 1. "`ph`: command not found" - Run `source ~/.bashrc` or restart your terminal - Verify that the `PNPM_HOME` environment variable is set correctly - Check if the `ph` binary exists in the `PNPM_HOME` directory 2. Nginx configuration errors - Check logs: `sudo tail -f /var/log/nginx/error.log` - Verify that all required modules are installed - Ensure that the SSL certificate paths are correct 3. Service not starting - Check PM2 logs: `pm2 logs` - Verify that the service ports are not in use - Check if the service has the required permissions 4. SSL certificate issues - Verify domain DNS settings - Check certificate paths in Nginx config - Ensure that the certificate files are readable by Nginx ## 5. Maintenance Regular maintenance is crucial for keeping your Powerhouse installation running smoothly. You can update services using the Powerhouse CLI, restart services through PM2, and monitor logs to ensure everything is functioning correctly. Regular maintenance helps prevent issues and ensures that your services are running with the latest security patches and features. ### Updating services ```bash ph update <package-name> ``` ### Restarting services ```bash ph service restart ``` ### Checking service status and logs ```bash ph service status ``` ## 6. Security notes Maintaining security is an ongoing process. It's essential to keep your database credentials secure and regularly update your SSL certificates. Regular monitoring of system logs helps identify potential security issues, and keeping your system and packages updated ensures you have the latest security patches. Consider implementing additional security measures such as firewall rules, intrusion detection systems, and regular security audits. ## 7. Backup Regular backups are crucial for data safety. The database can be backed up using pg_dump, and your configuration files can be archived using tar. These backups should be stored securely and tested regularly to ensure they can be restored if needed. Consider implementing an automated backup schedule and storing backups in multiple locations for redundancy. ### Database backup ```bash pg_dump -U powerhouse -d powerhouse > backup.sql ``` ### Configuration backup ```bash sudo tar -czf powerhouse-config.tar.gz /etc/powerhouse/ ``` ## 8. Best practices To get the most out of your Powerhouse installation, follow these best practices: 1. Regular Updates: Keep your system, packages, and services updated to the latest stable versions. 2. Monitoring: Set up monitoring for your services to detect issues early. 3. Documentation: Keep documentation of your configuration and any customizations. 4. Testing: Test your backup and restore procedures regularly. 5. Security: Regularly review and update your security measures. ## 9. Getting help If you encounter issues or need assistance, there are several resources available: 1. Documentation: Check the official Powerhouse documentation for detailed information. 2. Community: Join the Powerhouse community forums or chat channels. 3. Support: Contact Powerhouse support for professional assistance. 4. GitHub: Report issues or contribute to the project on GitHub. --- ## Configure your environment > Source: https://academy.vetra.io/academy/Build/Launch/ConfigureEnvironment After successfully setting up your server and installing the Powerhouse services using the `ph service setup` command as described in the [Setup Environment](../docs/docs/03-SetupEnvironment.md) guide, the next crucial step is to configure your environment. Powerhouse Connect reads its runtime configuration from `powerhouse.config.json`. Editing that file (or using the `ph connect config` CLI) is the recommended way to tune Connect's behavior — drives, renown integration, packages, log level, base path, and so on. Environment variables remain available as a legacy / CI mechanism for seeding the same fields at build time, but the JSON file is the source of truth at runtime. This guide walks you through the configuration model and shows you how to set values via JSON, the CLI, or env vars. ## Where the configuration lives A scaffolded Powerhouse project ships with `powerhouse.config.json` at the project root. Connect-specific settings live under the `connect` key: ```json { "$schema": "https://raw.githubusercontent.com/powerhouse-inc/powerhouse/main/packages/shared/clis/source-config.schema.json", "documentModelsDir": "./document-models", "editorsDir": "./editors", "studio": { "port": 3000 }, "reactor": { "port": 4001 }, "packages": [], "connect": { "app": { "basePath": "/", "logLevel": "info" }, "packages": { "externalEnabled": true }, "drives": { "allowAddDrive": true, "defaultDrives": [], "sections": { "remote": { "enabled": true, "allowAdd": true, "allowDelete": true }, "local": { "enabled": true, "allowAdd": true, "allowDelete": true } } }, "renown": { "url": "https://www.renown.id", "networkId": "eip155", "chainId": 1 } } } ``` The dist served by `ph connect build` deep-merges the project file with the schema defaults, so missing fields fall back automatically. ## Precedence When the dist `powerhouse.config.json` is built, values resolve in this order (lowest to highest): 1. Schema defaults (`DEFAULT_CONNECT_CONFIG`) — always present. 2. Env-var seeds — set-if-absent; only fill fields the source file does not specify (see [Build-time env-var seeds](#build-time-env-var-seeds) below for the list). 3. `powerhouse.config.json` (project root) — the operator's source of truth. 4. `ph connect build --json` — bulk override; applied last and beats source + seeds. 5. `ph connect build --<flag>` — individual flag overrides; applied above `--json` for the fields they cover. At runtime Connect always reads the resulting dist file as-is — it does not consult `process.env` for any field in the runtime schema. ## Editing the JSON ### Manually Open `powerhouse.config.json` in any editor and edit the `connect.` block. Save, then rebuild and restart: ```bash ph connect build ph service restart ``` ### Via `ph connect config` The CLI provides positional, flag, and bulk-JSON read/write access to every `connect.` field. The same surface works on `ph connect build` and `ph connect config` — pick whichever fits your workflow (build-time vs. live edit on a deployed dist). ```bash # Show the effective connect. block (list mode) ph connect config # Read a single value — positional <key>, or equivalently --get ph connect config connect.renown.url ph connect config --get connect.renown.url # Set a single value — positional <key> <value>, or equivalently a per-field flag ph connect config connect.renown.url "https://renown.staging.example" ph connect config connect.renown.chainId 137 ph connect config connect.drives.allowAddDrive false ph connect config --renown-url "https://renown.staging.example" ph connect config --renown-chain-id 137 ph connect config --allow-add-drive false # Bulk update via JSON patch (required for arrays/objects; useful for multi-field changes) ph connect config --json '{"renown":{"url":"https://x"},"drives":{"sections":{"remote":{"enabled":false}}}}' ``` Positional `<value>` is JSON-parsed first (so `137` → number, `false` → boolean) then schema-validated against the path. Strings without quotes pass through as bare strings. Arrays and objects should go through `--json` instead. Writes are dual-target: the source `powerhouse.config.json` is updated (next build picks it up) and, if the dist file exists, it is patched as well (the currently-served SPA picks up the change on its next refresh). Invalid types fail loudly before any write; both positional and `--json` payloads are Ajv-validated against the runtime schema. Mutually exclusive: positional `<key>` / `<key> <value>`, `--get`, `--json`, and any field flag can't be combined in one call — pick exactly one mode per invocation. ### At build time via positional / flags / JSON `ph connect build` accepts the same positional `<key> <value>` pair, per-field flags, and `--json` to bake values into the dist: ```bash # Positional override (single field) ph connect build connect.renown.url https://renown.staging.example # Per-field flags (combinable) ph connect build \ --renown-url https://renown.staging.example \ --renown-chain-id 137 \ --allow-add-drive false \ --remote-drives-enabled true \ --app-name "My Connect" ``` ```bash ph connect build --json '{"renown":{"url":"https://x"},"drives":{"allowAddDrive":false}}' ``` Overrides apply at dist-emit time and are baked into the dist file — operators see the resulting values when the container boots. ### Full flag matrix Every `connect.` field has a dedicated flag. Both `ph connect config` and `ph connect build` accept the same set. | `connect.` JSON path | Flag | Type | | -------------------------------------------- | ------------------------------ | -------------------------------------------- | | `connect.app.basePath` | `--base` | string | | `connect.app.logLevel` | `--log-level` | `debug \| info \| warn \| error` | | `connect.packages.externalEnabled` | `--external-packages` | boolean | | `connect.packages.registryUrl` | `--packages-registry` | string | | `connect.branding.appName` | `--app-name` | string | | `connect.branding.homeBackground` | `--home-background` | string (pass `""` to reset to bundled image) | | `connect.drives.allowAddDrive` | `--allow-add-drive` | boolean | | `connect.drives.defaultDrives` | `--default-drives-url` | comma-list → array of `{url, name, icon}` | | `connect.drives.preserveStrategy` | `--drive-preserve-strategy` | `preserve-all \| preserve-by-url-and-detach` | | `connect.drives.sections.remote.enabled` | `--remote-drives-enabled` | boolean | | `connect.drives.sections.remote.allowAdd` | `--remote-drives-allow-add` | boolean | | `connect.drives.sections.remote.allowDelete` | `--remote-drives-allow-delete` | boolean | | `connect.drives.sections.local.enabled` | `--local-drives-enabled` | boolean | | `connect.drives.sections.local.allowAdd` | `--local-drives-allow-add` | boolean | | `connect.drives.sections.local.allowDelete` | `--local-drives-allow-delete` | boolean | | `connect.renown.url` | `--renown-url` | string | | `connect.renown.networkId` | `--renown-network-id` | string | | `connect.renown.chainId` | `--renown-chain-id` | number | | _(bulk, any subset of fields)_ | `--json '{...}'` | partial `connect.` JSON blob | Plus `ph connect config --get <connect.path>` to read a single value, `ph connect config --dist-dir <path>` to point at a non-default dist location (overrides `PH_CONNECT_OUTDIR`). ## Configuring Connect's runtime values Connect's runtime configuration (everything under `connect.` in `powerhouse.config.json` — branding, drives, renown, app, packages) is set from one of three sources, in increasing precedence: 1. The source file `powerhouse.config.json` (project root) — hand-edited or generated by `ph init`. 2. `ph connect config --<field>` — dual-writes the value into the source file _and_ the running dist file, so the SPA picks it up on the next refresh without a rebuild. 3. `ph connect build --<field>` / `--json` — applies as a CLI override for the build, written into the emitted dist file. Environment variables are not a source for Connect's runtime config. The table above lists each `connect.` field together with its CLI flag. ### Docker deployments When deploying Connect's Docker image, the entrypoint applies the operator-supplied `PH_CONNECT_CONFIG_JSON` env var to the dist `powerhouse.config.json` at container start (operator-wins: concrete values override the baked file; `null`/omitted keep it; `connect.app.basePath` is ignored). This is purely an operator-time convenience — the SPA itself never reads env vars at runtime — and is documented in the [Docker Deployment guide](/academy/Build/Launch/DockerDeployment). ## Variables that stay as env vars The following are not runtime-config fields. They remain ordinary env vars because they are secrets, build-stamped metadata, or container-shape concerns: ```bash # Sentry (secrets / per-deploy) PH_SENTRY_AUTH_TOKEN="" PH_SENTRY_ORG="" PH_SENTRY_PROJECT="" PH_CONNECT_SENTRY_DSN="" PH_CONNECT_SENTRY_ENV="prod" PH_CONNECT_SENTRY_TRACING_ENABLED="false" PH_CONNECT_SENTRY_RELEASE="" # Build-stamped metadata PH_CONNECT_VERSION="..." # baked into the bundle at build time PH_CONNECT_CLI_VERSION="..." # baked into the bundle at build time # Container shape PORT=3001 ``` ## Configuring authorization (Switchboard) A critical aspect of your environment configuration is setting up authorization to control who can access your services and what they can do. As detailed in our dedicated [Switchboard Authorization](/academy/Build/BuildingUserExperiences/Authorization/Authorization) guide, you can manage access using authentication, supreme admin access, and document protection. Authorization is a Switchboard concern, not Connect. The same `powerhouse.config.json` carries both: ```json { "switchboard": { "auth": { "enabled": true, "admins": ["0x123...", "0x456..."] } } } ``` Or via env vars: ```bash AUTH_ENABLED=true ADMINS="0x123...,0x456..." DEFAULT_PROTECTION=true DOCUMENT_PERMISSIONS_ENABLED=true ``` For a complete understanding of how authorization (authentication, admin access, and document protection) works, please refer to the full [Authorization guide](/academy/Build/BuildingUserExperiences/Authorization/Authorization). ## Applying your changes Regardless of which method you use to update your configuration, the changes will not be applied until the service that consumes them restarts (or, in the case of the running SPA, the page is refreshed and re-fetches `/powerhouse.config.json`). ```bash ph service restart ``` This stops and restarts Connect and Switchboard so they pick up the new configuration. You can check the status with `ph service status`. ## Summary Configure Connect via `powerhouse.config.json` — edit the file directly, use `ph connect config <key> <value>`, or pass `--flag` / `--json` overrides to `ph connect build`. Env vars stay supported as build-time seeds for CI / docker workflows but are no longer the recommended interface. Secrets, build metadata, and container shape (sentry tokens, version stamps, `PORT`) remain as ordinary env vars. --- ## Docker deployment guide > Source: https://academy.vetra.io/academy/Build/Launch/DockerDeployment ## Introduction Powerhouse provides official Docker images for deploying your applications in containerized environments. This guide covers the available Docker images, how to use them with Docker Compose, and the environment variables you can configure. Docker deployment is ideal for: - Production environments that require consistent, reproducible deployments - Development teams that want to share a common environment - CI/CD pipelines that need automated testing and deployment - Cloud platforms like AWS ECS, Google Cloud Run, or Kubernetes TIP: This guide covers Docker-based deployment. If you prefer traditional VM/server deployment with direct installation, see the [Setup Environment Guide](../docs/docs/03-SetupEnvironment.md). Choose Docker if: You want the fastest path to production, prefer containerized workflows, or are deploying to cloud platforms. Choose Direct Installation if: You need maximum performance, want full control, or are setting up a dedicated server. ## Available Docker Images Powerhouse publishes three official Docker images to the GitHub Container Registry (ghcr.io): ### 1. Connect The Connect image provides the Powerhouse web application frontend with an embedded Nginx server. ``` ghcr.io/powerhouse-inc/powerhouse/connect ``` Available tags: - `latest` - Latest stable release - `dev` - Development builds - `staging` - Staging builds - `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`) ### 2. Switchboard The Switchboard image provides the backend API server that handles document synchronization and GraphQL endpoints. ``` ghcr.io/powerhouse-inc/powerhouse/switchboard ``` Available tags: - `latest` - Latest stable release - `dev` - Development builds - `staging` - Staging builds - `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`) ### 3. Academy The Academy image provides the documentation website. ``` ghcr.io/powerhouse-inc/powerhouse/academy ``` Available tags: - `latest` - Latest stable release - `dev` - Development builds - `staging` - Staging builds - `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`) ## Quick Start with Docker Compose The easiest way to run Powerhouse locally is using Docker Compose. Create a `docker-compose.yml` file or use the one provided in the repository: ```yaml name: powerhouse services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:dev environment: - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres - BASE_PATH=/ ports: - "127.0.0.1:3000:4000" networks: - powerhouse_network depends_on: postgres: condition: service_healthy switchboard: image: ghcr.io/powerhouse-inc/powerhouse/switchboard:dev environment: - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres ports: - "127.0.0.1:4000:4001" networks: - powerhouse_network depends_on: postgres: condition: service_healthy postgres: image: postgres:16.1 ports: - "127.0.0.1:5444:5432" environment: - POSTGRES_PASSWORD=postgres - POSTGRES_DB=postgres - POSTGRES_USER=postgres networks: - powerhouse_network healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 5s timeout: 3s retries: 3 networks: powerhouse_network: name: powerhouse_network ``` ### Running the Stack Start all services: ```bash docker compose up -d ``` View logs: ```bash docker compose logs -f ``` Stop all services: ```bash docker compose down ``` After starting, you can access: - Connect: http://localhost:3000 - Switchboard: http://localhost:4000 ## Configuring Connect at runtime Connect's runtime behavior is driven by `powerhouse.config.json` (the same file the build uses). For a Docker deployment you have three options: 1. Mount your own `powerhouse.config.json` as a Kubernetes ConfigMap / Secret (or a bind-mounted file) at `/var/www/html/project/powerhouse.config.json`. The SPA fetches it from `/powerhouse.config.json` on every page load, so post-deploy edits are visible after a refresh. 2. Pass a JSON payload via the `PH_CONNECT_CONFIG_JSON` env var. The entrypoint deep-merges it into the dist `powerhouse.config.json` at container start (operator-wins — concrete values in the payload override the baked file). 3. Edit the file at build time via `ph connect build --json '{...}'` or individual `--flag`s, baking the values into the image. For the full configuration model, precedence ladder, and the complete list of `connect.` fields, see the [Configure Environment](../docs/docs/04-ConfigureEnvironment.md) guide. ### Connect container env vars Connect's SPA reads runtime configuration from `/powerhouse.config.json`, never from env vars at runtime. The container entrypoint, however, can apply operator-supplied JSON to that file at startup (operator-wins) — equivalent to pre-running `ph connect config --json '{...}'` on the dist file. The SPA then reads the file as usual. #### Container shape and secrets | Variable | Description | Default | | ------------------------ | ----------------------------------------------------------- | -------- | | `PORT` | Port the nginx server listens on | `3001` | | `PH_CONNECT_BASE_PATH` | nginx base URL path | `/` | | `PH_CONNECT_CONFIG_JSON` | Runtime config JSON to merge into the dist file (see below) | _unset_ | | `DATABASE_URL` | PostgreSQL connection string (for Switchboard, not Connect) | Required | Sentry (DSN, environment label, tracing flag) is no longer set via per-field env vars — those live in `connect.sentry.` of `powerhouse.config.json` and ride through `PH_CONNECT_CONFIG_JSON` like every other runtime field. See the example below. #### `PH_CONNECT_CONFIG_JSON` (operator-wins) Set this env var to a JSON object that mirrors the `connect.` block of `powerhouse.config.json`. At container start the entrypoint deep-merges it into the dist file with operator-wins semantics: a concrete value in the env JSON overwrites the baked/mounted file; a `null` leaf (or an omitted key) keeps the file's value. Exception: `connect.app.basePath` is ignored — the base path is baked into the bundled asset URLs at build time (rebuild with `--base`, or use `--dynamic-base`). ```bash docker run \ -e PH_CONNECT_CONFIG_JSON='{ "connect": { "app": { "logLevel": "debug" }, "renown": { "url": "https://renown.staging.example", "chainId": 137 }, "drives": { "defaultDrives": [ { "url": "https://drive-a.example", "name": null, "icon": null } ], "sections": { "remote": { "enabled": true, "allowAdd": false } } }, "sentry": { "dsn": "https://prod-key@sentry.io/1", "env": "prod", "tracing": true } } }' \ connect:latest ``` The schema for the JSON object lives at `packages/builder-tools/connect-utils/runtime-config.schema.json` (also served as the `$schema` URL of any generated file). The same shape that `ph connect config --json` accepts is what `PH_CONNECT_CONFIG_JSON` accepts here. Invalid input behaviour: malformed JSON or a non-object payload aborts container startup with a clear stderr message rather than silently dropping the operator's intent. Migration from per-field env vars: the previous `PH_CONNECT_LOG_LEVEL`, `PH_CONNECT_DISABLE_ADD_DRIVE`, `PH_CONNECT_RENOWN_URL`, `PH_CONNECT_DEFAULT_DRIVES_URL`, `PH_CONNECT_SENTRY_DSN`, `PH_CONNECT_SENTRY_ENV`, `PH_CONNECT_SENTRY_TRACING_ENABLED`, and similar per-field variables are no longer wired. Wrap their values into a single `PH_CONNECT_CONFIG_JSON` payload using the JSON paths shown above. The Sentry release tag is build-time only — it stamps into the bundle via Vite's `define` from `WORKSPACE_VERSION` so it always matches the sourcemap upload tag CI used. ### Switchboard Environment Variables #### Core Configuration | Variable | Description | Default | | ----------------------------- | ------------------------------------------------------ | ---------- | | `PORT` | Port the server listens on | `3000` | | `PH_SWITCHBOARD_PORT` | Alias for PORT | `$PORT` | | `DATABASE_URL` | PostgreSQL or SQLite connection string | `"dev.db"` | | `PH_SWITCHBOARD_DATABASE_URL` | Alias for DATABASE_URL | `"dev.db"` | | `BASE_PATH` | Base URL path for the API | `"/"` | | `PH_PACKAGES` | Comma-separated list of packages to install at startup | `""` | #### Authentication | Variable | Description | Default | | ------------------------------ | ------------------------------------------------------------ | --------- | | `AUTH_ENABLED` | Enable authentication | `"false"` | | `ADMINS` | Comma-separated list of admin wallet addresses (full access) | `""` | | `DEFAULT_PROTECTION` | Make all new documents protected by default | `"false"` | | `DOCUMENT_PERMISSIONS_ENABLED` | Enable per-document permission management | `"false"` | #### Error Tracking & Monitoring | Variable | Description | Default | | -------------------------- | ------------------------------------------------------- | ------- | | `SENTRY_DSN` | Sentry DSN for error tracking | `""` | | `SENTRY_ENV` | Sentry environment name (e.g., "production", "staging") | `""` | | `PYROSCOPE_SERVER_ADDRESS` | Pyroscope server address for performance profiling | `""` | ## Installing Custom Packages Connect loads custom packages via the `PH_REGISTRY_PACKAGES` environment variable (written to a registry config at startup). Switchboard installs packages via `PH_PACKAGES`. ```yaml services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:dev environment: - PH_REGISTRY_PACKAGES=@powerhousedao/todo-demo-package,@powerhousedao/another-package ``` Packages are installed using the `ph install` command before the service starts. ## Image Architecture ### Connect Image The Connect image is based on Alpine Linux and includes: - Node.js and pnpm - Nginx with Brotli compression - The `ph-cmd` CLI tool - A pre-initialized Powerhouse project At startup, the entrypoint script: 1. Loads any packages specified in `PH_REGISTRY_PACKAGES` 2. Builds the Connect frontend with `ph connect build` 3. Configures and starts Nginx to serve the built files ### Switchboard Image The Switchboard image is based on Node.js 24 and includes: - pnpm package manager - The `ph-cmd` CLI tool - Prisma CLI for database migrations - A pre-initialized Powerhouse project At startup, the entrypoint script: 1. Installs any packages specified in `PH_PACKAGES` 2. Runs Prisma database migrations (if `PH_REACTOR_DATABASE_URL` is set) 3. Starts the Switchboard server via Node.js ## Production Considerations ### Using Specific Version Tags For production deployments, always use specific version tags instead of `latest` or `dev`: ```yaml services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:v1.0.0 switchboard: image: ghcr.io/powerhouse-inc/powerhouse/switchboard:v1.0.0 ``` ### Database Persistence For production, ensure your PostgreSQL data is persisted using volumes: ```yaml services: postgres: image: postgres:16.1 volumes: - postgres_data:/var/lib/postgresql/data environment: - POSTGRES_PASSWORD=your-secure-password - POSTGRES_DB=powerhouse - POSTGRES_USER=powerhouse volumes: postgres_data: ``` ### Health Checks The provided docker-compose.yml includes health checks for PostgreSQL. Services wait for the database to be healthy before starting, preventing connection errors during startup. ### Network Security The example configuration binds ports to `127.0.0.1` only: ```yaml ports: - "127.0.0.1:3000:4000" ``` This prevents direct external access. In production, use a reverse proxy (like Nginx or Traefik) to: - Terminate SSL/TLS - Handle load balancing - Provide additional security headers ### Environment File For better security, use a `.env` file instead of hardcoding credentials: ```bash # .env POSTGRES_PASSWORD=your-secure-password DATABASE_URL=postgres://powerhouse:your-secure-password@postgres:5432/powerhouse ``` ```yaml services: switchboard: image: ghcr.io/powerhouse-inc/powerhouse/switchboard:latest env_file: - .env ``` ## Troubleshooting ### Container Won't Start Check the logs for errors: ```bash docker compose logs connect docker compose logs switchboard ``` ### Database Connection Issues Ensure the database is ready before services start: ```bash docker compose logs postgres ``` Verify the `DATABASE_URL` format: ``` postgres://user:password@host:port/database ``` ### Package Installation Fails If custom packages fail to install, check: 1. Package name is correct 2. Network connectivity from container 3. Container has access to npm registry ### Permission Issues If you encounter permission issues with volumes: ```bash # Fix ownership sudo chown -R 1000:1000 ./data ``` ## Building Custom Images You can extend the official images for custom deployments: ```dockerfile FROM ghcr.io/powerhouse-inc/powerhouse/connect:latest # Install additional packages at build time RUN ph install @powerhousedao/my-custom-package # Add custom configuration COPY my-nginx.conf /etc/nginx/nginx.conf.template ``` Build and push your custom image: ```bash docker build -t my-registry/my-connect:latest . docker push my-registry/my-connect:latest ``` ## Next Steps - Learn about [Environment Configuration](../docs/docs/04-ConfigureEnvironment.md) for more detailed setup options - Explore [Publishing Your Project](../docs/docs/02-PublishYourProject.md) to create your own packages - Check the [Setup Environment Guide](../docs/docs/03-SetupEnvironment.md) for VM-based deployments --- ## Example use-cases > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/Overview Explore real-world examples of applications built with the Powerhouse ecosystem. Each use-case provides a complete walkthrough from project setup to a fully functional application. <div className={styles.learningPath} style={{ gridTemplateColumns: 'repeat(3, 1fr)' }}> <div className={styles.pathCard}> <div className={styles.cardHeader}> <h3 className="card-title"> <img src="/img/academy/icons/Editor.svg" alt="" className={styles.titleIcon} /> Chatroom </h3> </div> <div className={styles.cardContent}> <p style={{ fontSize: "0.9rem", color: "var(--ifm-color-content-secondary)", marginBottom: "1rem", }} > Build a real-time chat application with message posting and emoji reactions. Learn document models, reducers, and real-time synchronization. </p> <a href="/academy/Build/ExampleUsecases/Chatroom/CreateNewPowerhouseProject" className="path-button" > Start tutorial </a> </div> </div> <div className={styles.pathCard}> <div className={styles.cardHeader}> <h3 className="card-title"> <img src="/img/academy/icons/Editor.svg" alt="" className={styles.titleIcon} /> Todo List </h3> </div> <div className={styles.cardContent}> <p style={{ fontSize: "0.9rem", color: "var(--ifm-color-content-secondary)", marginBottom: "1rem", }} > The reference implementation built across the Manual Todo tutorial and Mastery Track — clone the finished repo and compare against your work. </p> <a href="/academy/Build/ExampleUsecases/TodoList/TodoList" className="path-button" > View reference </a> </div> </div> <div className={styles.pathCard}> <div className={styles.cardHeader}> <h3 className="card-title"> <img src="/img/academy/icons/Data.svg" alt="" className={styles.titleIcon} /> Vetra Package Library </h3> </div> <div className={styles.cardContent}> <p style={{ fontSize: "0.9rem", color: "var(--ifm-color-content-secondary)", marginBottom: "1rem", }} > Explore the Vetra package library and learn how to leverage existing packages in your projects. </p> <a href="/academy/Build/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary" className="path-button" > Explore library </a> </div> </div> </div> --- ## Create a new chatroom project > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/Chatroom/CreateNewPowerhouseProject TIP: 📦 Reference Code: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo) This tutorial has a complete reference implementation available. You can: - View the complete code for each step - Clone and compare your implementation - Use `git diff` to compare your code with the reference ::: <details> <summary>📖 How to use this tutorial</summary> This tutorial is designed for you to build your own project from scratch while having access to reference code. ### Setup: Create your project and connect to tutorial repo 1. Create your project following the tutorial: ```bash mkdir ph-projects cd ph-projects ph init # When prompted, enter project name: ChatRoom cd ChatRoom ``` 2. Add the tutorial repository as a remote to access reference code: ```bash git remote add tutorial https://github.com/powerhouse-inc/chatroom-demo.git git fetch tutorial --prune ``` 3. Create your own branch to keep your work organized: ```bash git checkout -b my-chatroom-project ``` Now you have access to the complete reference implementation while working on your own code! ### Compare your work with the reference At any point, compare what you've built with the reference: ```bash # Compare your current work with the reference git diff tutorial/main # Compare specific files git diff tutorial/main -- package.json ``` ### If you get stuck Reset your code to match the reference: ```bash # Reset to reference (WARNING: loses your changes) git reset --hard tutorial/main ``` </details> ## Overview This tutorial guides you through creating a ChatRoom application using Powerhouse. A Powerhouse project primarily consists of a document model and its editor. The ChatRoom demonstrates real-time collaboration features where users can post messages and react with emojis. ## Prerequisites - Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd` - Node.js 24 and a package manager (pnpm or npm) installed - Visual Studio Code (or your preferred IDE) - Terminal/Command Prompt access If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/Build/GettingStartedBuilding/Prerequisites) ## Before you begin 1. Open your terminal (either your system terminal or IDE's integrated terminal) 2. Optionally, create a folder first to keep your Powerhouse projects: ```bash mkdir ph-projects cd ph-projects ``` 3. Ensure you're in the correct directory before running the `ph init` command. In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter. ```bash you@yourmachine:~/ph-projects % ph init ? What is the project name? ‣ ChatRoom ``` Once the project is created, you will see the following output: ```bash Initialized empty Git repository in /Users/you/ph-projects/ChatRoom/.git/ The installation is done! ``` Navigate to the newly created project directory: ```bash cd ChatRoom ``` ## Develop your document model in Vetra Studio Vetra Studio is the builder's orchestration hub for assembling all specifications needed for your package. It provides a Vetra Studio Drive to access, manage, and share document model specifications, editors, and data integrations—all through a visual interface. For deeper coverage, see the [Vetra Studio documentation](/academy/GetStarted/VetraStudio). Once in the project directory, run the `ph vetra --watch` command to start a Vetra Studio Drive where you'll be defining your specifications. ```bash ph vetra --watch ``` The host application for Vetra Studio will start and you will see the following output: ```bash ℹ [reactor-api] [package-manager] Loading packages: @powerhousedao/vetra ℹ [reactor-api] [server] WebSocket server available at /graphql/subscriptions ℹ [reactor-api] [graphql-manager] Registered /graphql/system subgraph. ℹ [reactor-api] [graphql-manager] Registered /graphql supergraph ℹ [reactor-api] [server] MCP server available at http://localhost:4001/mcp Switchboard initialized ➜ Drive URL: http://localhost:4001/d/vetra-bac239dd ➜ Local: http://localhost:3000/ ➜ Network: use --host to expose ➜ press h + enter to show help ``` A new browser window will open when visiting localhost and you will see the Vetra Studio Drive. 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 the Document Models 'Add new specification' button. Name your document `ChatRoom` (PascalCase, no spaces or hyphens). Pay close attention to capitalization, as it influences code generation. If you've followed the steps correctly, you'll have an empty `ChatRoom` document where you can define the 'Document Specifications'. <details> <summary>Alternatively: Develop a single document model in Connect</summary> Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document. ```bash ph connect ``` The Connect application will start and you will see the following output: ```bash ➜ Local: http://localhost:3000/ ➜ Network: http://192.168.5.110: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. TIP: If your local drive is not present, navigate to Settings in the bottom left corner. Settings > Danger Zone > Clear Storage. Clear the storage of your localhost application as it might have an old session cached. Move into your local drive. Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. Name your document `ChatRoom` (PascalCase, no spaces or hyphens). </details> ## Verify your setup At this point, your project structure should include: - Empty `document-models/`, `editors/`, `processors/`, and `subgraphs/` directories - Configuration files: `powerhouse.config.json`, `powerhouse.manifest.json` - Package management files: `package.json`, `pnpm-lock.yaml` - Build configuration: `tsconfig.json`, `vite.config.ts`, `vitest.config.ts` ## Up next In the next tutorial, you will learn how to design your document model and export it to be later used in your Powerhouse project. --- ## Write the document specification > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/Chatroom/DefineChatroomDocumentModel TIP: 📦 Reference Code: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo) This tutorial step has a corresponding implementation in the repository. After completing this step, your project will have a document model specification with: - Document model specification files (`chat-room.json`, `schema.graphql`) - Auto-generated TypeScript types and action creators - Reducer scaffolding ready for implementation ::: <details> <summary>📖 How to use this tutorial</summary> Prerequisites: Complete step 1 and set up the tutorial remote (see previous step). ### Compare your generated code As Vetra generates code automatically, compare with the reference: ```bash # Compare all generated files with the reference git diff tutorial/main -- document-models/chat-room/ # View a specific file from the reference git show tutorial/main:document-models/chat-room/schema.graphql ``` ### Visual comparison with GitHub Desktop After making a commit, use GitHub Desktop for visual diff: 1. Branch menu → "Compare to Branch..." 2. Select `tutorial/main` 3. Review all file differences in the visual interface See step 1 for detailed GitHub Desktop instructions. </details> In this tutorial, you will learn how to define the specifications for a ChatRoom document model within Vetra Studio using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project. If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification. Before you start, make sure you have Vetra Studio running locally with the command: ```bash ph vetra --watch ``` ## ChatRoom document specification Make sure you have named your document model `ChatRoom` (PascalCase, no spaces or hyphens). Pay close attention to capitalization, as it influences code generation. We use the GraphQL Schema Definition Language (SDL) to define the schema for the document model. Below, you can see the SDL for the `ChatRoom` document model. INFO: This schema defines the data structure of the document model and the types involved in its operations. Documents 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. <details> <summary>State schema of our ChatRoom</summary> ```graphql type ChatRoomState { id: OID! name: String! description: String createdAt: DateTime createdBy: ID messages: [Message!]! } type Message { id: OID! sender: Sender! content: String sentAt: DateTime! reactions: [Reaction!] } type Sender { id: ID! name: String avatarUrl: URL } type Reaction { type: ReactionType! reactedBy: [ID!]! } enum ReactionType { THUMBS_UP THUMBS_DOWN LAUGH HEART CRY } ``` </details> <details> <summary>Messages Module: Operations for ChatRoom Messages</summary> ```graphql # Add a new message to the chat-room input AddMessageInput { messageId: OID! sender: SenderInput! content: String! sentAt: DateTime! } # Sender information for a message input SenderInput { id: ID! name: String avatarUrl: URL } # Add an emoji reaction to a message input AddEmojiReactionInput { messageId: OID! reactedBy: ID! type: ReactionType! } # Remove an emoji reaction from a message input RemoveEmojiReactionInput { messageId: OID! senderId: ID! type: ReactionType! } ``` </details> <details> <summary>Settings Module: Operations for ChatRoom Settings</summary> ```graphql # Edit the chat-room name input EditChatNameInput { name: String } # Edit the chat-room description input EditChatDescriptionInput { description: String } ``` </details> ## Define the document model specification To define the document model, you need to open the document model editor in Vetra Studio. ### Steps to define your document model: 1. In Vetra Studio, click on 'ChatRoom' Document to open the document model specification editor. 2. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields. In the Document Type field, type `powerhouse/chat-room` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification. ![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 template with the SDL defined in the State Schema section above. Only copy and paste the types, leaving the inputs for the next step. You can press the 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language. 4. Verify that your Global State Initial Value looks like this: ```json { "ID": "", "name": "", "description": null, "createdAt": null, "createdBy": null, "messages": [] } ``` 5. Below the editor, find the input field `Add module`. Create the first module for message-related operations. Name the module `messages`. Press enter. 6. Now there is a new field, called `Add operation`. Here you will add each input operation to the module, one by one. 7. Inside the `Add operation` field, type `ADD_MESSAGE` and press enter. A small editor will appear underneath with an empty input type that you need to fill. Copy the `AddMessageInput` and `SenderInput` from the Messages Module section and paste them in the editor: ```graphql input AddMessageInput { messageId: OID! sender: SenderInput! content: String! sentAt: DateTime! } input SenderInput { id: ID! name: String avatarUrl: URL } ``` 8. Add the remaining message operations to the `messages` module: `ADD_EMOJI_REACTION` and `REMOVE_EMOJI_REACTION`. Note that you only need to add the operation name (e.g., `ADD_EMOJI_REACTION`) without the `Input` suffix—it will be generated automatically. 9. Add reducer exceptions to the `ADD_MESSAGE` operation for validation: `MessageContentCannotBeEmptyError` and `MessageNotFoundError`. These will be used later to validate messages. 10. Create a second module called `settings` for the chat room configuration operations. 11. Add the settings operations to the `settings` module: `EDIT_CHAT_NAME` and `EDIT_CHAT_DESCRIPTION`. 12. In the meantime, Vetra has been keeping an eye on your inputs and started code generation in your directory. In your terminal you will also find any validation errors that help you to identify missing specifications. ## Verify your document model generation If you have been watching the terminal in your IDE you will see that Vetra has been tracking your changes and scaffolding your directory. Your project should have the following structure in `document-models/chat-room/`: ``` document-models/chat-room/ ├── gen/ # Auto-generated code (don't edit) │ ├── actions.ts │ ├── creators.ts # Action creator functions │ ├── types.ts # TypeScript type definitions │ ├── reducer.ts │ ├── messages/ # Messages module │ │ ├── actions.ts │ │ ├── creators.ts │ │ ├── error.ts # Error classes for validation │ │ └── operations.ts │ └── settings/ # Settings module │ ├── actions.ts │ ├── creators.ts │ ├── error.ts │ └── operations.ts ├── src/ # Your custom implementation │ ├── reducers/ │ │ ├── messages.ts # Message operation reducers │ │ └── settings.ts # Settings operation reducers │ └── tests/ │ ├── document-model.test.ts # Document model tests │ ├── messages.test.ts # Messages operation tests │ └── settings.test.ts # Settings operation tests ├── chat-room.json # Document model specification └── schema.graphql # GraphQL schema ``` ### Compare with reference Verify your generated files match the expected structure: ```bash # Compare your generated files with the reference git diff tutorial/main -- document-models/chat-room/ # List what was generated in the reference git ls-tree -r --name-only tutorial/main document-models/chat-room/ ``` ## Up next: Reducers In the next step, you'll learn how to implement the runtime logic that will use the `ChatRoom` document model specification you've just created. --- ## Implement the document model reducers > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/Chatroom/ImplementOperationReducers TIP: 📦 Reference Code: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo) This tutorial covers two key implementations: 1. Reducers: Implementing the reducer logic for all ChatRoom operations 2. Tests: Writing comprehensive tests for the reducers You can view the exact implementation in the repository's `document-models/chat-room/src/` directory. <details> <summary>📖 How to use this tutorial</summary> This tutorial covers implementing reducers and tests. ### Compare your reducer implementation After implementing your reducers: ```bash # Compare your reducers with the reference git diff tutorial/main -- document-models/chat-room/src/reducers/ # View the reference reducer implementation git show tutorial/main:document-models/chat-room/src/reducers/messages.ts ``` ### Compare your tests After writing tests: ```bash # Compare your tests with the reference git diff tutorial/main -- document-models/chat-room/src/tests/ # View the reference test implementation git show tutorial/main:document-models/chat-room/src/tests/messages.test.ts ``` ### Visual comparison with GitHub Desktop After committing your work, compare visually: 1. Branch menu → "Compare to Branch..." 2. Select `tutorial/main` 3. Review differences in the visual interface See step 1 for detailed GitHub Desktop instructions. ### If you get stuck View or reset to the reference: ```bash # View the reducer code from the reference git show tutorial/main:document-models/chat-room/src/reducers/messages.ts # Reset to reference (WARNING: loses your changes) git reset --hard tutorial/main ``` </details> Now implement and test the operation reducers for the ChatRoom document model. Vetra Studio has been generating your document model code as you defined the specification. If you need to review the document model specification steps, see [Define ChatRoom Document Model](/academy/Build/ExampleUsecases/Chatroom/DefineChatroomDocumentModel). ## Understanding reducers in document models Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema. INFO: Connection to schema definition language (SDL): The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddMessageInput`, `AddEmojiReactionInput`, `RemoveEmojiReactionInput`, `EditChatNameInput`, and `EditChatDescriptionInput` in our schema? The reducers provide the actual implementation of what happens when those operations are performed. To import the document model specification into your Powerhouse project, you can either: - Copy and paste the file directly into the root of your Powerhouse project. - Or drag and drop the file into the Powerhouse project directory in the VSCode editor as seen in the image below: Either step will import the document model specification into your Powerhouse project. ![vscode image](image-4.png) ## In your project directory The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well. To write the operation reducers of the ChatRoom document model, you need to generate the document model code from the document model specification file you have exported into the Powerhouse project directory. To do this, run the following command in the terminal: ```bash ph generate ChatRoom.phd ``` You will see that this action created a range of files for you. Before diving in, let's look at this simple schema to familiarize yourself with the structure you've defined in the document model once more. It shows how each type is connected to the next one. ![Chatroom-demo Schema](image.png) ## Implement the messages reducers Navigate to `/document-models/chat-room/src/reducers/messages.ts` and start writing the operation reducers for the messages module. Open the `messages.ts` file and you should see the scaffolding code that needs to be filled for the three message operations. The generated file will look like this: ```typescript export const chatRoomMessagesOperations: ChatRoomMessagesOperations = { addMessageOperation(state, action) { // TODO: Implement "addMessageOperation" reducer throw new Error('Reducer "addMessageOperation" not yet implemented'); }, addEmojiReactionOperation(state, action) { // TODO: Implement "addEmojiReactionOperation" reducer throw new Error('Reducer "addEmojiReactionOperation" not yet implemented'); }, removeEmojiReactionOperation(state, action) { // TODO: Implement "removeEmojiReactionOperation" reducer throw new Error( 'Reducer "removeEmojiReactionOperation" not yet implemented', ); }, }; ``` ### Write the messages operation reducers Copy and paste the code below into the `messages.ts` file in the `reducers` folder, replacing the scaffolding code: <details> <summary>Messages Operation Reducers</summary> ```typescript MessageNotFoundError, MessageContentCannotBeEmpty, } from "../../gen/messages/error.js"; export const chatRoomMessagesOperations: ChatRoomMessagesOperations = { addMessageOperation(state, action) { if (action.input.content === "") { throw new MessageContentCannotBeEmpty(); } const newMessage = { id: action.input.messageId, sender: { id: action.input.sender.id, name: action.input.sender.name || null, avatarUrl: action.input.sender.avatarUrl || null, }, content: action.input.content, sentAt: action.input.sentAt, reactions: [], }; state.messages.push(newMessage); }, addEmojiReactionOperation(state, action) { const message = state.messages.find((m) => m.id === action.input.messageId); if (!message) { throw new MessageNotFoundError( `Message with ID ${action.input.messageId} not found`, ); } if (!message.reactions) { message.reactions = []; } const existingReaction = message.reactions.find( (r) => r.type === action.input.type, ); if (existingReaction) { if (!existingReaction.reactedBy.includes(action.input.reactedBy)) { existingReaction.reactedBy.push(action.input.reactedBy); } } else { message.reactions.push({ type: action.input.type, reactedBy: [action.input.reactedBy], }); } }, removeEmojiReactionOperation(state, action) { const message = state.messages.find((m) => m.id === action.input.messageId); if (!message) { throw new MessageNotFoundError( `Message with ID ${action.input.messageId} not found`, ); } if (!message.reactions) { return; } const reactionIndex = message.reactions.findIndex( (r) => r.type === action.input.type, ); if (reactionIndex === -1) { return; } const reaction = message.reactions[reactionIndex]; const userIndex = reaction.reactedBy.indexOf(action.input.senderId); if (userIndex !== -1) { reaction.reactedBy.splice(userIndex, 1); if (reaction.reactedBy.length === 0) { message.reactions.splice(reactionIndex, 1); } } }, senderOperation(state, action) { // TODO: Implement "senderOperation" reducer throw new Error('Reducer "senderOperation" not yet implemented'); }, }; ``` </details> ## Write the operation reducer tests In order to make sure the operation reducers are working as expected, you need to write tests for them. Navigate to `/document-models/chat-room/src/tests` and you'll find test files for each module. Replace the scaffolding code with the tests below. ### Messages operation tests Replace the content of `messages.test.ts` with: <details> <summary>Messages Operation Tests</summary> ```typescript /** * This is a scaffold file meant for customization: * - change it by adding new tests or modifying the existing ones */ reducer, utils, isChatRoomDocument, addMessage, AddMessageInputSchema, addEmojiReaction, AddEmojiReactionInputSchema, removeEmojiReaction, RemoveEmojiReactionInputSchema, } from "chatroom/document-models/chat-room"; describe("Messages Operations", () => { it("should handle addMessage operation", () => { const document = utils.createDocument(); const input = generateMock(AddMessageInputSchema()); const updatedDocument = reducer(document, addMessage(input)); expect(isChatRoomDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_MESSAGE", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); it("should handle addEmojiReaction operation", () => { const document = utils.createDocument(); const input = generateMock(AddEmojiReactionInputSchema()); const updatedDocument = reducer(document, addEmojiReaction(input)); expect(isChatRoomDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "ADD_EMOJI_REACTION", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); it("should handle removeEmojiReaction operation", () => { const document = utils.createDocument(); const input = generateMock(RemoveEmojiReactionInputSchema()); const updatedDocument = reducer(document, removeEmojiReaction(input)); expect(isChatRoomDocument(updatedDocument)).toBe(true); expect(updatedDocument.operations.global).toHaveLength(1); expect(updatedDocument.operations.global[0].action.type).toBe( "REMOVE_EMOJI_REACTION", ); expect(updatedDocument.operations.global[0].action.input).toStrictEqual( input, ); expect(updatedDocument.operations.global[0].index).toEqual(0); }); }); ``` </details> ### Document model tests The `document-model.test.ts` file contains tests to verify the document model structure. Replace its content with: <details> <summary>Document Model Tests</summary> ```typescript /** * This is a scaffold file meant for customization: * - change it by adding new tests or modifying the existing ones / utils, initialGlobalState, initialLocalState, chatRoomDocumentType, isChatRoomDocument, assertIsChatRoomDocument, isChatRoomState, assertIsChatRoomState, } from "chatroom/document-models/chat-room"; describe("ChatRoom Document Model", () => { it("should create a new ChatRoom document", () => { const document = utils.createDocument(); expect(document).toBeDefined(); expect(document.header.documentType).toBe(chatRoomDocumentType); }); it("should create a new ChatRoom document with a valid initial state", () => { const document = utils.createDocument(); expect(document.state.global).toStrictEqual(initialGlobalState); expect(document.state.local).toStrictEqual(initialLocalState); expect(isChatRoomDocument(document)).toBe(true); expect(isChatRoomState(document.state)).toBe(true); }); it("should reject a document that is not a ChatRoom document", () => { const wrongDocumentType = utils.createDocument(); wrongDocumentType.header.documentType = "the-wrong-thing-1234"; try { expect(assertIsChatRoomDocument(wrongDocumentType)).toThrow(); expect(isChatRoomDocument(wrongDocumentType)).toBe(false); } catch (error) { expect(error).toBeInstanceOf(ZodError); } }); const wrongState = utils.createDocument(); // @ts-expect-error - we are testing the error case wrongState.state.global = { ...{ notWhat: "you want" }, }; try { expect(isChatRoomState(wrongState.state)).toBe(false); expect(assertIsChatRoomState(wrongState.state)).toThrow(); expect(isChatRoomDocument(wrongState)).toBe(false); expect(assertIsChatRoomDocument(wrongState)).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } const wrongInitialState = utils.createDocument(); // @ts-expect-error - we are testing the error case wrongInitialState.initialState.global = { ...{ notWhat: "you want" }, }; try { expect(isChatRoomState(wrongInitialState.state)).toBe(false); expect(assertIsChatRoomState(wrongInitialState.state)).toThrow(); expect(isChatRoomDocument(wrongInitialState)).toBe(false); expect(assertIsChatRoomDocument(wrongInitialState)).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } const missingIdInHeader = utils.createDocument(); // @ts-expect-error - we are testing the error case delete missingIdInHeader.header.id; try { expect(isChatRoomDocument(missingIdInHeader)).toBe(false); expect(assertIsChatRoomDocument(missingIdInHeader)).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } const missingNameInHeader = utils.createDocument(); // @ts-expect-error - we are testing the error case delete missingNameInHeader.header.name; try { expect(isChatRoomDocument(missingNameInHeader)).toBe(false); expect(assertIsChatRoomDocument(missingNameInHeader)).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } const missingCreatedAtUtcIsoInHeader = utils.createDocument(); // @ts-expect-error - we are testing the error case delete missingCreatedAtUtcIsoInHeader.header.createdAtUtcIso; try { expect(isChatRoomDocument(missingCreatedAtUtcIsoInHeader)).toBe(false); expect(assertIsChatRoomDocument(missingCreatedAtUtcIsoInHeader)).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } const missingLastModifiedAtUtcIsoInHeader = utils.createDocument(); // @ts-expect-error - we are testing the error case delete missingLastModifiedAtUtcIsoInHeader.header.lastModifiedAtUtcIso; try { expect(isChatRoomDocument(missingLastModifiedAtUtcIsoInHeader)).toBe(false); expect( assertIsChatRoomDocument(missingLastModifiedAtUtcIsoInHeader), ).toThrow(); } catch (error) { expect(error).toBeInstanceOf(ZodError); } }); ``` </details> ## Run the tests Now you can run the tests to make sure the operation reducers are working as expected. ```bash pnpm run test ``` Output should be similar to: ```bash ✓ document-models/chat-room/src/tests/document-model.test.ts (3 tests) 1ms ✓ document-models/chat-room/src/tests/messages.test.ts (3 tests) 8ms ✓ document-models/chat-room/src/tests/settings.test.ts (2 tests) 2ms Test Files 3 passed (3) Tests 8 passed (8) Start at 15:19:52 Duration 3.61s (transform 77ms, setup 0ms, collect 3.50s, tests 14ms, environment 0ms, prepare 474ms) ``` If you got a similar output, you have successfully implemented the operation reducers and tests for the ChatRoom document model. ## Compare with reference implementation Verify your implementation matches the tutorial: ```bash # View reference reducer implementation git show tutorial/main:document-models/chat-room/src/reducers/messages.ts git show tutorial/main:document-models/chat-room/src/reducers/settings.ts # View reference test implementation git show tutorial/main:document-models/chat-room/src/tests/messages.test.ts git show tutorial/main:document-models/chat-room/src/tests/settings.test.ts # Compare your entire implementation git diff tutorial/main -- document-models/chat-room/src/ ``` ## Up next: ChatRoom editor Continue to the next section to learn how to implement the document model editor so you can see a simple user interface for the ChatRoom document model in action. --- ## Build the ChatRoom editor > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/Chatroom/ImplementChatroomEditor TIP: 📦 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 ```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/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> Now build the editor: the user interface for the ChatRoom document model. It visualizes your chatroom, sends messages, and reacts with emojis. ## Add a document editor specification in Vetra Studio Go back to Vetra Studio, if you need to relaunch Vetra, launch it with `Vetra --watch` so it loads all existing local documents. Click the 'Add new specification' button in the User Experiences column under 'Editors'. This will create an editor template for your document model. Give the editor the name `chat-room-editor` and select the correct document model. In our case that's the `powerhouse/chat-room`. You'll see that the terminal in which you are running Vetra mentions ``` ℹ [Vetra] 🔄 Starting editor generation for: chat-room-editor added: editors/chat-room-editor/components/EditName.tsx added: editors/chat-room-editor/editor.tsx FORCED: editors/chat-room-editor/module.ts ℹ [Vetra] ✅ Editor generation completed successfully for: chat-room-editor ``` 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 ``` 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: Vetra 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. Vetra Studio Preview provides a dynamic local environment. By running `ph vetra --watch`, you can visualize your components instantly as you build them. ## Build the editor with components We'll build the editor using a component-based approach for better organization and reusability. ### Component-based architecture The ChatRoom editor uses a modular component structure. Each component has its own folder with an `index.ts` file for clean exports: ``` editors/chat-room-editor/ ├── components/ │ ├── Avatar/ # User avatar display │ │ ├── Avatar.tsx │ │ └── index.ts │ ├── ChatRoom/ # Main chat container │ │ ├── ChatRoom.tsx │ │ └── index.ts │ ├── Header/ # Chat header with editable title/description │ │ ├── EditableLabel.tsx │ │ ├── Header.tsx │ │ └── index.ts │ ├── Message/ # Individual message bubble │ │ ├── Message.tsx │ │ └── index.ts │ ├── MessageItem/ # Message with avatar and reaction dropdown │ │ ├── MessageItem.tsx │ │ └── index.ts │ ├── Reaction/ # Emoji reaction display │ │ ├── Reaction.tsx │ │ └── index.ts │ ├── TextInput/ # Message input field │ │ ├── SendIcon.tsx │ │ ├── TextInput.tsx │ │ └── index.ts │ └── index.ts # Central exports ├── editor.tsx # Main editor component ├── utils.ts # Utility functions for data mapping └── module.ts # Editor module configuration ``` ### Copy components from the reference repository 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 the following: 1. The entire `components/` folder - Contains all UI components 2. The `utils.ts` file - Contains utility functions for emoji mapping Here's what each component does: | Component | Purpose | | --------------- | --------------------------------------------------------------------------- | | `Avatar` | Displays a user avatar image or a deterministic emoji based on the username | | `ChatRoom` | Main container that orchestrates the header, messages list, and input field | | `Header` | Shows the chat title and description with inline editing capability | | `EditableLabel` | Reusable component for inline text editing with edit/cancel icons | | `Message` | Renders a single message bubble with styling based on the sender | | `MessageItem` | Wraps `Message` with `Avatar` and adds a reaction dropdown menu | | `Reaction` | Displays an emoji reaction with a count of users who reacted | | `TextInput` | Input field for composing and sending new messages | ### The utils.ts file The `utils.ts` file contains helper functions for mapping between document model types and component props: <details> <summary>View utils.ts code</summary> ```typescript MessageProps, ReactionMap, } from "./components/Message/Message.js"; Message, ReactionType, } from "../../document-models/chat-room/gen/schema/types.js"; const emojis = [ "😀", "😂", "🤣", "😍", "😎", "😊", "🙃", "😇", "🤔", "🥳", "🤯", "🤗", "😱", "👻", "🎃", "🐱", "🐶", "🐹", "🦊", "🐻", "🐼", "🐨", "🐯", "🦁", "🐸", "🐵", "🐔", "🐧", "🐦", "🐤", "🐝", "🐞", "🐟", "🐬", "🐳", "🦋", "🌺", "🌸", "🌼", "🍀", ]; export function getEmojiFromString(input: string): string { function hashString(str: string): number { let hash = 0; for (let i = 0; i < str.length; i++) { const char = str.charCodeAt(i); hash = (hash << 5) - hash + char; hash |= 0; } return Math.abs(hash); } const hash = hashString(input); return emojis[hash % emojis.length]; } export const reactionTypeToEmoji = (reactionType: ReactionType): string => { switch (reactionType) { case "HEART": return "❤️"; case "THUMBS_UP": return "👍"; case "THUMBS_DOWN": return "👎"; case "LAUGH": return "😂"; case "CRY": return "😢"; default: return "❤️"; } }; export const reactionTypeToReactionKey = ( reactionType: ReactionType, ): keyof ReactionMap => { switch (reactionType) { case "HEART": return "heart"; case "THUMBS_UP": return "thumbsUp"; case "THUMBS_DOWN": return "thumbsDown"; case "LAUGH": return "laughing"; case "CRY": return "cry"; default: return "heart"; } }; export const reactionKeyToReactionType = ( reactionKey: string, ): ReactionType => { switch (reactionKey) { case "heart": return "HEART"; case "thumbsUp": return "THUMBS_UP"; case "thumbsDown": return "THUMBS_DOWN"; case "laughing": return "LAUGH"; case "cry": return "CRY"; default: return "HEART"; } }; export const mapReactions = ( reactions: Message["reactions"], ): MessageProps["reactions"] => { return (reactions || []) .map((reaction) => ({ emoji: reactionTypeToEmoji(reaction.type), reactedBy: reaction.reactedBy, type: reactionTypeToReactionKey(reaction.type), })) .filter((reaction) => reaction.reactedBy.length > 0); }; ``` </details> ### The main editor.tsx file The main `editor.tsx` file connects your document model to the UI components. Replace the generated scaffolding with the code underneath: <details> <summary>View editor.tsx code</summary> ```typescript addMessage, addEmojiReaction, removeEmojiReaction, editChatName, editChatDescription, } from "../../document-models/chat-room/gen/creators.js"; ChatRoom, type ChatRoomProps, type MessageProps, } from "./components/index.js"; export default function Editor() { const [document, dispatch] = useSelectedChatRoomDocument(); const user = useUser(); const disableChatRoom = !user; if (!document) { return <div>Loading...</div>; } const messages: ChatRoomProps["messages"] = document.state.global.messages.map((message) => ({ id: message.id, message: message.content || "", timestamp: message.sentAt, userName: message.sender.name || message.sender.id, imgUrl: message.sender.avatarUrl || undefined, isCurrentUser: message.sender.id === user?.address, reactions: mapReactions(message.reactions), })); const onSendMessage: ChatRoomProps["onSendMessage"] = (message) => { if (!message) { return; } dispatch( addMessage({ messageId: generateId(), content: message, sender: { id: user?.address || "anon-user", name: user?.ens?.name || null, avatarUrl: user?.ens?.avatarUrl || null, }, sentAt: new Date().toISOString(), }), ); }; const addReaction = ( messageId: string, userId: string, reactionType: "HEART" | "THUMBS_UP" | "THUMBS_DOWN" | "LAUGH" | "CRY", ) => { dispatch( addEmojiReaction({ messageId, reactedBy: userId, type: reactionType, }), ); }; const removeReaction = ( messageId: string, userId: string, reactionType: "HEART" | "THUMBS_UP" | "THUMBS_DOWN" | "LAUGH" | "CRY", ) => { dispatch( removeEmojiReaction({ messageId, senderId: userId, type: reactionType, }), ); }; const onClickReaction: MessageProps["onClickReaction"] = (reaction) => { const message = messages.find( (message) => message.id === reaction.messageId, ); if (!message) { return; } const messageId = reaction.messageId; const reactionType = reactionKeyToReactionType(reaction.type); const currentUserId = user?.address || "anon-user"; const existingReaction = message.reactions?.find( (r) => r.type === reaction.type, ); if (existingReaction) { const dispatchAction = existingReaction.reactedBy.includes(currentUserId) ? removeReaction : addReaction; dispatchAction(messageId, currentUserId, reactionType); } else { addReaction(messageId, currentUserId, reactionType); } }; const onSubmitTitle: ChatRoomProps["onSubmitTitle"] = (title) => { dispatch(editChatName({ name: title })); }; const onSubmitDescription: ChatRoomProps["onSubmitDescription"] = ( description, ) => { dispatch(editChatDescription({ description })); }; return ( <div style={{ height: "calc(100vh - 140px)", }} > <ChatRoom description={ document.state.global.description || "This is a chat room demo" } disabled={disableChatRoom} messages={messages} onClickReaction={onClickReaction} onSendMessage={onSendMessage} onSubmitDescription={onSubmitDescription} onSubmitTitle={onSubmitTitle} title={document.state.global.name || "Chat Room Demo"} /> </div> ); } ``` </details> 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: 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. ## Key components explained ### MessageItem component The `MessageItem` component wraps the `Message` component with an avatar and a reaction dropdown menu. It uses the `@powerhousedao/design-system` package for the dropdown: ```typescript DropdownMenu, DropdownMenuContent, DropdownMenuTrigger, DropdownMenuItem, } from "@powerhousedao/design-system"; export type MessageItemProps = MessageProps & AvatarProps; export const reactionMap = { cry: "😢", laughing: "😂", heart: "❤️", thumbsDown: "👎", thumbsUp: "👍", }; export const MessageItem: React.FC<MessageItemProps> = (props) => { const { imgUrl, userName, isCurrentUser, ...messageProps } = props; const { disabled = false } = messageProps; const [isHovered, setIsHovered] = useState(false); const [open, setOpen] = useState(false); // ... hover and dropdown logic return ( <div style={{ display: "flex", gap: "2px", alignItems: "flex-end" }}> <Avatar imgUrl={imgUrl} userName={userName} /> <DropdownMenu> <Message isCurrentUser={isCurrentUser} userName={userName} {...messageProps} /> <DropdownMenuTrigger>🫥</DropdownMenuTrigger> <DropdownMenuContent> {Object.entries(reactionMap).map(([key, emoji]) => ( <DropdownMenuItem key={key} onClick={() => / handle reaction /}> {emoji} </DropdownMenuItem> ))} </DropdownMenuContent> </DropdownMenu> </div> ); }; ``` ### EditableLabel component The `EditableLabel` component enables inline editing of text fields (like the chat title and description): ```typescript export const EditableLabel: React.FC<EditableLabelProps> = ({ label: initialLabel, onSubmit, style, }) => { const [hover, setHover] = useState(false); const [isEditing, setIsEditing] = useState(false); const [label, setLabel] = useState(initialLabel); // Toggle between read mode (displaying text) and write mode (input field) // Press Enter to submit, Escape to cancel return ( <div onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}> {isEditing ? ( <input value={label} onChange={(e) => setLabel(e.target.value)} /> ) : ( <h1>{label}</h1> )} {(hover || isEditing) && <EditIcon onClick={() => setIsEditing(true)} />} </div> ); }; ``` ## Test your editor Now you can run Vetra Studio Preview and see the ChatRoom editor in action: ```bash ph vetra --watch ``` In Vetra Studio, 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: 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](../docs/docs/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: ```bash # See the ChatRoom component implementation git show tutorial/main:editors/chat-room-editor/components/ChatRoom/ChatRoom.tsx # Explore the MessageItem component git show tutorial/main:editors/chat-room-editor/components/MessageItem/MessageItem.tsx # View the EditableLabel component git show tutorial/main:editors/chat-room-editor/components/Header/EditableLabel.tsx # Compare your implementation with the reference git diff tutorial/main -- editors/chat-room-editor/ ``` You now have a working ChatRoom editor. Compare your implementation against the reference branch above if anything differs. --- ## Todo List (reference implementation) > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/TodoList/TodoList The Todo List is the worked example used throughout the Build track. Rather than repeat it here, this page points you to the finished code so you can clone, run, and compare against your own work. You build the Todo List step by step in two places: - [Manual Todo tutorial](/academy/Build/ManualTodoTutorial/ExploreDemoPackage) — build a basic Todo package by hand: document model, reducers, tests, and editor. - [Document Model Creation (Mastery Track)](/academy/Build/DocumentModelCreation/WhatIsADocumentModel) — the theory behind those steps, plus the advanced extensions: computed `stats`, the [Drive Explorer](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer), and a shared stats component. ## The reference repository The full implementation lives at [powerhouse-inc/todo-tutorial](https://github.com/powerhouse-inc/todo-tutorial). It uses one branch per step so you can start anywhere or compare your work: - Each step has a starting branch (`step-1-…`) and a completed branch (`step-1-complete-…`). - The `step-1-` branch matches what `ph init todo-tutorial` produces. - To compare your work against a checkpoint: `git diff your-branch step-1-complete-…`, or use "compare with branch" in the GitHub UI. Fork the repository (uncheck "copy the main branch only" so you keep every step branch), `git clone` your fork, then `pnpm install`. ## What the finished package demonstrates - A `TodoList` document model with state schema and operations - Reducer operation handlers and their unit tests - A document editor wired to the model's operations - A custom Drive Explorer for managing many Todo Lists in a drive - A shared component that displays Todo List stats in both the editor and the Drive Explorer --- ## VetraPackageLibrary > Source: https://academy.vetra.io/academy/Build/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary Packages of documents are a core structuring mechanism in the Vetra framework, allowing developers to group and manage related document efficiently. These packages serve as modular collections of document specifications and modules, ensuring consistency, scalability, and reusability across different applications. ### Example packages - Finance Package – A set of documents or apps handling invoices, payments, budgets, and financial reporting. - Contributor Billing Package – Defines documents for tracking work, invoicing, and facilitating payments (in both fiat and crypto) for contributors in decentralized organizations. - Governance Package – Models for proposals, voting, contributor agreements, and decision-making processes. - People Ops Package – Documents managing contributor profiles, roles, task assignments, and reputation tracking. - Project Management Package – Models for task tracking, milestones, resource allocation, and deliverables. --- The Vetra package library is your best source to explore packages built by different builder teams on the Powerhouse Vetra platform. Through the packages you'll find the GitHub repository with the source code of each package. You can get access to the [package library here.](https://vetra.io/packages) --- ## Cookbook > Source: https://academy.vetra.io/academy/Lookup/Cookbook ## Powerhouse CLI recipes This section covers recipes related to the `ph-cmd`, the command-line tool for Powerhouse project initialization, code generation, package management, and running local development environments. <details id="installing-ph-cmd"> <summary>Installing 'ph-cmd'</summary> ### How to install Powerhouse CLI --- ### Problem statement You need to install the Powerhouse CLI (`ph-cmd`) to create and manage Powerhouse projects. ### Prerequisites - Node.js 24 installed - pnpm package manager 10 installed - Terminal or command prompt access ### Solution ### Step 1: Install the CLI globally ```bash pnpm install -g ph-cmd ``` ### Step 2: Verify the installation ```bash ph-cmd --version ``` ### Optional: Install specific versions ```bash # For the staging version pnpm install -g ph-cmd@staging # For a specific version pnpm install -g ph-cmd@<version> ``` ### Expected outcome - Powerhouse CLI (`ph-cmd`) installed globally on your system - Access to all Powerhouse CLI commands for project creation and management ### Common issues and solutions - Issue: Permission errors during installation - Solution: Use `sudo` on Unix-based systems or run as administrator on Windows - Issue: Version conflicts - Solution: Clean your system using the uninstallation recipe before installing a new version ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> <details id="managing-ph-cmd-versions"> <summary>Managing ph-cmd Versions and Package Information</summary> ### How to Switch Between ph-cmd Versions --- ### Problem statement You need to switch to a different version of `ph-cmd`, check available versions, or understand how to manage package versions effectively. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - Terminal or command prompt access - Package manager (pnpm, npm, or yarn) installed ### Solution ### Using Version Tags and Specific Versions To change to a different version of `ph-cmd`, reinstall it globally with your package manager: ```bash # Install latest version with a specific tag npm install -g ph-cmd@staging pnpm install -g ph-cmd@dev # Install a specific version number npm install -g ph-cmd@1.2.3-staging.10 pnpm install -g ph-cmd@6.0.0-dev.33 ``` Important: Always use the same package manager you used for the original global install to avoid conflicting installations. ### Checking Your Current Installation Use the `which` command to see where your global install is located: ```bash which ph # Example output: /Users/username/Library/pnpm/ph ``` This shows which package manager was used (in this case, pnpm). ### Viewing Available Versions Use `npm view` to see all available versions and tags for any package: ```bash npm view ph-cmd ``` This displays: - Current version information - Available dist-tags (latest, dev, staging, test) - Specific version numbers for each tag - Package maintainers and publish information Example dist-tags output: ``` dist-tags: latest: 5.3.0 dev: 6.0.0-dev.33 staging: 5.3.0-staging.24 test: 2.5.0-test.0 ``` ### Expected outcome - Ability to switch between different versions of `ph-cmd` - Understanding of available version tags and specific versions - Knowledge of how to check current installation and available versions ### Best Practices - Use specific version numbers (e.g., `ph-cmd@6.0.0-dev.33`) instead of tags when you need to ensure exact version consistency - Check `npm view ph-cmd` before switching to see the latest available versions - Remember that without specifying a version, `@latest` is installed by default ### Common issues and solutions - Issue: Conflicting installations or commands not working - Solution: Ensure you use the same package manager for all global installs. Use `which ph` to verify your installation location. - Issue: Outdated version after installation - Solution: Use `npm view ph-cmd` to check the latest available versions and install the specific version you need. ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Using Different Branches in Powerhouse](#using-different-branches-in-powerhouse) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> <details id="uninstalling-ph-cmd"> <summary>Uninstalling 'ph-cmd'</summary> ### How to uninstall Powerhouse CLI --- ### Problem statement You want to perform a clean installation of the Powerhouse CLI. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A terminal or IDE ### Solution ### Step 1: Uninstall `ph-cmd` ```bash pnpm uninstall -g ph-cmd ``` ### Step 2: Remove the global setups folder ```bash rm -rf ~/.ph ``` ### Expected outcome - Your system should now be clean from the Powerhouse CLI ### Common issues and solutions - Issue: Outdated version - Solution: Uninstall and reinstall the Powerhouse CLI ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) - [Create A New Powerhouse Project](/academy/Build/ManualTodoTutorial/CreateNewPowerhouseProject) </details> <details id="setting-up-or-resetting-the-global-powerhouse-configuration"> <summary>Setting up or Resetting the Global Powerhouse Configuration</summary> ### How to set up or reset the global Powerhouse configuration --- ### Problem statement You need to initialize the global Powerhouse configuration for the first time, or reset it to resolve issues or start fresh. This might also involve switching to a specific dependency environment like staging. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - Terminal or command prompt access ### Solution ### Step 1: (Optional) Remove existing configuration If you suspect issues with your current global setup or want a completely clean slate, remove the existing global configuration directory. Skip this if setting up for the first time. ```bash # Use with caution: this removes your global settings and downloaded dependencies. rm -rf ~/.ph ``` ### Step 2: Set up global defaults Initialize the default global project configuration. ```bash ph setup-globals ``` ### Step 3: (Optional) Switch to a specific environment (e.g., staging) If you need to use non-production dependencies, switch the global environment. ```bash # Switch to staging dependencies ph use staging # Or switch back to the latest stable versions # ph use latest ``` ### Expected outcome - A `~/.ph` directory is created or reset. - The global project is configured, potentially using the specified environment (e.g., staging). - You are ready to initialize or work with Powerhouse projects using the defined global settings. ### Common issues and solutions - Issue: Commands fail after removing `~/.ph`. - Solution: Ensure you run `ph setup-globals` afterwards. - Issue: Need to use specific local dependencies globally. - Solution: Use `ph use local /path/to/local/packages`. ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Using Different Branches in Powerhouse](#using-different-branches-in-powerhouse) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) - [GraphQL Schema Best Practices](/academy/Build/WorkWithData/UsingTheAPI) </details> <details id="using-different-branches-in-powerhouse"> <summary>Using Different Branches in Powerhouse</summary> ### How to use different branches in Powerhouse --- ### Problem statement You need to access experimental features, bugfixes, or development versions of Powerhouse components that aren't yet available in the stable release. ### Prerequisites - Terminal or command prompt access - pnpm package manager 10 installed - Node.js 24 installed ### Solution ### Step 1: Install CLI with specific branch Choose the appropriate installation command based on your needs: ```bash # For latest stable version pnpm install -g ph-cmd # For development version pnpm install -g ph-cmd@dev # For staging version pnpm install -g ph-cmd@staging ``` ### Step 2: Initialize project with specific branch When creating a new project, you can specify which branch to use: ```bash # Use latest stable version of the boilerplate ph init # Use development version of the boilerplate ph init --dev # Use staging version of the boilerplate ph init --staging ``` ### Step 3: Switch dependencies for existing project For existing projects, you can switch all dependencies to different versions: ```bash # Switch to latest production versions ph use # Switch to development versions ph use dev # Switch to production versions ph use prod ``` ### Expected outcome - Access to the specified version of Powerhouse components - Ability to test experimental features or bugfixes - Project configured with the chosen branch's dependencies ### Common issues and solutions - Issue: Experimental features not working as expected - Solution: This is normal as these versions may contain untested features. Consider switching back to stable versions if issues persist. - Issue: Version conflicts between components - Solution: Ensure all components are using the same branch version. Use `ph use` commands to synchronize versions. ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Managing and Updating Powerhouse Dependencies](#managing-and-updating-powerhouse-dependencies) - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> <details id="using-different-package-managers-with-powerhouse"> <summary>Using Different Package Managers with Powerhouse</summary> ### How to use different package managers with Powerhouse --- ### Problem statement You want to use a different package manager (npm, yarn, or bun) instead of pnpm for managing Powerhouse projects and dependencies. ### Prerequisites - Node.js 24 installed - Your preferred package manager installed (npm, yarn, or bun) - Terminal or command prompt access ### Solution ### Step 1: Install the CLI with Your Preferred Package Manager Choose the appropriate installation command based on your package manager: ```bash # Using npm npm install -g ph-cmd --legacy-peer-deps # Using yarn yarn global add ph-cmd # Using bun bun install -g ph-cmd # Using pnpm (default) pnpm install -g ph-cmd ``` ### Step 2: Configure PATH for Global Binaries For yarn and bun, you need to add their global binary directories to your PATH: #### For Yarn: ```bash # Add this to your ~/.bashrc, ~/.zshrc, or equivalent export PATH="$PATH:$(yarn global bin)" ``` #### For Bun: ```bash # Add this to your ~/.bashrc, ~/.zshrc, or equivalent export PATH="$PATH:$HOME/.bun/bin" ``` After adding these lines, reload your shell configuration: ```bash source ~/.bashrc # or source ~/.zshrc ``` ### Step 3: Verify Installation Check that the CLI is properly installed and accessible: ```bash ph-cmd --version ``` ### Step 4: Using Different Package Managers in Projects When working with Powerhouse projects, you can specify your preferred package manager: ```bash # Initialize a project with npm ph init --package-manager npm # Initialize a project with yarn ph init --package-manager yarn # Initialize a project with bun ph init --package-manager bun # Initialize a project with pnpm (preferred default) ph init --package-manager pnpm ``` ### Expected outcome - Powerhouse CLI installed and accessible through your preferred package manager - Ability to manage Powerhouse projects using your chosen package manager - Proper PATH configuration for global binaries ### Common issues and solutions - Issue: Command not found after installation - Solution: Ensure the global binary directory is in your PATH (especially for yarn and bun) - Solution: Try running the command with the full path to verify installation - Issue: Permission errors during installation - Solution: Use `sudo` on Unix-based systems or run as administrator on Windows - Issue: Package manager conflicts - Solution: Stick to one package manager per project to avoid lockfile conflicts ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration) ### Further reading - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) - [Yarn Global Installation Guide](https://classic.yarnpkg.com/lang/en/docs/cli/global/) - [Bun Installation Guide](https://bun.sh/docs/installation#how-to-add-your-path) </details> ## Powerhouse Package Development recipes This comprehensive section covers the complete workflow for building Powerhouse packages using Vetra Studio, from project initialization and document model creation to editors, Drive-apps, and package publishing. > Tip: For the best development experience, use Vetra Studio with `ph vetra --watch`. Vetra Studio provides automatic code generation, AI-assisted development, and live preview of your documents and editors. ### Vetra Studio Vetra Studio is the AI-powered development environment for building Powerhouse packages with specification-driven workflows. <details id="launching-vetra-studio"> <summary>Launching Vetra Studio</summary> ### How to Launch Vetra Studio --- ### Problem statement You want to start Vetra Studio to develop document models, editors, and other package components using the specification-driven workflow. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - Terminal or command prompt access ### Solution ### Step 1: Navigate to Your Project Directory ```bash cd <yourprojectname> ``` ### Step 2: Choose Your Launch Mode Vetra Studio offers three modes depending on your workflow: #### Interactive Mode (Recommended for Development) ```bash ph vetra --interactive ``` In interactive mode: - You receive confirmation prompts before any code generation - Changes require explicit confirmation before being processed - Provides better control and visibility over document changes #### Watch Mode with Interactive ```bash ph vetra --interactive --watch ``` In watch mode: - Enables dynamic loading for document-models and editors - The system watches for changes and reloads them dynamically - Best for active development with frequent changes #### Standard Mode ```bash ph vetra ``` In standard mode: - Changes are processed automatically with 1-second debounce - Multiple changes are batched and processed together - Uses the latest document state for processing ### Expected outcome - Vetra Studio launches in your browser - You can access the Vetra Studio Drive to manage specifications - Document models and editors are available for development ### Common issues and solutions - Issue: Vetra Studio environment breaks during document model development - Solution: This can happen when code changes break the environment. Restart Vetra Studio and check your document model for errors. - Issue: Changes not reflecting in the studio - Solution: If not using `--watch` mode, restart Vetra Studio to pick up changes. ### Related recipes - [Connecting to a Remote Vetra Drive](#connecting-to-a-remote-vetra-drive) - [Connecting Claude with Reactor MCP](#connecting-claude-with-reactor-mcp) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Powerhouse CLI Reference](/academy/Reference/CLITooling/PowerhouseCLI#vetra) </details> <details id="connecting-to-a-remote-vetra-drive"> <summary>Connecting to a Remote Vetra Drive</summary> ### How to Connect to a Remote Vetra Drive --- ### Problem statement You want to collaborate with team members by connecting to a shared remote Vetra drive instead of using a local one, enabling synchronized specifications across your team. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized or ready to create - The URL of the remote Vetra drive you want to connect to - Terminal or command prompt access ### Solution #### Option A: Create a New Project with Remote Drive ### Step 1: Initialize with Remote Drive ```bash ph init --remote-drive <url> ``` Example: ```bash ph init --remote-drive https://switchboard.staging.vetra.io/d/my-team-drive ``` ### Step 2: Start Vetra with Watch Mode ```bash ph vetra --watch ``` #### Option B: Clone an Existing Project from Remote Drive ### Step 1: Checkout the Remote Drive ```bash ph checkout --remote-drive <url> ``` ### Step 2: Start Vetra ```bash ph vetra --watch ``` #### Option C: Configure Remote Drive in Existing Project ### Step 1: Edit powerhouse.config.json Add the Vetra configuration to your `powerhouse.config.json` file: ```json { "vetra": { "driveId": "your-drive-id", "driveUrl": "https://switchboard.staging.vetra.io/d/your-drive-id" } } ``` ### Step 2: Start Vetra ```bash ph vetra --watch ``` ### Expected outcome - Your project is connected to the remote Vetra drive - Specifications sync across team members - A "Vetra Preview" drive is created locally for testing changes before syncing - The main "Vetra" drive syncs with the remote and contains stable package configuration ### Common issues and solutions - Issue: Cannot connect to remote drive - Solution: Verify the drive URL is correct and accessible. Check your network connection and any firewall settings. - Issue: Local changes not syncing - Solution: The "Vetra Preview" drive is for local testing. Changes need to be explicitly synced to the main drive. - Issue: Conflicts with team member changes - Solution: Always use `ph vetra --watch` when restarting to ensure local documents and editors are loaded properly. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Connecting Claude with Reactor MCP](#connecting-claude-with-reactor-mcp) ### Further reading - [Vetra Remote Drive Reference](/academy/Reference/CLITooling/VetraRemoteDrive) - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) </details> <details id="connecting-claude-with-reactor-mcp"> <summary>Connecting Claude with Reactor MCP</summary> ### How to Connect Claude with Reactor MCP --- ### Problem statement You want to use AI-assisted development in Vetra Studio by connecting Claude to the Reactor MCP (Model Context Protocol), enabling natural language document model creation and editing. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - Vetra Studio running (`ph vetra --watch`) - Claude CLI installed and configured - Terminal or command prompt access ### Solution ### Step 1: Start Vetra Studio First, ensure Vetra Studio is running in your project directory: ```bash ph vetra --interactive --watch ``` ### Step 2: Configure the MCP Server (one-time setup) Add the Reactor MCP server to your Claude configuration. For Claude Code, add it to `~/.claude/mcp.json`; for Claude Desktop, add it under MCP Servers in settings: ```json { "mcpServers": { "reactor-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:4001/mcp"] } } } ``` This tells Claude how to reach the Reactor MCP endpoint. You only need to do this once per machine. ### Step 3: Open a New Terminal and Navigate to Your Project ```bash cd <yourprojectname> ``` ### Step 4: Start Claude CLI ```bash claude ``` ### Step 5: Connect to Reactor MCP In the Claude CLI, request connection to the reactor: ``` connect to the reactor mcp ``` ### Step 6: Verify the Connection You should see a confirmation message like: ``` Connected to MCP successfully! I can see there's a "vetra-4de7fa45" drive available. The reactor-mcp server is running and ready for document model operations. ``` ### Expected outcome - Claude is connected to Reactor MCP - Vetra Studio shows "Connected to Reactor MCP" - You can now use natural language to create and modify document models - Claude has access to document operations, drive operations, and document model operations ### Common issues and solutions - Issue: MCP connection fails - Solution: Ensure Vetra Studio is running before attempting to connect Claude. Restart both Vetra and Claude if needed. - Issue: Claude doesn't recognize reactor commands - Solution: Make sure you're in the correct project directory when starting Claude. - Issue: Drive not visible in Claude - Solution: Verify Vetra Studio is running with the `--watch` flag and the drive is properly initialized. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Creating a Document Model with AI Assistance](#creating-a-document-model-with-ai-assistance) - [Creating an Editor with AI Assistance](#creating-an-editor-with-ai-assistance) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) </details> <details id="creating-a-document-model-with-ai-assistance"> <summary>Creating a Document Model with AI Assistance</summary> ### How to Create a Document Model with AI Assistance --- ### Problem statement You want to create a new document model using natural language descriptions through Claude and the Reactor MCP, rather than manually defining schemas and operations. ### Prerequisites - Vetra Studio running (`ph vetra --interactive --watch`) - Claude connected to Reactor MCP (see [Connecting Claude with Reactor MCP](#connecting-claude-with-reactor-mcp)) ### Solution ### Step 1: Describe Your Document Model to Claude Provide a detailed description of your document needs. Be specific about: - The purpose of the document - The data fields and their types - The operations users should be able to perform - Any relationships or constraints Example prompt: ``` Create a document model for a task tracker with the following requirements: - Each task has a title (string), description (string), status (enum: todo, in-progress, done), priority (enum: low, medium, high), and due date (optional date) - Users should be able to create tasks, update task details, change status, and delete tasks - Tasks should track when they were created and last modified ``` ### Step 2: Review the Generated Schema Claude will generate: - An appropriate GraphQL schema - The necessary operations - Implementation for the required reducers Review the proposed schema before confirming. ### Step 3: Confirm Generation in Interactive Mode If running in interactive mode, you'll be prompted to confirm: - Schema changes - Operation definitions - Code generation ### Step 4: Verify in Vetra Studio Check Vetra Studio to see your new document model in the drive. The document should appear with the defined schema and operations. ### Expected outcome - A new document model is created based on your natural language description - The schema, operations, and reducers are generated automatically - The document model is placed in the Vetra drive - Code scaffolding is generated in your project ### Common issues and solutions - Issue: Generated schema doesn't match expectations - Solution: Provide more specific requirements. Ask Claude clarifying questions before generation. - Issue: Operations missing functionality - Solution: Be explicit about all the actions users should be able to perform on the document. - Issue: Code generation fails - Solution: Check if the document model is in a valid state. Review any error messages in Vetra Studio. ### Related recipes - [Connecting Claude with Reactor MCP](#connecting-claude-with-reactor-mcp) - [Creating an Editor with AI Assistance](#creating-an-editor-with-ai-assistance) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Document Model Creation](/academy/Build/DocumentModelCreation/SpecifyTheStateSchema) </details> <details id="creating-an-editor-with-ai-assistance"> <summary>Creating an Editor with AI Assistance</summary> ### How to Create an Editor with AI Assistance --- ### Problem statement You have a document model and want to create a user interface (editor) for it using AI assistance through Claude and the Reactor MCP. ### Prerequisites - Vetra Studio running (`ph vetra --interactive --watch`) - Claude connected to Reactor MCP - An existing document model in your Vetra drive ### Solution ### Step 1: Describe Your Editor Requirements to Claude Provide a detailed description including: - The document model the editor is for - UI layout and components needed - User interactions and workflows - Any specific styling or design requirements - Reference to operations from the document model Example prompt: ``` Create an editor for my task tracker document model with: - A form to create new tasks with fields for title, description, priority, and due date - A list view showing all tasks grouped by status (todo, in-progress, done) - Each task card should show title, priority badge, and due date - Clicking a task opens a detail panel for editing - Status can be changed via drag-and-drop between columns or a dropdown - Use the createTask, updateTask, changeStatus, and deleteTask operations ``` ### Step 2: Review Generated Components Claude will generate: - Editor components - Necessary hooks for document operations - Required UI elements - Integration with the document model operations ### Step 3: Confirm Generation In interactive mode, confirm the proposed changes before they are applied. ### Step 4: Verify in Your Project Check the `editors/` directory in your project for the generated editor files. The editor should be registered in your `powerhouse.manifest.json`. ### Step 5: Test the Editor Run Vetra Studio and open your document to test the new editor interface. ### Expected outcome - Editor components are generated in the `editors/` directory - The editor is registered in `powerhouse.manifest.json` - The editor integrates with your document model operations - You can interact with documents through the new UI ### Common issues and solutions - Issue: Editor doesn't appear in Vetra Studio - Solution: Verify the editor is registered in `powerhouse.manifest.json`. Restart Vetra Studio with `--watch`. - Issue: Operations not working in the editor - Solution: Ensure the editor references the correct operation names from your document model. - Issue: Styling doesn't match expectations - Solution: Provide more detailed design requirements or manually adjust the generated CSS/styles. ### Related recipes - [Creating a Document Model with AI Assistance](#creating-a-document-model-with-ai-assistance) - [Generating a Document Editor](#generating-a-document-editor) - [Connecting Claude with Reactor MCP](#connecting-claude-with-reactor-mcp) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Build a Todo-list Editor](/academy/Build/ManualTodoTutorial/BuildToDoListEditor) </details> ### Project Initialization & Management Creating, configuring, and managing Powerhouse projects, which are collections of document models, editors, and other resources. <details id="initializing-a-new-project-and-document-model"> <summary>Initializing a New Project & Document Model</summary> ### How to initialize a new project and document model --- ### Problem statement You need to create a new, empty document model within a Powerhouse project to represent a workflow of a business process. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (see [Initializing a Powerhouse Project Recipe](#powerhouse-cli-recipes)) or follow Step 1 & 2 below. - Access to a terminal or command prompt - A web browser ### Solution > Recommended: Use Vetra Studio for document model development. Vetra provides automatic code generation and a live preview with `ph vetra --watch`. See [Launching Vetra Studio](#launching-vetra-studio) for the preferred workflow. ### Step 1: Initialize a Powerhouse Project (if needed) If you haven't already, create a new Powerhouse project: ```bash ph init # Follow the prompts to name your project ``` ### Step 2: Navigate to Project Directory Change your current directory to the newly created project folder: ```bash cd <yourprojectname> ``` ### Step 3: Start Vetra Studio (Recommended) Run Vetra with watch mode for automatic code generation and live preview: ```bash ph vetra --watch ``` This will: - Launch Vetra Studio in your browser - Automatically generate code when you make changes to document models - Provide live preview of your documents and editors ### Step 4: Create the Document Model In Vetra Studio, navigate to your drive and click the `DocumentModel` button to create a new document model. ### Alternative: Using Connect (Legacy) If you need to use the Connect application instead: ```bash ph connect ``` Wait for the output indicating the server is running (e.g., `Local: http://localhost:3000/`). ### Expected outcome - An empty document model is created and opened in the Document Model Editor. - You are ready to start defining the schema and logic for your new model. - With Vetra, code is automatically generated as you make changes. ### Common issues and solutions - Issue: `ph vetra` command fails. - Solution: Ensure `ph-cmd` is installed correctly (`ph-cmd --version`). Check for port conflicts. Make sure you are inside the project directory created by `ph init`. - Issue: Browser window doesn't open automatically. - Solution: Manually open the URL shown in the terminal output. - Issue: Cannot find the `DocumentModel` button. - Solution: Ensure you have navigated into your drive within the application first. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Creating a Document Model with AI Assistance](#creating-a-document-model-with-ai-assistance) - [Initializing a Powerhouse Project](#powerhouse-cli-recipes) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [GraphQL Schema Best Practices](/academy/Build/WorkWithData/UsingTheAPI) </details> <details id="generating-reducers-from-a-document-model-file"> <summary>Generating Reducers from a Document Model File</summary> ### How to Generate Reducers from a Document Model File --- ### Problem statement You have a Powerhouse Document Model defined in a `.phdm` or `.phdm.zip` file and need to generate the corresponding reducer functions for your project. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - A `.phdm` or `.phdm.zip` file containing your document model definition, placed in your project (e.g., at the root). ### Solution > Recommended: Use Vetra Studio with `ph vetra --watch` for automatic code generation. Vetra watches for changes to your document models and automatically generates reducers and other code. See [Launching Vetra Studio](#launching-vetra-studio). ### Using Vetra (Recommended) With Vetra running in watch mode, code generation happens automatically: ```bash ph vetra --watch ``` When you make changes to document models in Vetra Studio, reducers and other code are generated automatically. ### Manual Generation (Alternative) If you need to manually generate code from a `.phdm` file: ### Step 1: Navigate to Project Directory Ensure your terminal is in the root directory of your Powerhouse project. ```bash cd <yourprojectname> ``` ### Step 2: Run the Generate Command Execute the `ph generate` command, providing the path to your document model file. ```bash # Replace todo.phdm.zip with the actual filename/path of your model ph generate todo.phdm.zip ``` ### Step 3: Integrate Generated Code The command will output the generated reducer scaffolding code in the designated folders. ### Expected outcome - Reducer functions corresponding to the operations defined in your document model are generated. - The generated code is ready to be integrated into your project's state management logic. - With Vetra, this happens automatically when you save changes. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) - [Generating a Document Editor](#generating-a-document-editor) </details> <details id="managing-and-updating-powerhouse-dependencies"> <summary>Managing and Updating Powerhouse Dependencies</summary> ### How to Manage and Update Powerhouse Dependencies --- ### Problem statement You need to understand and manage different types of dependencies in your Powerhouse project, and know how to update them using `ph update` and `ph use` commands. This includes updating based on version ranges, switching between development environments, and understanding the Powerhouse branching strategy. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - Terminal or command prompt access ### Solution ### Understanding Dependency Types #### 1. Monorepo Dependencies (Powerhouse Core) The Powerhouse monorepo uses a specific branching strategy: - Development (`dev` tag): Ongoing development on the main branch - Staging (`staging` tag): Pre-release branch (`Release/staging/v.x.x`) - Production (`latest` or `prod` tag): Latest stable release (`Release/production/v.x.x`) You can install CLI versions matching these environments: ```bash # Install dev version of CLI pnpm install -g ph-cmd@dev # Install staging version pnpm install -g ph-cmd@staging # Install latest stable version pnpm install -g ph-cmd ``` #### 2. Project Dependencies These are dependencies from published npm packages in your `package.json`. ### Using `ph update`: Version Range Updates Use `ph update` to update dependencies based on the semver ranges in your `package.json`: #### Step 1: Standard Update (Respect Version Ranges) Update all Powerhouse dependencies within the ranges specified in your `package.json`: ```bash ph update ``` This updates packages like `@powerhousedao/` and `document-model` to their latest versions that satisfy your version constraints. ### Step 2: Force Update to Specific Environment Override version ranges and force all dependencies to a specific environment: ```bash # Force update to latest dev versions ph update --force dev # Force update to latest stable/production versions ph update --force prod # or ph update --force latest ``` #### Step 3: Specify Package Manager (Optional) ```bash ph update --package-manager pnpm ``` ### Using `ph use`: Environment Switching Use `ph use` to quickly switch all dependencies between environments or versions: #### Switching to Development Environment ```bash ph use dev ``` This switches all installed Powerhouse dependencies to their `@dev` tagged versions. #### Switching to Staging Environment ```bash ph use staging ``` #### Switching to Production Environment ```bash ph use prod # or ph use latest ``` #### Switching to Specific Version ```bash # Use a specific release version ph use 5.1.0 # Use a pre-release version ph use 1.0.0-beta.1 ``` #### Using Local Development Versions For active development, link to local packages: ```bash ph use local /path/to/powerhouse/monorepo ``` #### Resolving Tags to Exact Versions Use `--use-resolved` to resolve tags to actual version numbers: ```bash ph use dev --use-resolved ``` This resolves `@dev` to an exact version like `v1.0.1-dev.1` instead of using the tag. ### Initializing Projects with Specific Environments When creating new projects, you can specify the environment: ```bash # Initialize with dev dependencies ph init my-project --dev # Initialize with staging dependencies ph init my-project --staging # Initialize with production dependencies (default) ph init my-project ``` ### Publishing Updated Dependencies If you're developing packages: 1. Update dependencies in your project using `ph use` or `ph update` 2. Test thoroughly 3. Publish the updated package to npm: ```bash pnpm build npm publish ``` 4. Other projects get the new version when they run `ph install your-package` ### Expected outcome - Clear understanding of Powerhouse dependency types and environments - Ability to update dependencies based on version ranges with `ph update` - Ability to switch between environments with `ph use` - Knowledge of the dev/staging/prod branching strategy - Understanding of when to use each command ### Common issues and solutions - Issue: Dependencies not updating as expected - Solution: Check your `package.json` version ranges. Use `ph update --force <env>` to override ranges. - Issue: Confusion between `ph update` and `ph use` - Solution: Use `ph update` for version range updates. Use `ph use` for environment switching. - Issue: Breaking changes after updates - Solution: Test thoroughly. Consider publishing to a private npm registry first. Use staging environment before production. - Issue: Local development changes not reflecting - Solution: Use `ph use local /path/to/monorepo` and ensure you've built the local packages. - Issue: Which version am I using? - Solution: Check `package.json` for installed versions. Use `ph list` to see installed packages. ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Using Different Branches in Powerhouse](#using-different-branches-in-powerhouse) - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration) - [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package) ### Further reading - [Powerhouse CLI Reference: Update Command](/academy/Reference/CLITooling/PowerhouseCLI#update) - [Powerhouse CLI Reference: Use Command](/academy/Reference/CLITooling/PowerhouseCLI#use) - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> <details id="running-connect-with-https-and-a-custom-port"> <summary>Running Connect with HTTPS and a Custom Port</summary> ### How to Run Connect with HTTPS and a Custom Port --- ### Problem statement You need to run the local Powerhouse application using HTTPS, possibly on a different port than the default, for scenarios like testing on a remote server (e.g., EC2) or complying with specific network requirements. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - Potentially, valid SSL/TLS certificates if running in a non-localhost environment that requires trusted HTTPS. (The `--https` flag may use self-signed certificates for local development). ### Solution > Note: For local development, Vetra Studio (`ph vetra --watch`) is the recommended workflow as it provides automatic code generation and live preview. Use the options below when you specifically need HTTPS or custom port configurations. ### Step 1: Navigate to Project Directory Ensure your terminal is in the root directory of your Powerhouse project. ```bash cd <yourprojectname> ``` ### Step 2: Run with Flags #### Using Vetra (Recommended for Development) ```bash # Vetra with watch mode for automatic code generation ph vetra --watch ``` #### Using Connect (for HTTPS/Custom Port) Execute the `ph connect` command, adding the `--https` flag to enable HTTPS and the `--port` flag followed by the desired port number. ```bash # Example using port 8442 ph connect --port 8442 --https ``` ### Step 3: Access the Application Open your web browser and navigate to the specified address. Remember to use `https` and include the custom port. ``` https://<your-hostname-or-ip>:<port> # Example: https://localhost:8442 # Example: https://my-ec2-instance-ip:8442 ``` You might encounter a browser warning about the self-signed certificate; you may need to accept the risk to proceed for local/development testing. ### Expected outcome - The Powerhouse application starts and serves traffic over HTTPS on the specified port. - You can access the interface securely using the `https` protocol. ### Common issues and solutions - Issue: Browser shows security warnings (e.g., "Your connection is not private"). - Solution: This is expected when using the default self-signed certificate generated by `--https`. For development or internal testing, you can usually proceed by accepting the risk. For production or public-facing scenarios, configure with properly signed certificates (consult Powerhouse documentation for advanced configuration). - Issue: Port conflict (e.g., `"Port <port> is already in use"`). - Solution: Choose a different port number that is not currently occupied by another application. - Issue: Cannot access from a remote machine. - Solution: Ensure the port is open in any firewalls (on the server and potentially network firewalls). Verify you are using the correct public IP address or hostname of the machine. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> ### Editors & Drive-apps Generating and customizing editors for Document Models and custom interfaces for Drives. <details id="generating-a-document-editor"> <summary>Generating a Document Editor</summary> ### How to Generate a Document Editor --- ### Problem statement You have a Powerhouse document model and need to create a user interface (editor) for it. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - A document model generated or defined within the project (e.g., in the `document-models` directory). ### Solution > Recommended: Use Vetra Studio with `ph vetra --watch` for editor development. Vetra automatically generates editor scaffolding and provides live preview as you develop. See [Launching Vetra Studio](#launching-vetra-studio) and [Creating an Editor with AI Assistance](#creating-an-editor-with-ai-assistance). ### Using Vetra (Recommended) Start Vetra with watch mode for automatic code generation and live preview: ```bash ph vetra --watch ``` In Vetra Studio, you can: - Create editors visually or with AI assistance - See live preview of your editor as you make changes - Automatically generate editor scaffolding ### Manual Generation (Alternative) If you need to manually generate an editor template: ### Step 1: Navigate to Project Directory Ensure your terminal is in the root directory of your Powerhouse project. ```bash cd <yourprojectname> ``` ### Step 2: Generate the Editor Template Run the `generate` command, specifying the editor name (usually matching the document model name) and the associated document type. ```bash # Replace <ModelName> with the name of your document model (e.g., To-do List) # Replace <docType> with the identifier for your document (e.g., powerhouse/todo-list) ph generate --editor <ModelName> --document-types <docType> ``` ### Expected outcome - A new directory is created under `editors/` (e.g., `editors/<model-name>/`). - An `editor.tsx` file is generated within that directory, containing a basic template for your document editor. - You can now customize `editor.tsx` to build your desired UI using HTML, Tailwind CSS, or custom CSS. - With Vetra, you get live preview with `ph vetra --watch` as you develop. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Creating an Editor with AI Assistance](#creating-an-editor-with-ai-assistance) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) - [Generating a Custom Drive-app](#generating-a-custom-drive-app) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Build a Todo-list Editor](/academy/Build/ManualTodoTutorial/BuildToDoListEditor) </details> <details id="generating-a-custom-drive-app"> <summary>Generating a Custom Drive-app</summary> ### How to Generate a Custom Drive-app --- ### Problem statement You need a custom, application-like interface to browse, organize, or interact with specific types of documents stored within a Powerhouse drive, going beyond the standard file listing. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) ### Solution > Recommended: Use Vetra Studio with `ph vetra --watch` for drive explorer development. Vetra provides automatic code generation and live preview as you build your custom drive interface. See [Launching Vetra Studio](#launching-vetra-studio). ### Using Vetra (Recommended) Start Vetra with watch mode for automatic code generation and live preview: ```bash ph vetra --watch ``` Vetra Studio allows you to develop and preview your Drive-app in real-time. ### Manual Generation (Alternative) If you need to manually generate a Drive-app template: ### Step 1: Navigate to Project Directory Ensure your terminal is in the root directory of your Powerhouse project. ```bash cd <yourprojectname> ``` ### Step 2: Generate the Drive-app Template Run the `generate` command, specifying the `--drive-editor` flag and a name for your Drive-app. ```bash # Replace <drive-app-name> with a suitable name for your Drive-app (e.g., todo-drive-app) ph generate --drive-editor <drive-app-name> ``` ### Expected outcome - A new directory is created under `editors/` (e.g., `editors/<drive-app-name>/`). - Template files (`EditorContainer.tsx`, components, hooks, etc.) are generated within that directory, providing a basic structure for a Drive-app. - You can now customize these files to create your specific drive interface, potentially removing default components and adding custom views relevant to your document models. - Remember to update your `powerhouse.manifest.json` to register the new app. - With Vetra, you get live preview with `ph vetra --watch` as you develop. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Generating a Document Editor](#generating-a-document-editor) ### Further reading - [Vetra Studio Documentation](/academy/GetStarted/VetraStudio) - [Build a Drive-app](/academy/Build/BuildingUserExperiences/BuildingADriveExplorer) </details> <details id="adding-a-new-drive-via-graphql-mutation"> <summary>Adding a New Drive via GraphQL Mutation</summary> ### How to Add a New Remote Drive via GraphQL Mutation --- ### Problem statement You want to programmatically add a new remote drive to your Powerhouse Connect environment using a GraphQL mutation. This is useful for automation, scripting, or integrating with external systems. ### Prerequisites - Access to the Switchboard or remote reactor (server node) of your Connect instance. - The GraphQL endpoint for your instance (e.g., `https://staging.switchboard.phd/graphql/system`). - Appropriate permissions to perform mutations. ### Solution ### Step 1: Access the GraphQL Playground or Client Open the GraphQL Playground at your endpoint (e.g., [https://staging.switchboard.phd/graphql/system](https://staging.switchboard.phd/graphql/system)), or use a GraphQL client of your choice. ### Step 2: Prepare the Mutation Use the following mutation to create a new drive, set a name and add a drive icon. Weither or not you define a ID & Slug is up to you: ```graphql mutation Mutation( $name: String! $icon: String $addDriveId: String $slug: String ) { addDrive(name: $name, icon: $icon, id: $addDriveId, slug: $slug) { icon id name slug } } ``` Example variables: ```json { "name": "AcademyTest", "icon": "https://static.thenounproject.com/png/3009860-200.png", "addDriveId": null, "slug": null } ``` You can also provide a custom `id`, `slug`, or `preferredEditor` if needed. ### Step 3: Execute the Mutation Run the mutation. On success, you will receive a response containing the new drive's `icon`, `id`, `name`, and `slug`: ```json { "data": { "addDrive": { "icon": "https://static.thenounproject.com/png/3009860-200.png", "id": "6461580b-d317-4596-942d-f6b3d1bfc8fd", "name": "AcademyTest", "slug": "6461580b-d317-4596-942d-f6b3d1bfc8fd" } } } ``` ### Step 4: Construct the Drive URL Once you have the `id` or `slug`, you can construct the drive URL for Connect: - Format: `domain/d/driveId` or `domain/d/driveSlug` - Example: `https://staging.connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd` ### Step 5: Add the Drive in Connect Use the constructed URL to add or access the drive in your Connect environment. ### Expected outcome - A new drive is created and accessible in your Connect environment. - The drive can be managed or accessed using the generated URL. ### Related recipes - [Configuring Drives](/academy/Build/WorkWithData/ConfiguringDrives) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) ### Further reading - [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/) - [Powerhouse Builder Tools](/academy/Build/GettingStartedBuilding/BuilderTools) </details> ### Package Publishing & Distribution Creating, installing, and managing Powerhouse Packages for distribution and reuse. <details id="packaging-and-publishing-a-powerhouse-project"> <summary>Packaging and Publishing a Powerhouse Project</summary> ### How to Package and Publish a Powerhouse Project --- ### Problem statement You have created a collection of document models, editors, or other components and want to share it as a reusable package on a public or private npm registry. Publishing a package allows other projects to install and use your creations easily. ### Prerequisites - A completed Powerhouse project that you are ready to share. - An account on [npmjs.com](https://www.npmjs.com/) (or a private registry). - Your project's `package.json` should have a unique name and correct version. - You must be logged into your npm account via the command line. ### Solution ### Step 1: Build the Project First, compile your project to create a production-ready build in the `dist/` or `build/` directory. ```bash pnpm build ``` ### Step 2: Log In to npm If you aren't already, log in to your npm account. You will be prompted for your username, password, and one-time password. ```bash npm login ``` ### Step 3: Version Your Package Update the package version according to semantic versioning. This command updates `package.json` and creates a new Git tag. ```bash # Choose one depending on the significance of your changes pnpm version patch # For bug fixes (e.g., 1.0.0 -> 1.0.1) pnpm version minor # For new features (e.g., 1.0.1 -> 1.1.0) pnpm version major # For breaking changes (e.g., 1.1.0 -> 2.0.0) ``` ### Step 4: Publish the Package Publish your package to the npm registry. If it's your first time publishing a scoped package (e.g., `@your-org/your-package`), you may need to add the `--access public` flag. ```bash npm publish --access public ``` ### Step 5: Push Git Commits and Tags Push your new version commit and tag to your remote repository to keep it in sync. ```bash # Push your current branch git push # Push the newly created version tag git push --tags ``` ### Expected outcome - Your Powerhouse project is successfully published to the npm registry. - Other developers can now install your package into their projects using `ph install @your-org/your-package-name`. - Your Git repository is updated with the new version information. ### Common issues and solutions - Issue: "403 Forbidden" or "You do not have permission" error on publish. - Solution: Ensure your package name is unique and not already taken on npm. If it's a scoped package (`@scope/name`), make sure the organization exists and you have permission to publish to it. For public scoped packages, you must include `--access public`. ### Related recipes - [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package) - [Managing and Updating Powerhouse Dependencies](#managing-and-updating-powerhouse-dependencies) </details> <details id="installing-a-custom-powerhouse-package"> <summary>Installing a Custom Powerhouse Package</summary> ### How to Install a Custom Powerhouse Package --- ### Problem statement You have developed and published a Powerhouse package (containing document models, editors, etc.) to npm, or you have a local package, and you need to install it into another Powerhouse project. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) where you want to install the package. - The custom package is either published to npm or available locally. ### Solution ### Step 1: Navigate to the Target Project Directory Ensure your terminal is in the root directory of the Powerhouse project where you want to install the package. ```bash cd <your-target-project-name> ``` ### Step 2: Install the Package Use the `ph install` command followed by the package name (if published to npm) or the path to the local package. For npm packages: ```bash # Replace <your-package-name> with the actual name on npm ph install <your-package-name> ``` For local packages (using a relative or absolute path): ```bash # Example using a relative path ph install ../path/to/my-local-package # Example using an absolute path ph install /Users/you/dev/my-local-package ``` ### Step 3: Verify Installation Check your project's `package.json` and `powerhouse.manifest.json` to ensure the package dependency has been added correctly. Run `ph vetra --watch` (or `ph connect`) to see if the components from the installed package are available. ### Expected outcome - The custom Powerhouse package is downloaded and installed into your project's dependencies. - The `powerhouse.manifest.json` is updated (if necessary) to reflect the installed package. - Document models, editors, Drive-apps, or other components from the package become available within the target project. ### Common issues and solutions - Issue: Package not found (npm). - Solution: Double-check the package name for typos. Ensure the package is published and accessible on npm. - Issue: Path not found (local). - Solution: Verify the relative or absolute path to the local package directory is correct. - Issue: Conflicts with existing project components or dependencies. - Solution: Resolve version conflicts or naming collisions as needed. Review the installed package's structure and dependencies. ### Related recipes - [Publishing a Powerhouse Package](#publishing-a-powerhouse-package) - [Initializing a Powerhouse Project](#initializing-a-new-project-and-document-model) </details> ## Deployment recipes This section covers deploying Powerhouse applications and packages to various environments using Docker and other deployment methods. <details id="deploying-powerhouse-with-docker"> <summary>Deploying Powerhouse with Docker</summary> ### How to Deploy Powerhouse with Docker --- ### Problem statement You want to deploy your Powerhouse application (Connect and Switchboard) using Docker containers for production or development environments. Docker deployment provides consistency, reproducibility, and easy scalability across different platforms. ### Prerequisites - Docker installed on your system - Docker Compose installed (usually included with Docker Desktop) - Basic understanding of Docker concepts - (Optional) A custom Powerhouse package to deploy ### Solution ### Step 1: Create a Docker Compose Configuration Create a `docker-compose.yml` file in your project directory: ```yaml name: powerhouse services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:latest environment: - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres - PH_CONNECT_BASE_PATH=/ ports: - "127.0.0.1:3000:4000" networks: - powerhouse_network depends_on: postgres: condition: service_healthy switchboard: image: ghcr.io/powerhouse-inc/powerhouse/switchboard:latest environment: - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres ports: - "127.0.0.1:4000:4001" networks: - powerhouse_network depends_on: postgres: condition: service_healthy postgres: image: postgres:16.1 ports: - "127.0.0.1:5444:5432" environment: - POSTGRES_PASSWORD=postgres - POSTGRES_DB=postgres - POSTGRES_USER=postgres volumes: - postgres_data:/var/lib/postgresql/data networks: - powerhouse_network healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 5s timeout: 3s retries: 3 networks: powerhouse_network: name: powerhouse_network volumes: postgres_data: ``` ### Step 2: Install Custom Packages (Optional) If you have custom Powerhouse packages to deploy, add them via the `PH_PACKAGES` environment variable: ```yaml services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:latest environment: - PH_PACKAGES=@powerhousedao/your-package,@powerhousedao/another-package - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres ``` ### Step 3: Start the Services Launch all services in detached mode: ```bash docker compose up -d ``` ### Step 4: Verify Deployment Check that all services are running: ```bash docker compose ps ``` View logs to confirm successful startup: ```bash docker compose logs -f ``` ### Step 5: Access Your Application Once services are running, access: - Connect: http://localhost:3000 - Switchboard API: http://localhost:4000 ### Production Configuration For production deployments, use specific version tags and secure credentials: ```yaml services: connect: image: ghcr.io/powerhouse-inc/powerhouse/connect:v1.0.0 env_file: - .env switchboard: image: ghcr.io/powerhouse-inc/powerhouse/switchboard:v1.0.0 env_file: - .env ``` Create a `.env` file with secure credentials: ```bash POSTGRES_PASSWORD=your-secure-password DATABASE_URL=postgres://powerhouse:your-secure-password@postgres:5432/powerhouse ``` ### Expected outcome - All Powerhouse services (Connect, Switchboard, PostgreSQL) are running in Docker containers - Services can communicate with each other through the Docker network - Your custom packages (if specified) are installed and available - The application is accessible through the configured ports - Data is persisted in Docker volumes ### Common issues and solutions - Issue: Container fails to start with "port already in use" error - Solution: Change the port mapping in `docker-compose.yml` to use an available port (e.g., `3001:4000` instead of `3000:4000`) - Issue: Database connection errors on startup - Solution: Ensure the `depends_on` configuration includes health checks so services wait for PostgreSQL to be ready - Issue: Custom packages fail to install - Solution: Verify package names are correct and published to npm. Check container logs with `docker compose logs switchboard` or `docker compose logs connect` - Issue: Changes to docker-compose.yml not taking effect - Solution: Run `docker compose down` then `docker compose up -d` to recreate containers with new configuration - Issue: Permission errors with volumes - Solution: Ensure the volume paths have correct permissions: `sudo chown -R 1000:1000 ./data` ### Related recipes - [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package) - [Setting up a Production Environment](#setting-up-a-production-environment) - [Publishing a Powerhouse Package](#packaging-and-publishing-a-powerhouse-project) ### Further reading - [Docker Deployment Guide](/academy/Build/Launch/DockerDeployment) - [Environment Configuration](/academy/Build/Launch/ConfigureEnvironment) - [Setup Environment Guide](/academy/Build/Launch/SetupEnvironment) - [Docker Compose Documentation](https://docs.docker.com/compose/) </details> <details id="setting-up-a-production-environment"> <summary>Setting up a Production Environment</summary> ### How to set up a Production Powerhouse Environment --- ### Problem statement You need to set up a new production-ready server to host and run your Powerhouse services (Connect and Switchboard). ### Prerequisites - A Linux-based server (Ubuntu or Debian recommended) with `sudo` privileges. - A registered domain name. - DNS `A` records for your `connect` and `switchboard` subdomains pointing to your server's public IP address. ### Solution ### Step 1: Install Powerhouse Services SSH into your server and run the universal installation script. This will install Node.js, pnpm, and prepare the system for Powerhouse services. ```bash curl -fsSL https://apps.powerhouse.io/install | bash ``` ### Step 2: Reload Your Shell After the installation, reload your shell's configuration to recognize the new commands. ```bash source ~/.bashrc # Or source ~/.zshrc if using zsh ``` ### Step 3: Initialize a Project Create a project directory for your services. The `ph-init` command sets up the basic structure. Move into the directory after creation. ```bash ph-init my-powerhouse-services cd my-powerhouse-services ``` ### Step 4: Configure Services Run the interactive setup command. This will guide you through configuring Nginx, PM2, databases, and SSL. ```bash ph service setup ``` During the setup, you will be prompted for: - Packages to install: You can pre-install any Powerhouse packages you need. (Optional) - Database: Choose between a local PostgreSQL setup or connecting to a remote database. - SSL Certificate: Select Let's Encrypt for a production setup. You will need to provide your domain and subdomains. ### Expected outcome - Powerhouse Connect and Switchboard services are installed, configured, and running on your server. - Nginx is set up as a reverse proxy with SSL certificates from Let's Encrypt. - Services are managed by PM2 and will restart automatically on boot or if they crash. - You can access your services securely at `https://connect.yourdomain.com` and `https://switchboard.yourdomain.com`. ### Common issues and solutions - Issue: `ph: command not found` - Solution: Ensure you have reloaded your shell with `source ~/.bashrc` or have restarted your terminal session. - Issue: Let's Encrypt SSL certificate creation fails. - Solution: Verify that your domain's DNS records have fully propagated and are pointing to the correct server IP. This can take some time. - Issue: Services fail to start. - Solution: Check the service logs for errors using `ph service logs` or `pm2 logs`. ### Related recipes - [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package) - [Deploying Powerhouse with Docker](#deploying-powerhouse-with-docker) ### Further reading - [Full Setup Guide](/academy/Build/Launch/SetupEnvironment) </details> ## Reactor & Data Synchronisation recipes This section covers managing the Powerhouse Reactor (the local service for processing document model operations) and troubleshooting data synchronization within the Powerhouse ecosystem. > Tip: For development workflows, Vetra Studio (`ph vetra --watch`) is recommended as it includes reactor functionality along with automatic code generation and live preview. ### Reactor Recipes The [Powerhouse Recipes](https://github.com/powerhouse-inc/recipes) repository contains standalone example projects that demonstrate common Reactor patterns and integrations. Each recipe is a self-contained project you can clone and run. {/* AUTO-GENERATED-RECIPE-DOCS-START /} {/ This content is automatically generated by scripts/generate-recipe-docs.ts. Do not edit directly. /} | Recipe | Description | | --- | --- | | [Analytics Processor](https://github.com/powerhouse-inc/recipes/tree/main/analytics-processor) | A Reactor processor that projects expense-report line items into the Powerhouse analytics engine — a dedicated dimensional time-series store — and a query layer that reads aggregations back out. | | [Audit Trail](https://github.com/powerhouse-inc/recipes/tree/main/audit-trail) | A Reactor processor that inspects `ActionSigner` context on every operation to build an immutable audit log in PostgreSQL. | | [Batch Progress](https://github.com/powerhouse-inc/recipes/tree/main/batch-progress) | Demonstrates multi-document wizard creation with dependency ordering using Reactor's `executeBatch` and real-time progress tracking via the EventBus. | | [Cross-Document Reactor](https://github.com/powerhouse-inc/recipes/tree/main/cross-document-reactor) | Event-driven cross-document automation using `ReactorClient` subscriptions. | | [Custom Read Model](https://github.com/powerhouse-inc/recipes/tree/main/custom-read-model) | A custom `IReadModel` implementation registered via `ReactorBuilder.withReadModel()` that maintains a document-count-per-type materialized view. | | [DB Migrate](https://github.com/powerhouse-inc/recipes/tree/main/db-migrate) | PostgreSQL database export, import, and migration scripts using Docker. | | [Discord Webhook Processor](https://github.com/powerhouse-inc/recipes/tree/main/discord-webhook-processor) | A Reactor `IProcessor` that posts document operations to a Discord channel via webhook. | | [Document Snapshot Exporter](https://github.com/powerhouse-inc/recipes/tree/main/document-snapshot-exporter) | CLI tool that exports document state and operation history to JSON files, demonstrating reliable read-after-write consistency using the Reactor API. | | [Document Versioning](https://github.com/powerhouse-inc/recipes/tree/main/document-versioning) | Evolve a document model's schema from v1 to v2 with an `UpgradeManifest` and a pure `upgradeReducer`, so documents created under the old schema keep loading and replaying correctly. | | [Drive Override](https://github.com/powerhouse-inc/recipes/tree/main/drive-override) | A custom container document that tracks its children via the reactor's `ADD_RELATIONSHIP` system action instead of the `document-drive` model's `ADD_FILE`. | | [External Feed Ingest](https://github.com/powerhouse-inc/recipes/tree/main/external-feed-ingest) | A polling worker that pulls an off-platform feed into event-sourced documents idempotently. | | [Full-Text Search Processor](https://github.com/powerhouse-inc/recipes/tree/main/full-text-search) | A Reactor `IProcessor` that indexes document state into a PostgreSQL full-text search table, enabling ranked keyword search across all documents managed by a Reactor instance. | | [Inbound Webhook Bridge](https://github.com/powerhouse-inc/recipes/tree/main/inbound-webhook-bridge) | Receive external webhooks (Stripe-style), verify the signature server-side against the raw request bytes, and map verified events onto document actions. | | [Rate Limiter](https://github.com/powerhouse-inc/recipes/tree/main/rate-limiter) | A Reactor `IProcessor` paired with an `AuthService` gate to throttle users by signer address, preventing any single user from overwhelming the system with excessive operations. | | [Relational DB Subgraph](https://github.com/powerhouse-inc/recipes/tree/main/relational-db-subgraph) | A complete relational DB processor recipe demonstrating the academy flagship tutorial pattern: | | [Role-Based Auth](https://github.com/powerhouse-inc/recipes/tree/main/role-based-auth) | A custom document model where the creator is promoted to admin on first action, admins can grant or revoke admin and member roles, and a domain action (`writeNote`) is gated on member-or-higher. | | [Saga](https://github.com/powerhouse-inc/recipes/tree/main/saga) | Saga pattern via Reactor processor: operations on one document trigger operations on others, linked by a traceable saga context. | | [Semantic Search Processor](https://github.com/powerhouse-inc/recipes/tree/main/semantic-search) | A Reactor `IProcessor` that embeds document content with an in-process model (Transformers.js) into PGlite's `vector` extension and answers cosine-similarity queries — the semantic sibling of the [full-text-search](#recipe-full-text-search) recipe. | | [Signed Operations Verifier](https://github.com/powerhouse-inc/recipes/tree/main/signed-operations-verifier) | A standalone script that builds a document operation history with cryptographic signatures, then verifies each one. | | [Subscription CLI](https://github.com/powerhouse-inc/recipes/tree/main/subscription-cli) | A standalone CLI for monitoring Powerhouse Reactor GraphQL subscriptions over WebSocket in real time. | | [Sync Health Monitor](https://github.com/powerhouse-inc/recipes/tree/main/sync-health-monitor) | Subscribes to `SyncEventTypes` on the Reactor EventBus and maintains a live health dashboard. | > See the [recipes repository](https://github.com/powerhouse-inc/recipes) for full source code, setup instructions, and prerequisites. <details id="recipe-analytics-processor"> <summary><strong>Analytics Processor</strong> — A Reactor processor that projects expense-report line items into the Powerhouse analytics engine — a dedicated dimensional time-series store — and a query layer that reads aggregations back out.</summary> ### Analytics Processor A Reactor processor that projects expense-report line items into the Powerhouse analytics engine — a dedicated dimensional time-series store — and a query layer that reads aggregations back out. Everything runs in-process (the store is backed by PGlite, an embedded PostgreSQL), so the demo needs no external services. #### What it demonstrates - Implementing `IProcessor` (from `@powerhousedao/reactor`) whose constructor receives an `IAnalyticsStore`, registered through a `ProcessorFactory` with a document-type filter and `startFrom: "beginning"`. - Mapping `ADD_LINE_ITEM` / `UPDATE_LINE_ITEM` / `DELETE_LINE_ITEM` operations into append-only series values: updates and deletes write compensating entries (−old, +new) instead of mutating history. - Idempotent reprocessing — the `clearSource` pattern. A processor registered with `startFrom: "beginning"` can be re-delivered the full operation history at any time (e.g. after a restart). Seeing operation index 0 again for a known document means "replay": the processor clears that document's series (`clearSeriesBySource`) and rebuilds, so reprocessing always converges to the same totals. - Building hierarchical `AnalyticsPath` dimensions from user data (slugified category names like `ph/expenses/category/headcount/salaries`). - Querying with `AnalyticsQueryEngine`: totals per category, monthly aggregation, and a category × currency breakdown using `lod` (level of detail) to roll subcategories up into their parents. - A document model generated with `ph generate` from a spec JSON (`document-models/expense-report/expense-report.json`), the same workflow as the `role-based-auth` recipe. #### When to use the analytics engine vs a SQL read model | | analytics-processor (this recipe) | custom-read-model | relational-db-subgraph | |---|---|---|---| | Storage model | Dimensional time-series (source, metric, dimensions, unit) | In-memory map | Relational rows (Kysely schema) | | Query style | Time-bucketed aggregates, dimension rollups via `lod` | Direct lookup | Arbitrary SQL: joins, filters, ordering | | Best for | "Total per category per month in USD" — dashboards, budgets, spend analytics | Simple derived counts | Searchable catalogs, tag filters | Use the analytics engine when queries are shaped like aggregate metric X, grouped by dimension Y, over period Z, rolled up to depth N. Use `relational-db-subgraph` when you need relational queries, and `custom-read-model` for lightweight synchronous counters. #### Key concepts - Source — an `AnalyticsPath` identifying who owns a set of series. This recipe uses one source per document (`ph/expenses/<documentId>`), so a single `clearSeriesBySource(source, true)` wipes exactly that document during a replay. - Dimensions — named `AnalyticsPath`s attached to every value (`category`, `currency` here). Queries `select` on dimension path prefixes and group by the (lod-truncated) paths. - Metric + unit — the metric is a plain string (`"Expenses"`); the unit carries the currency code. One series per currency — the engine never sums across units, which keeps USD and EUR amounts separate. - Business time vs event time — series values are dated by the line item's `date` field (when the money was spent), not by the operation timestamp and never by processing time. A correction made in March to a January expense still lands in January. - lod (level of detail) — truncates dimension paths to N segments at query time: `lod: { category: 4 }` collapses `ph/expenses/category/headcount/salaries` into `ph/expenses/category/headcount`. Every key in `select` needs a `lod` entry. - Explicit query windows — the engine can derive a missing start/end from the data, but it is fragile on degenerate inputs; the query layer always passes an explicit window. #### Files | File | Purpose | |---|---| | `document-models/expense-report/` | Generated document model (`example/expense-report`); reducers in `v1/src/`, spec in `expense-report.json` | | `src/processor.ts` | `ExpenseAnalyticsProcessor`, path helpers, processor factory | | `src/query.ts` | Query functions over `AnalyticsQueryEngine` + table rendering | | `src/demo.ts` | End-to-end demo | | `src/processor.test.ts` | Processor tests against a real PGlite-backed store | #### Setup ```sh pnpm install pnpm build ``` #### Running the demo ```sh pnpm start ``` Boots a reactor, creates three expense reports, dispatches nine adds, one amount correction, and one delete, waits for the processor via the processor-manager consistency tracker (no sleeps), then prints three aggregation tables. #### Tests ```sh pnpm test ``` Covers the delta arithmetic (add/update/delete, date-moving updates), idempotent replay (same operations delivered twice → same totals), source clearing isolation between documents, slug escaping of hostile category names, currency separation, and skipping of failed operations. #### Regenerating the document model ```sh pnpm generate document-model --document document-models/expense-report/expense-report.json ``` Requires the Powerhouse monorepo checked out next to this repo (the script calls `../../powerhouse/clis/ph-cli/dist/cli.mjs`). Note that the generated output targets a newer `document-model` than the catalog pin; a few imports are adjusted to the `document-model/core` subpath (marked with comments) and `v1/hooks.ts` (which requires `@powerhousedao/reactor-browser`) is removed. #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/analytics-processor) </details> <details id="recipe-audit-trail"> <summary><strong>Audit Trail</strong> — A Reactor processor that inspects `ActionSigner` context on every operation to build an immutable audit log in PostgreSQL.</summary> ### Audit Trail A Reactor processor that inspects `ActionSigner` context on every operation to build an immutable audit log in PostgreSQL. Exposes a GraphQL subgraph for querying entries by user, document, or time range. #### What it demonstrates - Signature/signer inspection — extracting `user.address`, `networkId`, `chainId`, and app credentials from `operation.action.context.signer` - Relational DB processor — batch-inserting structured rows via Kysely - Subgraph resolvers — GraphQL API over the audit log using graphql-yoga - Operation context fields — using `documentId`, `documentType`, `action.type`, and `timestampUtcMs` #### Setup ```sh pnpm install pnpm build ``` #### Usage ##### Processor ```ts const db = new Kysely({ dialect: new PostgresDialect({ pool }) }); await up(db); await processorManager.registerFactory( "audit-trail", createAuditTrailFactory({ db, filter: { branch: ["main"] }, }), ); ``` ##### GraphQL subgraph ```ts const server = startAuditServer(db, 4002); ``` Query examples: ```graphql # By user { auditByUser(address: "0xabc", limit: 10) { actionType documentId timestamp } } # By document { auditByDocument(documentId: "doc-1", limit: 10) { signerAddress actionType timestamp } } # By time range { auditByTimeRange(from: "2025-01-01T00:00:00Z", to: "2025-12-31T23:59:59Z") { signerAddress actionType documentId } } ``` #### Tests ```sh pnpm test ``` Tests use [PGlite](https://github.com/electric-sql/pglite) for an in-memory PostgreSQL instance. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/audit-trail) </details> <details id="recipe-batch-progress"> <summary><strong>Batch Progress</strong> — Demonstrates multi-document wizard creation with dependency ordering using Reactor's `executeBatch` and real-time progress tracking via the EventBus.</summary> ### Batch Progress Demonstrates multi-document wizard creation with dependency ordering using Reactor's `executeBatch` and real-time progress tracking via the EventBus. #### What it shows A "Create Project" flow that atomically creates 4 documents with dependencies: ``` budget ──┐ ├──► project ──► drive (add files) scope ──┘ ``` - budget and scope create in parallel (no dependencies) - project waits for both budget and scope - drive adds all three as files after project completes One call, one result, automatic dependency resolution. ##### Without Reactor ```ts const budget = await createDocument(budgetId, initBudget); const scope = await createDocument(scopeId, initScope); // hope nothing interleaves... const project = await createDocument(projectId, initProject); await addFilesToDrive(driveId, [budget, scope, project]); ``` Four sequential calls, manual error handling, no atomicity. ##### With Reactor ```ts await reactor.executeBatch({ jobs: [ { key: "budget", documentId: budgetId, actions: [initBudget], dependsOn: [] }, { key: "scope", documentId: scopeId, actions: [initScope], dependsOn: [] }, { key: "project", documentId: projectId, actions: [initProject], dependsOn: ["budget", "scope"] }, { key: "drive", documentId: driveId, actions: [addFiles], dependsOn: ["project"] }, ], }); ``` One call. Budget and scope run in parallel. Project waits for both. Drive waits for project. The reactor handles ordering, parallelism, and failure propagation. #### How it works 1. Embedded Reactor — spins up an in-memory Reactor (PGlite, no external DB) 2. Drive creation — creates a drive document to hold the project files 3. Batch submission — submits 4 dependent jobs via `IReactor.executeBatch` 4. EventBus tracking — subscribes to `JOB_PENDING`, `JOB_RUNNING`, `JOB_WRITE_READY`, `JOB_READ_READY`, and `JOB_FAILED` events for real-time status updates 5. Live progress — renders a multi-bar terminal display showing each job's status #### Job status lifecycle ``` PENDING → RUNNING → WRITE_READY → READ_READY ↘ FAILED ``` | Status | Meaning | |--------|---------| | `PENDING` | Job is queued but not yet started | | `RUNNING` | Job is currently being executed | | `WRITE_READY` | Operations written to the operation store | | `READ_READY` | Read models have finished indexing (terminal) | | `FAILED` | Job failed (terminal) | #### Usage ```sh pnpm install pnpm start ``` ##### Example output ``` Multi-Document Wizard — Create Project ═══════════════════════════════════════ Creating drive... Drive created: abc123 budget |████████████████████████████████████████| READ_READY scope |████████████████████████████████████████| READ_READY project |████████████████████████████████████████| READ_READY drive |████████████████████████████████████████| READ_READY ✓ Done in 0.42s — 4 jobs completed, 0 failed Budget: def456 Scope: ghi789 Project: jkl012 Drive: abc123 ``` #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/batch-progress) </details> <details id="recipe-cross-document-reactor"> <summary><strong>Cross-Document Reactor</strong> — Event-driven cross-document automation using `ReactorClient` subscriptions.</summary> ### Cross-Document Reactor Event-driven cross-document automation using `ReactorClient` subscriptions. #### What it demonstrates - `reactorClient.subscribe()` — broad subscription watching all document changes - Cross-document workflows — a change on one document triggers an action on a related document - `execute()` from within a subscription handler — the reactor as an event-driven automation engine #### How it works 1. Creates a drive with two documents: an invoice and a task, linked by naming convention (`Invoice-001` ↔ `Task-001-Invoice-001`) 2. Subscribes to all document changes with an empty search filter (`{}`) 3. When the invoice is renamed to include `[PAID]`, the subscription handler finds the related task and renames it to include `[CLOSED]` #### Running ```sh pnpm install pnpm --filter @powerhousedao/cross-document-reactor start ``` #### Expected output ``` Cross-Document Reactor ══════════════════════ Starting reactor... done (X.Xs) Creating drive... <drive-id> Creating invoice document... <invoice-id> Creating task document... <task-id> Documents named: "Invoice-001" ↔ "Task-001-Invoice-001" ─── Triggering workflow: marking Invoice-001 as [PAID] ─── [HH:MM:SS.mmm] updated → Invoice-001 [PAID] [HH:MM:SS.mmm] ⚡ Rule triggered: "Invoice-001 [PAID]" is paid [HH:MM:SS.mmm] Looking for task: "Task-001-Invoice-001"... [HH:MM:SS.mmm] Found task <task-id>, closing it... [HH:MM:SS.mmm] updated → Task-001-Invoice-001 [CLOSED] ─── Final document state ─── Invoice: "Invoice-001 [PAID]" Task: "Task-001-Invoice-001 [CLOSED]" ✓ Cross-document reaction succeeded ``` #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/cross-document-reactor) </details> <details id="recipe-custom-read-model"> <summary><strong>Custom Read Model</strong> — A custom `IReadModel` implementation registered via `ReactorBuilder.withReadModel()` that maintains a document-count-per-type materialized view.</summary> ### Custom Read Model A custom `IReadModel` implementation registered via `ReactorBuilder.withReadModel()` that maintains a document-count-per-type materialized view. Demonstrates the read model lifecycle, the pre-ready guarantee, and how read models differ from processors. #### How it works `DocumentCountReadModel` implements `IReadModel` directly — it receives every operation written to the reactor's operation store via `indexOperations()` and increments an in-memory counter keyed by `context.documentType`. ``` Operation written → JOB_WRITE_READY → ReadModelCoordinator ├── preReady: DocumentCountReadModel.indexOperations() ← our read model ├── preReady: DocumentView, DocumentIndexer (built-in) ├── emit JOB_READ_READY ← counts are already up to date here └── postReady: processors, subscriptions ``` ##### Read model vs processor | | Read Model (IReadModel) | Processor (IProcessor) | |--|--|--| | Phase | Pre-ready — completes before `JOB_READ_READY` | Post-ready — runs after `JOB_READ_READY` | | Purpose | Derived views that must be queryable immediately | Side-effects (webhooks, notifications, sync) | | Registration | `ReactorBuilder.withReadModel()` | `ProcessorManager.registerFactory()` | | Receives | `OperationWithContext[]` via `indexOperations()` | `OperationWithContext[]` via `onOperations()` | ##### Why implement IReadModel directly? `BaseReadModel` provides catch-up/rewind via the `ViewState` table and requires `IOperationIndex`, `IWriteCache`, and `IConsistencyTracker` — useful for persistent read models but unnecessary for a simple in-memory counter. Implementing `IReadModel` directly keeps the example minimal and shows the core contract. ##### buildModule() internals `ReactorBuilder.buildModule()` returns a `ReactorModule` with direct access to the event bus, database, operation store, and other internals — useful for advanced integration, testing, or custom wiring. #### Architecture | Module | Purpose | |--------|---------| | `src/document-count-read-model.ts` | `DocumentCountReadModel` — the `IReadModel` implementation | | `src/index.ts` | Demo: builds a reactor, creates a document, shows the read model counts inside `JOB_READ_READY` | #### Usage ##### Run the demo ```sh pnpm start ``` ##### Use in your own code ```ts const countReadModel = new DocumentCountReadModel(); const reactorModule = await new ReactorBuilder() .withDocumentModels([/ your models /]) .withReadModel(countReadModel) .buildModule(); // After any job completes, counts are already up to date: reactorModule.eventBus.subscribe( ReactorEventTypes.JOB_READ_READY, () => { console.log(countReadModel.getCounts()); }, ); ``` ##### Query the materialized view ```ts // All counts const counts: ReadonlyMap<string, number> = countReadModel.getCounts(); // Single type const budgetOps = countReadModel.getCount("powerhouse/budget"); ``` #### Tests ```sh pnpm test ``` #### Exports ```ts export { DocumentCountReadModel } from "./src/document-count-read-model.js"; ``` [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/custom-read-model) </details> <details id="recipe-db-migrate"> <summary><strong>DB Migrate</strong> — PostgreSQL database export, import, and migration scripts using Docker.</summary> ### DB Migrate PostgreSQL database export, import, and migration scripts using Docker. No local `pg_dump` or `pg_restore` installation required. #### Prerequisites - [Docker](https://docs.docker.com/get-docker/) The scripts use the `postgres:17` image, which is pulled automatically on first run. #### Scripts ##### export.sh Dump a PostgreSQL database to a file or stdout. ```sh # Export to a file (custom format, default) ./export.sh -o backup.dump postgres://user:pass@localhost:5432/mydb # Export as plain SQL ./export.sh -F plain -o backup.sql postgres://user:pass@localhost:5432/mydb # Export to stdout (pipe to another tool) ./export.sh postgres://user:pass@localhost:5432/mydb > backup.dump ``` Options: | Flag | Description | |------|-------------| | `--format, -F` | Dump format: `custom` (default), `plain`, `tar`, `directory` | | `--output, -o` | Output file path (default: stdout) | ##### import.sh Restore a dump file into a PostgreSQL database. ```sh # Import a custom-format dump ./import.sh postgres://user:pass@localhost:5432/mydb backup.dump # Import a plain SQL dump ./import.sh -F plain postgres://user:pass@localhost:5432/mydb backup.sql # Import from stdin cat backup.dump | ./import.sh postgres://user:pass@localhost:5432/mydb - ``` Options: | Flag | Description | |------|-------------| | `--format, -F` | Dump format: `custom` (default), `plain`, `tar` | For custom/tar formats, `pg_restore --clean --if-exists` is used. For plain format, `psql` is used. ##### migrate.sh Export from one database and import into another in a single step. ```sh # Migrate between two databases ./migrate.sh postgres://user:pass@source:5432/mydb postgres://user:pass@target:5432/mydb # Migrate using plain SQL format ./migrate.sh -F plain postgres://user:pass@source:5432/mydb postgres://user:pass@target:5432/mydb ``` Options: | Flag | Description | |------|-------------| | `--format, -F` | Dump format: `custom` (default), `plain`, `tar` | #### Running via pnpm ```sh pnpm --filter @powerhousedao/db-migrate export -- -o backup.dump postgres://user:pass@localhost:5432/mydb pnpm --filter @powerhousedao/db-migrate import -- postgres://user:pass@localhost:5432/mydb backup.dump pnpm --filter @powerhousedao/db-migrate migrate -- postgres://user:pass@source:5432/mydb postgres://user:pass@target:5432/mydb ``` #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/db-migrate) </details> <details id="recipe-discord-webhook-processor"> <summary><strong>Discord Webhook Processor</strong> — A Reactor `IProcessor` that posts document operations to a Discord channel via webhook.</summary> ### Discord Webhook Processor A Reactor `IProcessor` that posts document operations to a Discord channel via webhook. Each operation is converted into a Discord embed containing: - Action type, document ID, document type, scope, branch, hash - Truncated action input (max 1024 chars) - Timestamp Batches exceeding Discord's 10-embed limit are automatically chunked into multiple requests. Every request includes an HMAC-SHA256 signature in the `X-Reactor-Signature` header. #### Usage Register the processor with a Reactor `ProcessorManager`: ```ts await processorManager.registerFactory( "discord-webhook", createDiscordWebhookFactory({ webhookUrl: "https://discord.com/api/webhooks/{id}/{token}", secret: process.env.WEBHOOK_SECRET!, filter: { documentType: ["powerhouse/billing-statement"], scope: ["global"], branch: ["main"], }, }), ); ``` #### Tests ```sh pnpm test ``` [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/discord-webhook-processor) </details> <details id="recipe-document-snapshot-exporter"> <summary><strong>Document Snapshot Exporter</strong> — CLI tool that exports document state and operation history to JSON files, demonstrating reliable read-after-write consistency using the Reactor API.</summary> ### Document Snapshot Exporter CLI tool that exports document state and operation history to JSON files, demonstrating reliable read-after-write consistency using the Reactor API. #### What it demonstrates - IReactor API — low-level interface where mutations return `JobInfo` with consistency tokens - Consistency tokens — passed to reads (`reactor.get()`, `reactor.getOperations()`) to guarantee the read reflects prior writes - OperationFilter — filtering operations by action type, timestamp range, or revision - IReactor vs IReactorClient — run with `--mode reactor` or `--mode client` to compare the two APIs side by side ##### IReactor vs IReactorClient | | IReactor | IReactorClient | |---|---|---| | Mutations return | `JobInfo` (must await manually) | The document (job awaited internally) | | Consistency | You pass `ConsistencyToken` to reads | Managed automatically | | Signing | Manual (pass `ISigner` to each call) | Automatic via configured signer | | `getOperations()` returns | `Record<string, PagedResults>` (per-scope) | `PagedResults` (flat) | | Use when | You need fine-grained control over job lifecycle | You want a simpler, higher-level API | #### Usage ```sh pnpm install pnpm start ``` ##### Options ``` --mode <reactor|client> API mode (default: reactor) --out <path> Output directory (default: ./output) ``` ##### Examples ```sh # Export using low-level IReactor with explicit consistency tokens pnpm start # Export using high-level IReactorClient pnpm start -- --mode client # Custom output directory pnpm start -- --out ./snapshots # Compare both modes pnpm start -- --out ./out-reactor pnpm start -- --mode client --out ./out-client ``` #### Output Each document is written as a JSON file named `<document-id>.json`: ```json { "header": { "id": "...", "documentType": "...", ... }, "state": { ... }, "operations": [ ... ], "exportedAt": "2025-01-01T00:00:00.000Z", "mode": "reactor" } ``` [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/document-snapshot-exporter) </details> <details id="recipe-document-versioning"> <summary><strong>Document Versioning</strong> — Evolve a document model's schema from v1 to v2 with an `UpgradeManifest` and a pure `upgradeReducer`, so documents created under the old schema keep loading and replaying correctly.</summary> ### Document Versioning Evolve a document model's schema from v1 to v2 with an `UpgradeManifest` and a pure `upgradeReducer`, so documents created under the old schema keep loading and replaying correctly. #### What it demonstrates - Defining two schema versions in a single codegen spec: [`document-models/todo/todo.json`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/todo.json) carries one `specifications` entry per version, and `ph-cli generate` emits the whole `v1/`, `v2/`, and `upgrades/` tree — including a wired-up `UpgradeManifest` (`{ documentType, latestVersion, supportedVersions, upgrades }`) and a stub upgrade transition for you to fill in. - `UpgradeTransition`: `{ toVersion, upgradeReducer, description }` — its `upgradeReducer` is a pure function that transforms a whole document from version N−1 to N. Codegen scaffolds the stub at [`document-models/todo/upgrades/v2.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/upgrades/v2.ts); the migration body is the one piece you hand-write. - The upgrade-application logic that `@powerhousedao/reactor` runs in production (`computeUpgradePath` + apply + version stamp), distilled into [`src/upgrade.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/src/upgrade.ts) — `document-model` only defines the manifest types. - Replaying an operation log recorded under v1 into a v2 state shape ([`src/replay.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/src/replay.ts)). #### State shape evolution ```ts // v1 type TodoItemV1 = { id: string; title: string; checked: boolean }; // v2 — a field rename plus a type change, the realistic migration case type TodoItemV2 = { id: string; title: string; status: "TODO" | "IN_PROGRESS" | "DONE"; priority: number; }; ``` Each version's shape is declared as GraphQL in the matching `specifications` entry of [`todo.json`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/todo.json); codegen turns it into the types above. The transition in [`document-models/todo/upgrades/v2.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/upgrades/v2.ts) maps `checked: true → status: "DONE"`, `checked: false → status: "TODO"`, and adds `priority: 0`. #### Critical pitfall: patch `state` and `initialState` together The upgrade runs once, when `UPGRADE_DOCUMENT` is dispatched. Replay never re-runs it: loading a document (`baseLoadFromInput` → `replayDocument`) starts from the stored `initialState` and folds the domain operations through the latest reducer — the `document`-scope log where the upgrade is recorded is not replayed. So if the upgrade reducer migrates `state` but forgets `initialState`: - the live document looks perfectly healthy, but - anything seeded into `initialState` (never created by an operation) is still v1-shaped there, so a rebuild can no longer reproduce the stored state — and the replayed final state fails the recorded hash check. The document errors on load with a `HashMismatchError` whose message embeds `Hash mismatch on document …, scope global` (match it with `/Hash mismatch/`, as the tests do). The transition in this recipe patches both in one pass, and [`tests/versioning.test.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/tests/versioning.test.ts) includes a deliberately broken state-only transition that makes the failure visible. #### The latest reducer owns the historical log Replay sends the entire* operation history through the latest reducer — including operations whose type no longer exists in the new schema. That is why `CHECK_ITEM` is retained as an operation in the v2 spec (so codegen keeps generating its action and reducer slot), and [`v2/src/reducers/todo.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/v2/src/reducers/todo.ts) maps the old `checked` boolean onto the new `status`. When a migration renames or retypes fields, retiring an operation from the editor does not retire it from history. #### Upgrade reducers must be pure Upgrade reducers run on every peer that loads the document. No `Date.now()`, no randomness, no I/O — and they must return a new document (spread-style); there is no immer draft, so in-place mutation is lost. #### `supportedVersions` is ordered, and every hop must be covered `supportedVersions` lists every version the model has ever shipped, in ascending order. Upgrading a v1 document in a package that is already on v3 composes the intermediate transitions in sequence (v1→v2, then v2→v3) — there is no shortcut path, and a missing `upgrades` entry for any intermediate hop throws at upgrade time. The `computeUpgradePath` suite in [`tests/versioning.test.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/tests/versioning.test.ts) exercises both. #### Production wiring Codegen already emits the structure a real package registers: each version's [`module.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/v2/module.ts) carries an explicit `version` field, [`document-models/document-models.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/document-models.ts) exports `documentModels = [TodoV1, TodoV2]`, and [`document-models/upgrade-manifests.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/upgrade-manifests.ts) exports `upgradeManifests = [todoUpgradeManifest]`. The only thing this recipe does differently from production is who applies the upgrade: - a reactor registers both (`new ReactorBuilder().withDocumentModels(documentModels).withUpgradeManifests(upgradeManifests)`) and, on `UPGRADE_DOCUMENT`, computes the upgrade path from the manifest and applies it; - here, [`src/upgrade.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/src/upgrade.ts) runs that same compose-transitions-then-stamp-version sequence in-process, so the mechanics are visible without standing up a reactor. A peer that has only the v1 package registered cannot execute the upgrade: the document stays at v1 there, and v2 operations fail until the updated package ships — deploy the new model version everywhere before dispatching the first v2 operation. #### Running ```sh pnpm install pnpm start ``` The demo creates a v1 document with a seeded item, applies v1 operations, upgrades to v2, keeps dispatching v2 operations, then replays the recorded history and verifies it converges on the stored state. #### Regenerating the model The `document-models/` tree is generated from [`document-models/todo/todo.json`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/document-models/todo/todo.json) and committed to the repo. To evolve a schema, edit the spec (add a `specifications` entry for the new version) and re-run codegen: ```sh pnpm generate ``` `gen/` files are overwritten on every run; the hand-written reducers (`/src/reducers/todo.ts`) and the upgrade transitions (`upgrades/v.ts`) are scaffolded once and then preserved, so re-running is safe. #### Creating a document at its model version A v1 document must declare version 1: the upgrade manifest covers 1→2 and has no transition into v1, so a document left at version 0 would give `computeUpgradePath` nowhere to start (`Version 0 ... is not in supportedVersions [1, 2]`). The generated factory stamps the version for you — pass it explicitly and seed any initial items through `global`: ```ts createTodoDocument({ document: { version: 1 }, global: { items } }); ``` `createTodoDocument` routes through `baseCreateDocument`, so it also seeds the document-scope log (`CREATE_DOCUMENT` plus the genesis `UPGRADE_DOCUMENT` 0→1) — the same thing a reactor does from the registered module in production. The "starts at model version 1" check in [`tests/v1-reducer.test.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/tests/v1-reducer.test.ts) and the upgrade/replay suites in [`tests/versioning.test.ts`](https://github.com/powerhouse-inc/recipes/blob/main/document-versioning/tests/versioning.test.ts) guard the behavior. #### Tests ```sh pnpm test ``` Covered: v1/v2 reducer behavior (including the legacy `CHECK_ITEM` case), migration of `state` and `initialState`, the no-op upgrade of an already-latest document, replay convergence of the mixed v1/v2 history, the broken state-only transition failing replay with a hash mismatch, and multi-hop upgrade paths (v1→v2→v3) composing in order. #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/document-versioning) </details> <details id="recipe-drive-override"> <summary><strong>Drive Override</strong> — A custom container document that tracks its children via the reactor's `ADD_RELATIONSHIP` system action instead of the `document-drive` model's `ADD_FILE`.</summary> ### Drive Override A custom container document that tracks its children via the reactor's `ADD_RELATIONSHIP` system action instead of the `document-drive` model's `ADD_FILE`. The container's own state stays at O(1) regardless of how many children it owns; children live in the reactor's `DocumentRelationship` table and are enumerated through paged, DB-native queries. #### What it demonstrates - Build your own drive — define a minimal `DocumentModelModule` with `name` + `description` state and a single `SET_METADATA` operation. No `nodes[]` array, no embedded child catalogue. - `ADD_RELATIONSHIP` instead of `ADD_FILE` — link 10,000 child documents to the container in batches of 100 via `reactor.execute(containerId, "main", [addRelationshipAction(...)])`. The container's state never grows. - Paged enumeration — read children back via `documentIndexer.getOutgoing(containerId, ["contains"], { cursor, limit })`, advancing `cursor` until `nextCursor` is empty. Backed by indexed Kysely queries on the `DocumentRelationship` table. - Bidirectional graph — `documentIndexer.getIncoming(childId)` returns the container as a parent. The relationship table is indexed on both `sourceId` and `targetId`. #### Why this scales better than `ADD_FILE` `document-drive` keeps its child catalogue inside the drive document's `state.global.nodes[]`. Each `ADD_FILE` mutates that array — every replay walks every previously-added child, every read materialises the full state, and operation-log size grows with child count. Container performance decays as the drive fills. `ADD_RELATIONSHIP` is a system-scope action handled directly by the reactor's job executor. The source document's state and operation log are unaffected; the indexer writes one row to `DocumentRelationship` and exposes the graph via `IDocumentIndexer`. Cost is flat in the number of children. #### State shape ```graphql type CustomContainerState { name: String! description: String } ``` That is the entire schema. No children, no nodes, no files. #### Operations | Operation | Effect | |---|---| | `SET_METADATA({ name, description? })` | Sets the container's display metadata. | Children are added by dispatching `addRelationshipAction(containerId, childId, "contains")` directly to `reactor.execute()` — not through the container's own reducer. The reducer never sees relationships. #### GraphQL The reactor subgraph exposes the same data over GraphQL: - `documentOutgoingRelationships(documentId, relationshipTypes, paging)` — children of a container. - `documentIncomingRelationships(documentId, relationshipTypes, paging)` — parents of a child. Both fields are paged. Use them when querying from an external client. #### Running ```sh pnpm install pnpm --filter @powerhousedao/example-drive-override start ``` The demo will: 1. Spin up an in-memory reactor (PGlite-backed). 2. Create the container and apply `SET_METADATA`. 3. Create 10,000 plain `document-model` child documents in 100 batches of 100, wiring each to the container via `ADD_RELATIONSHIP`. 4. Print the container's `state.global` keys — should remain `["description", "name"]`. 5. Page through all 10,000 children via `documentIndexer.getOutgoing` at 500 per page. 6. Spot-check one child via `documentIndexer.getIncoming` and confirm the container is its parent. Expect total runtime in the tens of seconds to a few minutes depending on hardware, dominated by the per-job round-trip through the executor. The point is not throughput — it's that the container's state stays flat. #### Key files - [`document-models/custom-container/`](https://github.com/powerhouse-inc/recipes/blob/main/drive-override/document-models/custom-container) — the `powerhouse/custom-container` document model, generated from `custom-container.json` via `pnpm generate` (pinned `ph-cli`, `catalog:`). The `SET_METADATA` reducer lives in `v1/src/reducers/metadata.ts`; everything under `v1/gen/` is codegen output. - [`src/index.ts`](https://github.com/powerhouse-inc/recipes/blob/main/drive-override/src/index.ts) — the demo. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/drive-override) </details> <details id="recipe-external-feed-ingest"> <summary><strong>External Feed Ingest</strong> — A polling worker that pulls an off-platform feed into event-sourced documents idempotently.</summary> ### External Feed Ingest A polling worker that pulls an off-platform feed into event-sourced documents idempotently. It is the external-input counterpart to [`cross-document-reactor`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../cross-document-reactor) (which automates on internal events): here the trigger comes from outside the reactor. This generalizes what `defi-united-package` does for real against Ethereum — a processor polls Alchemy for asset transfers and dispatches them into receipt documents, handling idempotency, confirmation depth, and chain reorgs as first-class concerns. We replace Ethereum with a deterministic in-process mock feed so the recipe is keyless and offline-runnable. #### The one idea worth taking away > The document is the checkpoint store. The dedup set and the high-watermark > live in document state, and the worker rebuilds them from state at startup. An > in-memory-only checkpoint is the bug this recipe exists to prevent: crash the > worker mid-stream and an in-memory checkpoint re-ingests everything since the > last flush. Seed from state instead and a restart is a no-op. ``` external feed ──fetchSince(watermark)──▶ FeedPoller (monotonic cursor, │ 1. seedFromState(): rebuild dedup set redeliveries, │ + watermark from the document corrections) │ 2. skip ids already in state │ 3. map event → recordEntry / markSuperseded ▼ reactor.execute → Ledger document { source, watermark, entries[] } ``` #### What it demonstrates - A poll loop dispatching actions into a document through the reactor (`FeedPoller.pollOnce` / `start`). - Idempotent ingestion. The dedup key is `(source, externalId)`, and the set is seeded from existing document state at startup, so restarts never double-ingest. The reducer enforces the same uniqueness as defense-in-depth. - High-watermark per source, stored in the document itself — no side database. The watermark tracks the feed's monotonic delivery cursor, not the events' logical timestamps. - Corrections as explicit operations. An upstream rewrite becomes a `markSuperseded` op that flips the old entry's status and appends the corrected value as a new entry — the original payload is never mutated. #### Why `externalId` is the dedup key, not the watermark The watermark is only a fetch optimization ("don't re-read the whole feed"). It is not the dedup mechanism, because real feeds redeliver: the same `externalId` can reappear at a later cursor, sailing straight past a watermark filter. The authoritative check is "have I already recorded this `externalId`?", answered from document state. The watermark and the id-set are belt and suspenders — and on restart the id-set is what saves you. The scripted feed (`feed.ts`) exercises every case in six events: | cursor | externalId | what it is | |--------|------------|-----------| | 1 | `po-001` | normal | | 2 | `po-002` | normal | | 3 | `po-003` | normal, but its `ts` is earlier than `po-002`'s (out-of-order logical delivery) | | 4 | `po-002` | duplicate redelivery at a later cursor | | 5 | `po-004` | normal | | 6 | `po-001-c` | correction of `po-001` (restated amount) | #### Run it ```sh pnpm --filter @powerhousedao/example-external-feed-ingest start ``` The demo starts a poller, lets it ingest the first three events, kills it (discarding its in-memory cache), then starts a fresh poller that re-seeds from the document and drains the rest. It prints the final ledger and operation history, and asserts: - no duplicate entries across the restart (`po-002` appears exactly once), - the correction is a `MARK_SUPERSEDED` op + a new entry, and - `po-001`'s original payload was never mutated. #### The document model (codegen) The `FeedLedger` document model is generated, not hand-written. The spec lives at `document-models/feed-ledger/feed-ledger.json` (GraphQL state schema + operations + initial reducer bodies); everything under `document-models/feed-ledger/v1/gen/` — types, zod validators, action creators, the reducer wiring, the typed error classes (`DuplicateEntry`, `UnknownEntry`) — is produced from it. Regenerate after editing the spec: ```sh pnpm --filter @powerhousedao/example-external-feed-ingest generate ``` The state schema: ```graphql type FeedLedgerState { source: String! watermark: Int! entries: [LedgerEntry!]! } type LedgerEntry { externalId: String! sequence: Int! payload: String! recordedAt: String! # the FEED timestamp, never local wall-clock status: LedgerEntryStatus! # RECORDED | SUPERSEDED supersededBy: String } enum LedgerEntryStatus { RECORDED SUPERSEDED } ``` The reducer logic is hand-maintained at `document-models/feed-ledger/v1/src/reducers/ingest.ts` (codegen scaffolds it from the spec's `reducer` fields and then leaves it alone): - `recordEntry(externalId, sequence, payload, ts)` — append a `RECORDED` entry and advance the watermark to `max(watermark, sequence)` (monotonic, so an out-of-order delivery can't regress it). Throws `DuplicateEntry` if the `externalId` is already present. - `markSuperseded(supersededId, externalId, sequence, payload, ts)` — flip an existing entry to `SUPERSEDED`, set its `supersededBy`, and append the correction as a new `RECORDED` entry. Throws `UnknownEntry` if the target is missing or already superseded. Watermark advancement is folded into both operations; there is no separate `setWatermark` op. Codegen is pinned to the same `6.2.0-dev.9` line as the runtime (the `ph-cli` devDependency uses `catalog:`), so the `gen/` tree compiles as-is — nothing under it is hand-edited. #### Where should the poller live? This recipe runs the poller as a plain long-running script using the reactor client (the simplest option, matching `cross-document-reactor`'s style). The `start(intervalMs)` loop backs off exponentially on feed errors and never tight-loops a struggling upstream. The alternative is to run the poll inside an `IProcessor` — that's `defi-united-package`'s choice. It's perfectly valid, but then the reactor owns the worker's lifecycle (start/stop/retry), which is more machinery than a recipe needs to make the point. The crash-safety argument is identical either way: it comes from seeding state from the document, not from where the loop lives. One document per source keeps watermark advancement contention-free — every `recordEntry` touches a single document, so there's no cross-source coordination. #### Tests ```sh pnpm --filter @powerhousedao/example-external-feed-ingest test ``` - `document-models/feed-ledger/v1/tests/ingest.test.ts` — reducer-level: record, monotonic watermark, duplicate rejection, correction-not-mutation, unknown-supersede rejection. - `src/poller.test.ts` — end-to-end over a reactor: full scripted ingest, restart-without-duplicates, redelivery-ignored, correction → `markSuperseded`, and backoff-on-feed-error. #### Related recipes - [`cross-document-reactor`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../cross-document-reactor) / [`saga`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../saga) — internal-event automation; this is the external-input counterpart. - [`inbound-webhook-bridge`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../inbound-webhook-bridge) — the push twin: the feed calls you. Same idempotency idea (dedup ids in document state), different trigger. - [`sync-health-monitor`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../sync-health-monitor) — similar long-running observer wiring. - [`batch-progress`](https://github.com/powerhouse-inc/recipes/blob/main/external-feed-ingest/../batch-progress) — bulk dispatch ergonomics if the feed delivers in batches. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/external-feed-ingest) </details> <details id="recipe-full-text-search"> <summary><strong>Full-Text Search Processor</strong> — A Reactor `IProcessor` that indexes document state into a PostgreSQL full-text search table, enabling ranked keyword search across all documents managed by a Reactor instance.</summary> ### Full-Text Search Processor A Reactor `IProcessor` that indexes document state into a PostgreSQL full-text search table, enabling ranked keyword search across all documents managed by a Reactor instance. #### How it works When operations arrive, the processor: 1. Collects the last operation per document (earlier states are superseded). 2. Flattens the resulting document state into a single searchable string via `flattenToSearchableText`. 3. Upserts a row in `search_index` with the content and a PostgreSQL `tsvector`. 4. Handles `DELETE_DOCUMENT` actions by removing the corresponding row. #### Architecture | Module | Purpose | |--------|---------| | `processor.ts` | `SearchProcessor` — the `IProcessor` implementation | | `schema.ts` | Kysely type definitions for the `search_index` table | | `migrations.ts` | `up` / `down` functions to create/drop the table and GIN index | | `query.ts` | `createSearchQuery` — returns a `search(term, limit?)` helper using `ts_rank` | | `utils.ts` | `flattenToSearchableText` — recursively extracts all string values from a JSON state | #### Prerequisites - PostgreSQL with full-text search support (`tsvector`, `plainto_tsquery`, `ts_rank`) - [Kysely](https://kysely.dev/) database instance #### Usage ##### Run migrations ```ts await up(db); ``` ##### Register the processor ```ts const processor = new SearchProcessor(db); ``` ##### Query the index ```ts const search = createSearchQuery(db); const results = await search.search("budget allocation", 10); // returns: [{ document_id, document_type, title, rank }] ``` #### Exports ```ts export { SearchProcessor } from "./processor.js"; export { createSearchQuery } from "./query.js"; export type { SearchResult } from "./query.js"; export type { SearchDB, SearchIndex } from "./schema.js"; export { flattenToSearchableText } from "./utils.js"; export { up, down } from "./migrations.js"; ``` [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/full-text-search) </details> <details id="recipe-inbound-webhook-bridge"> <summary><strong>Inbound Webhook Bridge</strong> — Receive external webhooks (Stripe-style), verify the signature server-side against the raw request bytes, and map verified events onto document actions.</summary> ### Inbound Webhook Bridge Receive external webhooks (Stripe-style), verify the signature server-side against the raw request bytes, and map verified events onto document actions. This is the inbound twin of [`discord-webhook-processor`](https://github.com/powerhouse-inc/recipes/blob/main/inbound-webhook-bridge/../discord-webhook-processor) (documents → external service); here the flow runs the other way: external service → documents. #### The headline rule: verify the raw bytes > `JSON.parse(body)` → `JSON.stringify(parsed)` breaks HMAC. The signature > is computed over the exact bytes the provider sent. Re-serializing changes key > order, whitespace, and number formatting, so the MAC no longer matches. Always verify the raw body string, then parse it. This recipe uses a small `node:http` listener precisely so it controls the bytes — a GraphQL/JSON mutation resolver parses the body before your code runs, which is why the brief recommends a dedicated listener when raw-body access is awkward. #### How it works ``` provider ──POST raw body + x-webhook-signature──▶ createWebhookServer (node:http) │ 1. read raw bytes (no parse yet) │ 2. verifyWebhook() — HMAC over `${t}.${rawBody}`, │ constant-time compare, replay-window check │ 3. JSON.parse the verified bytes ▼ WebhookBridge.handleEvent │ 4. resolve orderId → documentId │ 5. dedup vs persisted processedEventIds │ 6. map event type → typed action ▼ reactor.execute → Payment document ``` ##### Signature scheme (modelled on Stripe) The `x-webhook-signature` header is `t=<unixSeconds>,v1=<hmacHex>`, and the signed payload is `` `${t}.${rawBody}` ``. Folding the timestamp into the MAC is what makes the replay-window check trustworthy — it can't be altered independently of the signature. ```ts const header = signWebhook(secret, rawBody, Math.floor(Date.now() / 1000)); const verdict = verifyWebhook({ secret, rawBody, signatureHeader: header, nowSeconds }); // { ok: true, timestampSeconds } | { ok: false, reason } ``` Verification rejects: missing/malformed header, signature mismatch (wrong secret or tampered/re-serialized body), and timestamps outside the tolerance window (default 5 minutes). Comparison uses `crypto.timingSafeEqual`. ##### Idempotency that survives restarts Providers redeliver. Every event that mutates the document records its provider `event.id` in the document's `processedEventIds` state. Because the dedup set lives in document state — not a processor's memory — it is rebuilt for free after a restart. The bridge short-circuits a known event id (keeping history clean), and the reducer refuses a duplicate as a second line of defense for racing redeliveries. #### The payment document model A deliberately small state machine, generated from `document-models/payment/payment.json` via `pnpm generate` (pinned `ph-cli`, `catalog:`): ``` PENDING ──recordPayment──▶ PAID ──recordRefund──▶ REFUNDED └──────markFailed──────▶ FAILED ``` | Event type | Action | Transition | |---------------------|-----------------|---------------------| | `payment.succeeded` | `recordPayment` | PENDING → PAID | | `payment.failed` | `markFailed` | PENDING → FAILED | | `refund.created` | `recordRefund` | PAID → REFUNDED | State: `{ orderId, amountCents, currency, status, failureReason, processedEventIds }`. The reducer logic (the state-machine guards + event-id dedup) is hand-maintained at `document-models/payment/v1/src/reducers/payment.ts`; everything under `document-models/payment/v1/gen/` is codegen output and isn't edited. #### Architecture | Module | Purpose | |--------|---------| | `src/signature.ts` | `signWebhook` / `verifyWebhook` — pure HMAC helpers (raw-bytes, constant-time, replay window) | | `document-models/payment/` | The codegen'd `powerhouse/payment` document model; reducer (state machine + event-id dedup) in `v1/src/reducers/payment.ts` | | `src/webhook-bridge.ts` | `WebhookBridge` (event → action, dedup, dispatch) and `createWebhookServer` (raw-body HTTP edge) | | `src/demo.ts` | Boots a reactor + endpoint and plays the provider: valid / tampered / duplicate / stale events | #### Secrets The signing secret is read only on the server and must never be bundled for the browser. Declare it via the package manifest `config` block (see `powerhouse.manifest.json`), the way production packages document required secrets: | Name | Type | Required | Description | |------|------|----------|-------------| | `WEBHOOK_SIGNING_SECRET` | `secret` | yes | Shared HMAC-SHA256 secret for verifying the `x-webhook-signature` header. | Load it from the environment server-side; keep it out of any code path that could be bundled for the client. #### Running ```sh pnpm start # runs the demo pnpm test # signature, reducer, and HTTP integration tests ``` The demo prints the document's final state and history, showing exactly one state-changing operation despite the tampered, duplicate, and stale deliveries. #### Related recipes - [`discord-webhook-processor`](https://github.com/powerhouse-inc/recipes/blob/main/inbound-webhook-bridge/../discord-webhook-processor) — the outbound twin (documents → external service). - [`rate-limiter`](https://github.com/powerhouse-inc/recipes/blob/main/inbound-webhook-bridge/../rate-limiter) — precedent for gating the write path. - [`saga`](https://github.com/powerhouse-inc/recipes/blob/main/inbound-webhook-bridge/../saga) — what to read next if one webhook should fan out across multiple documents. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/inbound-webhook-bridge) </details> <details id="recipe-rate-limiter"> <summary><strong>Rate Limiter</strong> — A Reactor `IProcessor` paired with an `AuthService` gate to throttle users by signer address, preventing any single user from overwhelming the system with excessive operations.</summary> ### Rate Limiter A Reactor `IProcessor` paired with an `AuthService` gate to throttle users by signer address, preventing any single user from overwhelming the system with excessive operations. #### How it works The recipe has two components that form a feedback loop: 1. `RateLimiterProcessor` sits inside the Reactor and observes every operation. It extracts the signer address from `operation.action.context.signer.user.address`, counts operations per user within a sliding time window, and calls `authService.cooldown()` when a user exceeds the threshold. The processor never throws — it only signals. 2. `AuthService` sits in front of the Reactor (e.g. in a GraphQL resolver or HTTP middleware). Before forwarding a mutation, the caller checks `authService.isAllowed(address)`. If the user is on cooldown, the response includes `retryAfterMs` so the client knows when to retry. ``` Client → [AuthService gate] → Reactor → RateLimiterProcessor → authService.cooldown() ↑ | └────────────────────────────────────────────────────────┘ ``` Operations without a signer are silently skipped. Counters are in-memory and reset on processor disconnect or restart. #### Architecture | Module | Purpose | |--------|---------| | `src/auth-service.ts` | `AuthService` — in-memory cooldown gate with `cooldown()`, `isAllowed()`, and `getCooldownRemaining()` | | `src/rate-limiter-processor.ts` | `RateLimiterProcessor` — the `IProcessor` implementation; also exports `createRateLimiterFactory` | #### Configuration | Option | Type | Description | |--------|------|-------------| | `maxOperations` | `number` | Maximum operations allowed per user within the time window | | `windowMs` | `number` | Length of the sliding time window in milliseconds | | `cooldownMs` | `number` | How long a user is blocked after exceeding the limit | | `filter` | `ProcessorFilter` | Which operations the processor subscribes to (document type, scope, branch, etc.) | #### Usage ##### Register the processor ```ts // Shared instance — pass to both the GQL layer and the processor const authService = new AuthService(); await processorManager.registerFactory( "rate-limiter", createRateLimiterFactory({ authService, maxOperations: 100, windowMs: 60_000, // 1-minute window cooldownMs: 300_000, // 5-minute cooldown filter: { branch: ["main"] }, }), ); ``` ##### Gate requests in your GraphQL / HTTP layer ```ts const check = authService.isAllowed(userAddress); if (!check.allowed) { res.set("Retry-After", String(Math.ceil(check.retryAfterMs! / 1000))); throw new Error(`Rate limited. Retry after ${check.retryAfterMs}ms`); } ``` ##### Check cooldown status ```ts const remainingMs = authService.getCooldownRemaining(userAddress); ``` #### Exports ```ts export { AuthService } from "./src/auth-service.js"; export type { AuthCheckResult } from "./src/auth-service.js"; export { RateLimiterProcessor, createRateLimiterFactory } from "./src/rate-limiter-processor.js"; export type { RateLimiterConfig } from "./src/rate-limiter-processor.js"; ``` #### Tests ```sh pnpm test ``` [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/rate-limiter) </details> <details id="recipe-relational-db-subgraph"> <summary><strong>Relational DB Subgraph</strong> — A complete relational DB processor recipe demonstrating the academy flagship tutorial pattern:</summary> ### Relational DB Subgraph A complete relational DB processor recipe demonstrating the academy flagship tutorial pattern: - RelationalDbProcessor — extends the base class with `initAndUpgrade()`, namespaced DB, and type-safe `query` builder - Kysely migrations — up/down migrations creating `documents` and `document_tags` tables - Typed schema — full Kysely DB interface with `CatalogDB`, `DocumentRow`, and `DocumentTagRow` - Type-safe queries — Kysely query layer with joins, filtering by type/tag, and pagination - GraphQL subgraph — graphql-yoga server exposing the catalog data, ready for supergraph composition #### What it does The `CatalogProcessor` watches all documents flowing through the Reactor (document-type-agnostic) and maintains a denormalized relational view: - `documents` table — stores document metadata (ID, type, name, content summary, revision) - `document_tags` table — stores tags extracted from document state The GraphQL subgraph exposes this data via queries like `documents`, `document(id)`, `documentsByType`, and `documentsByTag`. #### Mapping to `ph generate` | Generated artifact | File in this recipe | |---|---| | `ph generate --processor` | `src/processor.ts` — `CatalogProcessor extends RelationalDbProcessor<CatalogDB>` | | `ph generate --subgraph` | `src/subgraph.ts` — GraphQL SDL + resolvers backed by the query layer | | Schema types | `src/schema.ts` — Kysely DB interface | | Migrations | `src/migrations.ts` — `up()`/`down()` functions | | Query layer | `src/query.ts` — type-safe Kysely queries with joins | #### Usage ```ts // 1. Create a Kysely instance (PGlite, PostgreSQL, etc.) const db = new Kysely<CatalogDB>({ dialect }); const relationalDb = createRelationalDb(db); // 2. Create and initialize the processor const processor = new CatalogProcessor("catalog", { branch: ["main"] }, relationalDb); await processor.initAndUpgrade(); // 3. Register with the Reactor processor manager await processorManager.registerFactory("catalog", () => [ { processor, filter: { branch: ["main"] }, startFrom: "beginning", }, ]); // 4. Start the GraphQL subgraph server startCatalogServer(db, 4002); // → Catalog subgraph ready at http://localhost:4002/graphql ``` #### Supergraph composition This subgraph can be composed into a supergraph alongside other subgraphs (e.g., the Reactor's built-in GraphQL endpoint). With a gateway like Apollo Router or GraphQL Mesh, you can query documents from the catalog and other sources in a single request. #### Running tests ```sh pnpm test ``` Tests use PGlite (embedded PostgreSQL) — no external database required. #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/relational-db-subgraph) </details> <details id="recipe-role-based-auth"> <summary><strong>Role-Based Auth</strong> — A custom document model where the creator is promoted to admin on first action, admins can grant or revoke admin and member roles, and a domain action (`writeNote`) is gated on member-or-higher.</summary> ### Role-Based Auth A custom document model where the creator is promoted to admin on first action, admins can grant or revoke admin and member roles, and a domain action (`writeNote`) is gated on member-or-higher. All authorization runs inside the reducer against `action.context.signer.user.address`. #### What it demonstrates - State-embedded RBAC — access control lives in the document state and replicates with it. - Reducer-level enforcement — every operation reads `action.context.signer.user.address` and rejects unauthorized callers. - Creator auto-promotion — the first `bootstrap` caller becomes the permanent root admin and cannot be demoted. - Typed error taxonomy — authorization failures surface as named error classes generated into `gen/access/error.ts`. #### State shape ```graphql type RoleBasedAuthState { creator: String admins: [String!]! members: [String!]! notes: [Note!]! } type Note { id: OID! author: String! text: String! createdAt: DateTime! } ``` #### Operations | Operation | Who can call | Effect | |---|---|---| | `bootstrap` | anyone, once | Sets the caller as `creator` and pushes them into `admins`. Throws `AlreadyBootstrapped` on a second call. | | `grantAdmin(address)` | admin | Promotes `address` to admin; removes from `members` if present. | | `revokeAdmin(address)` | admin | Removes `address` from admins. Throws `CannotRevokeCreator` on the creator, `LastAdmin` if it would empty the admin set. | | `addMember(address)` | admin | Adds `address` to `members`. Throws `AddressAlreadyAdmin` if the address is already an admin. | | `removeMember(address)` | admin | Removes `address` from `members` (no-op if absent). | | `writeNote({ id, text, createdAt })` | admin or member | Appends `{ id, author, text, createdAt }` to `state.notes`. Throws `NotAuthorized` if the caller has no role. | Every operation throws `NotAuthorized` if `action.context.signer` is missing. #### Authorization pattern Each reducer op begins with: ```ts const address = action.context?.signer?.user?.address; if (!address) throw new NotAuthorized("User is not authenticated"); ``` Role-mutating ops additionally call `requireAdmin(state, address)`. Thrown errors are captured by the framework and surfaced as `operation.error` on the resulting document — callers inspect the operation log to detect rejection. See `document-models/role-based-auth/v1/src/reducers/access.ts` for the full implementation. #### Running ```sh pnpm install pnpm start # runs src/demo.ts ``` The demo walks through: Alice bootstraps, Bob is rejected from `writeNote`, Alice adds Bob as a member, Bob writes a note, Bob is rejected from `grantAdmin`, Alice promotes Bob, Bob promotes Carol, Carol is rejected from demoting the creator. #### Tests ```sh pnpm test ``` The suite in `document-models/role-based-auth/v1/tests/access.test.ts` covers the single-bootstrap invariant, missing-signer rejection, non-admin role-mutation rejection, creator-cannot-be-demoted, grantAdmin moving members to admins, and writeNote gating. #### Regenerating The document-model spec lives in `document-models/role-based-auth/role-based-auth.json` with the GraphQL schema at `document-models/role-based-auth/v1/schema.graphql`. To regenerate the `gen/` tree after editing either file: ```sh pnpm run generate ``` The hand-written reducer at `v1/src/reducers/access.ts` is not touched by codegen. #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/role-based-auth) </details> <details id="recipe-saga"> <summary><strong>Saga</strong> — Saga pattern via Reactor processor: operations on one document trigger operations on others, linked by a traceable saga context.</summary> ### Saga Saga pattern via Reactor processor: operations on one document trigger operations on others, linked by a traceable saga context. #### What it demonstrates - `IProcessor` as a saga coordinator — a processor that reacts to operations and dispatches follow-up actions on other documents - Saga correlation via DB — a `saga_id` ties every step together, tracked entirely in the processor's own table (no changes to document interfaces) - `IReactor.execute()` from within a processor — the processor dispatches actions to other documents in response to incoming operations - Re-entrancy guard — prevents the processor from reacting to its own dispatched operations #### How it works 1. Creates a drive with three documents: Order-001, Payment-001, and Fulfillment-001 2. Registers a `SagaProcessor` with step definitions that form a chain: - `Order-001 [CREATED]` → dispatches rename on Payment to `Payment-001 [REQUESTED]` - `Payment-001 [REQUESTED]` → dispatches rename on Fulfillment to `Fulfillment-001 [STARTED]` - `Fulfillment-001 [STARTED]` → dispatches rename on Order to `Order-001 [FULFILLED]` 3. Triggering the saga by renaming the order document cascades through all three steps 4. The saga log table records every step with a shared `saga_id` for traceability #### Running ```sh pnpm install pnpm --filter @powerhousedao/saga start ``` #### Expected output ``` Saga Pattern Demo ================== Demonstrates: processor-based saga coordination across documents, with a traceable saga_id linking every step. Starting reactor... done (X.Xs) Creating drive... <drive-id> Creating order document... <order-id> Creating payment document... <payment-id> Creating fulfillment document... <fulfillment-id> Documents named: "Order-001", "Payment-001", "Fulfillment-001" Registered saga processor --- Triggering saga: renaming Order-001 to Order-001 [CREATED] --- --- Final document state --- Order: "Order-001 [FULFILLED]" Payment: "Payment-001 [REQUESTED]" Fulfillment: "Fulfillment-001 [STARTED]" --- Saga log --- Saga ID: <uuid> Step: order-created <order-id> -> <payment-id> action: SET_NAME status: dispatched Step: payment-requested <payment-id> -> <fulfillment-id> action: SET_NAME status: dispatched Step: fulfillment-started <fulfillment-id> -> <order-id> action: SET_NAME status: dispatched + Saga completed successfully ``` #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/saga) </details> <details id="recipe-semantic-search"> <summary><strong>Semantic Search Processor</strong> — A Reactor `IProcessor` that embeds document content with an in-process model (Transformers.js) into PGlite's `vector` extension and answers cosine-similarity queries — the semantic sibling of the [full-text-search](#recipe-full-text-search) recipe.</summary> ### Semantic Search Processor A Reactor `IProcessor` that embeds document content with an in-process model (Transformers.js) into PGlite's `vector` extension and answers cosine-similarity queries — the semantic sibling of the [full-text-search](https://github.com/powerhouse-inc/recipes/blob/main/semantic-search/../full-text-search) recipe. No external API, no API key, no server: the `all-MiniLM-L6-v2` model runs in-process via ONNX, and pgvector runs inside PGlite. #### How it works When operations arrive, the processor: 1. Collects the last operation per document (earlier states are superseded). 2. Flattens the resulting document state into a single string (same extraction as full-text-search) and truncates it to the model's effective window. 3. Hashes the text and skips re-embedding when the hash is unchanged — embedding is by far the most expensive step. 4. Embeds the text into a 384-dimensional vector and upserts it into `semantic_index` (`embedding vector(384)`, HNSW index, cosine ops). 5. Handles `DELETE_DOCUMENT` actions by removing the corresponding row. Queries go through `searchSimilar(text, k)`: embed the query with the same model, then `ORDER BY embedding <=> $1 LIMIT k`. With normalized embeddings, `similarity = 1 - cosine distance`. #### Architecture | Module | Purpose | |--------|---------| | `processor.ts` | `SemanticSearchProcessor` — the `IProcessor` implementation | | `embedder.ts` | Real embedder: Transformers.js feature-extraction pipeline, lazily initialized once | | `schema.ts` | Kysely type definitions for the `semantic_index` table | | `migrations.ts` | `up` / `down`: `CREATE EXTENSION vector`, the table, and the HNSW index | | `query.ts` | `createSimilarityQuery` — returns a `searchSimilar(text, k?)` helper | | `utils.ts` | Text flattening, truncation, content hashing, vector literals, dimension guard | #### Run it ```sh pnpm start # runs demo.ts pnpm test # offline — uses a deterministic fake embedder ``` The demo builds a reactor, registers the processor, creates ten documents on distinct topics, then runs semantic queries side by side with lexical full-text search over the same content. Queries like "my car needs an oil change" find "Automobile Maintenance and Repair Manual" — a hit lexical search misses because query and document share no words. First-run model download: `demo.ts` downloads ~25 MB (quantized MiniLM) from the HuggingFace Hub into `.model-cache/` next to the sources; later runs are fully offline. Tests never download anything — they inject a fake embedder (word-hash → pseudo-vector) so similarity ordering and processor mechanics are testable in CI. #### Usage ```ts up, embed, SemanticSearchProcessor, createSimilarityQuery, } from "@powerhousedao/example-semantic-search"; // PGlite must be constructed with the vector extension const pglite = new KyselyPGlite({ extensions: { vector } }); const db = new Kysely<SemanticSearchDB>({ dialect: pglite.dialect }); await up(db); const processor = new SemanticSearchProcessor(db, embed); // ...register with a ProcessorManager... const query = createSimilarityQuery(db, embed); const results = await query.searchSimilar("budget allocation", 10); // [{ document_id, document_type, title, similarity }] ``` #### Notes & pitfalls - The embedding dimension is baked into the column type. `vector(384)` matches `all-MiniLM-L6-v2`; the processor asserts `embedding.length === 384` before insert, so swapping models with a different dimension fails loudly instead of corrupting the index. - Long content is truncated, not chunked. MiniLM attends to ~256 tokens; `utils.ts` cuts at 2 000 characters and stores exactly what was embedded. Production systems should chunk long content into multiple rows. - HNSW parameters don't matter at demo scale. The defaults (`m=16`, `ef_construction=64`) are fine until the table holds many thousands of vectors. - Plain vs. lazy imports. [`@powerhousedao/knowledge-note`](https://www.npmjs.com/package/@powerhousedao/knowledge-note) — the production proof of this stack — lazily `import()`s PGlite so its processor and subgraph still register on deployments where transitive runtime deps aren't installed. In a Node-only recipe a plain import is simpler; only the model pipeline is lazily initialized. #### Related recipes - [full-text-search](https://github.com/powerhouse-inc/recipes/blob/main/semantic-search/../full-text-search) — the lexical sibling; same layout, same text extraction, so the two approaches diff cleanly. - [relational-db-subgraph](https://github.com/powerhouse-inc/recipes/blob/main/semantic-search/../relational-db-subgraph) — how to expose a read model like this one over GraphQL. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/semantic-search) </details> <details id="recipe-signed-operations-verifier"> <summary><strong>Signed Operations Verifier</strong> — A standalone script that builds a document operation history with cryptographic signatures, then verifies each one.</summary> ### Signed Operations Verifier A standalone script that builds a document operation history with cryptographic signatures, then verifies each one. Demonstrates detection of unsigned and tampered operations, plus signer identity chain extraction. #### What it demonstrates - `ISigner` interface via `RenownCryptoSigner` from `@renown/sdk` - `RenownCryptoSigner` construction using `MemoryKeyStorage` + `RenownCryptoBuilder` (no filesystem or network needed) - `verifyOperationSignature()` — low-level per-signature verification with a custom `ActionVerificationHandler` - `createSignatureVerifier()` — higher-level operation verifier from `@renown/sdk` - `validateHeader()` — document header signature validation - Signature tuple structure — `[timestamp, publicKey, actionHash, prevStateHash, signature]` - Signer identity chain — user address/networkId/chainId + app name/key #### Run ```bash pnpm install pnpm --filter @powerhousedao/example-signed-operations-verifier test ``` #### Key APIs | Import | API | Purpose | |--------|-----|---------| | `document-model/core` | `verifyOperationSignature()` | Verify a single signature tuple | | `document-model/core` | `buildSignedAction()` | Create a signed operation from an action | | `document-model/core` | `actionSigner()` | Construct an `ActionSigner` with identity info | | `@renown/sdk/node` | `RenownCryptoSigner` | `ISigner` implementation using ECDSA P-256 | | `@renown/sdk/node` | `RenownCryptoBuilder` | Builder for the underlying crypto engine | | `@renown/sdk/node` | `MemoryKeyStorage` | In-memory key pair storage for demos | | `@renown/sdk/node` | `createSignatureVerifier()` | Higher-level full-operation verifier | [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/signed-operations-verifier) </details> <details id="recipe-subscription-cli"> <summary><strong>Subscription CLI</strong> — A standalone CLI for monitoring Powerhouse Reactor GraphQL subscriptions over WebSocket in real time.</summary> ### Subscription CLI A standalone CLI for monitoring Powerhouse Reactor GraphQL subscriptions over WebSocket in real time. Subscribes to `documentChanges` and optionally `jobChanges`, printing timestamped events to stdout. Useful for debugging, integration testing, and observing Reactor activity. #### Usage ```sh pnpm start ``` With options: ```sh pnpm start -- --url ws://localhost:4001/graphql/subscriptions \ --type "powerhouse/billing-statement" \ --parent-id "drive-abc-123" \ --auth "eyJhbG..." ``` #### CLI Options | Flag | Description | Default | |------|-------------|---------| | `--url <url>` | WebSocket endpoint | `ws://localhost:4001/graphql/subscriptions` | | `--type <type>` | Filter `documentChanges` by document type | _(none)_ | | `--parent-id <id>` | Filter `documentChanges` by parent document (drive) ID | _(none)_ | | `--job-id <id>` | Also subscribe to `jobChanges` for a specific job | _(none)_ | | `--auth <token>` | Bearer token for authentication | _(none)_ | | `--help` | Show help message | | #### Example output ``` [12:34:56.789] Connecting to ws://localhost:4001/graphql/subscriptions... [12:34:56.801] Connected [12:34:56.802] Subscribing to documentChanges (type: powerhouse/billing-statement)... [12:34:56.803] Listening for events. Press Ctrl+C to stop. [12:34:58.100] documentChanges [UPDATE] Invoice Q1 (powerhouse/billing-statement) ``` Press `Ctrl+C` for clean shutdown. [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/subscription-cli) </details> <details id="recipe-sync-health-monitor"> <summary><strong>Sync Health Monitor</strong> — Subscribes to `SyncEventTypes` on the Reactor EventBus and maintains a live health dashboard.</summary> ### Sync Health Monitor Subscribes to `SyncEventTypes` on the Reactor EventBus and maintains a live health dashboard. Exposes metrics via a GraphQL subgraph. #### What it shows - EventBus subscriptions — listens to all five sync event types (`SYNC_PENDING`, `SYNC_SUCCEEDED`, `SYNC_FAILED`, `DEAD_LETTER_ADDED`, `CONNECTION_STATE_CHANGED`) - ReactorModule internals — accesses `eventBus` and `syncModule` from the built `ReactorModule` - Two-reactor sync — wires two embedded reactors via a custom `InternalChannel` (no network, direct in-process delivery) - GraphQL subgraph — serves a `syncHealth` query with counters, connection states, and recent errors - Live dashboard — refreshing terminal display with health status, sync counters, and connection states #### How it works 1. Two embedded reactors — builds reactor A and reactor B, each with in-memory PGlite 2. Internal channels — a shared `IChannelFactory` creates `InternalChannel` pairs that deliver operations directly between reactors 3. Health monitor — subscribes to reactor A's `EventBus` for all `SyncEventTypes`, maintains counters and connection state 4. GraphQL server — serves the health metrics via a `syncHealth` query on `http://localhost:4001/graphql` 5. Demo scenario — runs through four phases: normal sync, connection state changes, simulated failure, and recovery ##### Demo phases | Phase | What happens | Events fired | |-------|-------------|-------------| | Normal sync | Create a document on A, syncs to B | `SYNC_PENDING`, `SYNC_SUCCEEDED` | | Connection issue | Simulate disconnect → reconnect on the channel | `CONNECTION_STATE_CHANGED` (x3) | | Failure | Make the channel throw, then create a document | `SYNC_PENDING`, `SYNC_FAILED`, `DEAD_LETTER_ADDED` | | Recovery | Restore the channel, create another document | `SYNC_PENDING`, `SYNC_SUCCEEDED` | ##### Health status logic | Status | Condition | |--------|-----------| | `healthy` | All connections up, low failure ratio, no dead letters | | `degraded` | A connection is disconnected/reconnecting, failure ratio >10%, or dead letters exist | | `unhealthy` | Any connection is in `error` state | #### Usage ```sh pnpm install pnpm start ``` ##### JSON mode ```sh pnpm start -- --json ``` Emits one JSON line per refresh interval instead of the visual dashboard. ##### GraphQL query While the dashboard is running, query the subgraph: ```sh curl -s http://localhost:4001/graphql \ -H 'Content-Type: application/json' \ -d '{"query":"{ syncHealth { healthStatus pendingCount successCount failureCount deadLetterCount connectionStates { remoteName state } recentErrors { timestamp remoteName error } } }"}' \ | jq . ``` ##### Example output ``` Sync Health Monitor uptime 0h 0m 12s ============================================================ Status: HEALTHY Sync Operations pending: 0 succeeded: 2 failed: 0 dead letters: 0 Connections remoteB connected ------------------------------------------------------------ GraphQL: http://localhost:4001/graphql Ctrl+C to quit ``` #### Tests ```sh pnpm test ``` Unit tests verify the `SyncHealthMonitor` class in isolation using a standalone `EventBus` with synthetic events. #### License AGPL-3.0-only [View source on GitHub →](https://github.com/powerhouse-inc/recipes/tree/main/sync-health-monitor) </details> {/* AUTO-GENERATED-RECIPE-DOCS-END */} ### Reactor Management <details id="starting-the-reactor"> <summary>Starting the Reactor</summary> ### How to Start the Powerhouse Reactor --- ### Problem statement You need to start the Powerhouse Reactor, the local service responsible for processing document model operations and managing state, typically for testing or development purposes. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed - A Powerhouse project initialized (`ph init`) - You are in the root directory of your Powerhouse project. ### Solution > Note: For development, Vetra Studio (`ph vetra --watch`) is the recommended workflow as it includes the reactor functionality along with automatic code generation and live preview. Use `ph reactor` directly when you need to run the reactor service independently. ### Using Vetra (Recommended for Development) ```bash ph vetra --watch ``` Vetra includes reactor functionality and provides: - Automatic code generation when document models change - Live preview of documents and editors - Integrated development environment ### Using Reactor Directly ### Step 1: Navigate to Project Directory (if needed) Ensure your terminal is in the root directory of your Powerhouse project. ```bash cd <yourprojectname> ``` ### Step 2: Run the Reactor Command Execute the `ph reactor` command. ```bash ph reactor ``` ### Expected outcome - The Reactor service starts, typically listening on `localhost:4001`. - You will see log output indicating the reactor is running and ready to process operations. - A GraphQL endpoint is usually available at `http://localhost:4001/graphql` for direct interaction and testing. ### Common issues and solutions - Issue: Reactor fails to start, mentioning port conflicts. - Solution: Ensure port `4001` (or the configured reactor port) is not already in use by another application. Stop the conflicting application or configure the reactor to use a different port (if possible, check documentation). - Issue: Errors related to storage or configuration. - Solution: Check the `powerhouse.manifest.json` and any reactor-specific configuration files for errors. Ensure storage providers (like local disk) are accessible and configured correctly. ### Related recipes - [Launching Vetra Studio](#launching-vetra-studio) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) </details> ### Data Synchronisation <details id="troubleshooting-document-syncing"> <summary>Troubleshooting Document Syncing: Supergraph vs. Drive Endpoints</summary> ### Troubleshooting Document Syncing: Supergraph vs. Drive Endpoints --- ### Problem statement You've created or modified documents within a specific drive using Powerhouse Connect, but when you query the main GraphQL endpoint (`http://localhost:4001/graphql`), you don't see the changes or the documents you expected. This can lead to confusion about whether data is being synced correctly. ### Prerequisites - Powerhouse CLI (`ph-cmd`) installed. - A Powerhouse project initialized (`ph init`). - Vetra Studio is running (`ph vetra --watch`) or the Powerhouse Reactor is running (`ph reactor`). - You have attempted to create or modify documents in a drive (e.g., a "finances" drive). ### Solution Understanding the different GraphQL endpoints in Powerhouse is crucial for effective troubleshooting: 1. The Supergraph Endpoint (`http://localhost:4001/graphql`): - This is the main entry point for the supergraph, which combines various subgraphs (e.g., system information, user accounts, etc.). - While you can query many things here, it's generally not the endpoint for direct, real-time document content operations like `pushUpdates` for a specific drive. 2. Drive-Specific Endpoints (e.g., `http://localhost:4001/d/<driveId>` or `http://localhost:4001/d/<driveId>/graphql`): - Each drive (e.g., "finances", "mydocs") has its own dedicated endpoint. - Operations that modify or directly interact with the content of a specific drive, such as creating new documents or pushing updates, are typically handled by this endpoint. - When you interact with documents in Powerhouse Connect, it communicates with these drive-specific endpoints. Troubleshooting Steps: 1. Identify the Correct Endpoint: - As illustrated in the scenario where a user was looking for documents in a "finances" drive, the key realization was needing to interact with the `http://localhost:4001/d/finances` endpoint for document-specific operations, not just `http://localhost:4001/graphql`. 2. Inspect Network Requests: - Open your browser's developer tools (usually by pressing F12) and go to the "Network" tab. - Perform an action in Powerhouse Connect that involves a document (e.g., creating, saving). - Look for GraphQL requests. You'll often see operations like `pushUpdates`. - Examine the "Request URL" or "Path" for these requests. You'll likely see they are being sent to a drive-specific endpoint (e.g., `/d/finances`, `/d/powerhouse`). - The payload might show `operationName: "pushUpdates"`, confirming a document modification attempt. 3. Querying Drive Data: - If you want to query the state of documents within a specific drive via GraphQL, ensure you are targeting that drive's GraphQL endpoint (often `http://localhost:4001/d/<driveId>/graphql` or through specific queries available on the main supergraph that reference the drive). The exact query structure will depend on your document models. 4. Clear Caches and Reset (If Necessary): - Sometimes, old state or cached data can cause confusion. As a general troubleshooting step if issues persist: - Try deleting the `.ph` folder in your user's home directory (`~/.ph`). This folder stores global Powerhouse configurations and cached dependencies. - Clear browser storage (localStorage, IndexedDB) for the Connect application. ### Expected outcome - You can correctly identify which GraphQL endpoint to use for different types of queries and operations. - You understand that document-specific operations (like creating or updating documents in a drive) are typically handled by drive-specific endpoints. - You can use browser developer tools to inspect network requests and confirm which endpoints Powerhouse Connect is using. - Documents sync as expected, and you can retrieve their state by querying the appropriate endpoint. ### Common issues and solutions - Issue: Documents created in Connect don't appear when querying `http://localhost:4001/graphql`. - Solution: You are likely querying the general supergraph. For document-specific data, ensure you are targeting the drive's endpoint (e.g., `http://localhost:4001/d/<driveId>`) or using queries designed to fetch data from specific drives. Inspect Connect's network activity to see the endpoint it uses for `pushUpdates`. - Issue: Persistent syncing problems or unexpected behavior after trying the above. - Solution: Consider cleaning the global Powerhouse setup by removing `~/.ph` </details> <details id="resetting-your-localhost-environment"> <summary>Resetting Your Localhost Environment</summary> ### How to Reset Your Localhost Environment --- ### Problem statement You are running Powerhouse locally (via `ph vetra --watch` or `ph connect`), but you can't find your local drive in the interface. Alternatively, you can see the drive or have recreated it, but the `DocumentModel` button is missing, preventing you from creating new document model schemas. ### Prerequisites - Powerhouse Connect is running locally. - The Powerhouse Connect interface is open in your browser. ### Solution This issue is often caused by corrupted or inconsistent data stored in your browser's local storage for the Connect application. Clearing this storage forces a re-initialization of your local environment. ### Step 1: Open Settings In the bottom-left corner of the Powerhouse Connect UI, click on the "Settings" menu. ### Step 2: Find the Danger Zone In the settings panel that appears, scroll or navigate to the "Danger Zone" section. ### Step 3: Clear Local Storage Click the "Clear storage" button. A confirmation prompt may appear. Confirming this action will wipe all application data stored in your browser for your local environment, including the state of your local drive. ### Step 4: Verify the Reset The application should automatically refresh and re-initialize its state. If it doesn't, manually reload the page. Your local drive should now be present with the `DocumentModel` button restored. ### Expected outcome - Your local drive is visible again in the Powerhouse Connect UI. - The `DocumentModel` button is available inside the local drive. - You can proceed to create and edit document models in your local environment. ### Common issues and solutions - Issue: The problem persists after clearing storage. - Solution: Try clearing your browser's cache and cookies for the localhost domain. As a last resort, follow the recipe for [Clearing Package Manager Caches](#clearing-package-manager-caches) and reinstalling dependencies. ### Related recipes - [Troubleshooting Document Syncing](#troubleshooting-document-syncing) - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model) </details> <details id="clearing-package-manager-caches"> <summary>Clearing Package Manager Caches</summary> ### How to Clear Package Manager Caches --- ### Problem statement You are encountering unexpected issues with dependencies, `ph-cmd` installation, or package resolution. Corrupted or outdated caches for your package manager (pnpm, npm, yarn) can often be the cause. Clearing the cache forces the package manager to refetch packages, which can resolve these problems. ### Prerequisites - Terminal or command prompt access - A package manager (pnpm, npm, or yarn) installed ### Solution Choose the commands corresponding to the package manager you are using. ### For pnpm `pnpm` has a robust set of commands to manage its content-addressable store. ```bash # Verify the integrity of the cache pnpm cache verify # Remove orphaned packages from the store pnpm store prune ``` ### For npm `npm` provides commands to clean and verify its cache. ```bash # Verify the contents of the cache folder, which can fix some issues npm cache verify # If verification doesn't solve the issue, force clean the cache npm cache clean --force ``` ### For Yarn (v1 Classic) Yarn Classic allows you to list and clean the cache. ```bash # List the contents of the cache yarn cache list # Clean the cache yarn cache clean --force ``` ### Expected outcome - The package manager's cache is cleared or verified. - Subsequent installations will fetch fresh versions of packages, potentially resolving dependency-related errors. - Your system is in a cleaner state for managing Powerhouse project dependencies. ### Common issues and solutions - Issue: Problems persist after clearing the cache. - Solution: The issue might not be cache-related. Consider completely removing `node_modules` and lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`) and running `pnpm install` (or equivalent) again. ### Related recipes - [Installing 'ph-cmd'](#installing-ph-cmd) - [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd) - [Managing and Updating Powerhouse Dependencies](#managing-and-updating-powerhouse-dependencies) </details> --- ## Glossary > Source: https://academy.vetra.io/academy/Lookup/Glossary ## General Terms - Powerhouse – A network organization that provides open-source software and services to support decentralized operations for other network organizations. - Scalable Network Organization (SNO) – A network organization structured according to the Powerhouse framework, designed for sustainable and scalable growth. - Powerhouse Ecosystem – The overall environment of Powerhouse tools, applications (like Connect), concepts (document models, packages), and services. ## Technology & Framework - CQRS (Command Query Responsibility Segregation) – A pattern that separates read and write operations to improve scalability. - Event Sourcing – A method of storing system state as a sequence of immutable events rather than modifying a single record. ## Software Components - Model Context Protocol (MCP) – A standardized protocol that enables AI agents and external tools to interact with systems through structured operations. Powerhouse uses MCP to provide AI access to document management capabilities. - Reactor – A storage node for Powerhouse documents and files with multiple storage adapters (local, cloud, decentralized). Reactors process mutations as jobs, emit events, and coordinate read models and processors. - IReactorClient – The primary programmatic interface for interacting with a reactor. Provides Promise-based methods for reading, creating, updating, deleting, and subscribing to documents. See the [IReactorClient API Reference](/academy/Reference/Reactor/ReactorClient). - Job (Reactor Job) – A unit of work in the reactor's queue. Each mutation (e.g., executing actions on a document) becomes a job that moves through statuses: PENDING, RUNNING, WRITE_READY, READ_READY, or FAILED. - ProcessorManager – The reactor component that routes operations to user-defined processors. After a job reaches READ_READY, the ProcessorManager matches operations against each processor's filter and calls `onOperations()` on matching processors. - Reactor-MCP – A Model Context Protocol server for the Powerhouse ecosystem that provides AI agents and tools with structured access to document model operations, serving as a bridge between AI systems and Powerhouse document management infrastructure. - Powerhouse Switchboard – A scalable API service that aggregates and processes document data. - Powerhouse Fusion – A platform front-end that hosts the public marketplace for SNO interactions. - Powerhouse Renown – A decentralized authentication system managing contributor reputation. - Powerhouse Academy – A training platform for onboarding and upskilling SNO contributors. - Connect – The contributor's public or private workspace, serving as the entry point for individual contributors to install apps and packages for specific business solutions. - Powergrid – A decentralized network of reactors that sync with each other. - Preview Drive – A local drive created in `--watch` mode during `ph vetra` development, used for testing local document models and editors without affecting the main synced drive. - Remote Drive – A Powerhouse drive hosted on a remote server (e.g., Vetra) that syncs across team members, enabling collaborative development on shared documents and document models. - Powerhouse CLI (ph) – The command-line tool for Powerhouse project initialization, code generation, package management, and running local development environments (Connect Studio). It also manages services, ensuring the terminology aligns with the updated setup guide. - Connect App (Connect Studio) – The primary Powerhouse application for defining document models, building/testing editors (in Studio mode), and collaborating on documents. - Document Tools – Built-in features within Powerhouse applications (e.g., Connect) that assist with document management, inspection, and interaction, such as Operations History. - Operations History – A Document Tool in Connect providing a chronological, immutable log of all operations on a document for traceability. - Studio mode – The local development mode of the Connect App (`ph connect`), for real-time document model definition, editor building, and testing. - Renown (Login Flow) – The Powerhouse decentralized login process using an Ethereum wallet signature to generate/retrieve a user's DID for secure, pseudonymous actions. - Powerhouse Switchboard (Verifier Role) – A function of Powerhouse Switchboard that validates DIDs and credentials for operations submitted via Connect, ensuring they are authorized. ## Document Modeling - Action Creators (for Document Operations) – Auto-generated helper functions creating structured "action" objects for dispatching operations to a document model's reducer. - Actions (Document Actions) – Typed objects representing an intent to change a document's state, dispatched to reducers, containing an operation type and input data. - API Integration (for Document Models) – The capability of Document Models to connect with Switchboard API or external APIs, facilitating data exchange between Powerhouse applications and other systems. - Data Analysis (with Document Models) – Leveraging the structured data within Document Models, often via read models, to extract insights, generate reports, and perform analytics on operational and historical data. - Dispatch (in Document Models) – The act of sending an action (representing an operation) to a document model's reducer to trigger a state update. - Document Model Specification – The formal definition of a document model (state, operations), created in Connect Studio (using GraphQL SDL) and exported (e.g., `.phdm.zip`) for code generation. - Document Models – Structured data models that define how Powerhouse documents store and process information. - Document State – The current data held by a document instance, structured according to its Document Model. - Document Type – A unique string identifier (e.g., `powerhouse/todo-list`) for a Document Model, used by host apps to select the correct editor/logic. - Event History (Append-Only Log) – An immutable, append-only log where every operation applied to a Powerhouse document is stored as an event. It provides a transparent audit trail and enables features like time travel debugging and state reconstruction. - GraphQL Scalars – Data types used in Powerhouse document modeling (e.g., `String`, `Int`, `Currency`, `OID` for unique object IDs). - GraphQL Schema Definition Language (SDL) (for Document Models) – Language used in Connect Studio to define a Document Model's data structure (state) and operations. - Immutable Updates – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing. - Input Types (GraphQL for Document Operations) – Custom data structures in SDL detailing parameters for document operations (e.g., `AddTodoItemInput`). - Model-Driven Development (MDD) – A software approach that uses high-level models to generate system logic and configurations. - Operations (Document Operations) – Named commands (e.g., `ADD_TODO_ITEM`) in a Document Model representing all ways to change its state, forming its event log. - Powerhouse Document (`.phd` file) – Standard file extension for an exported Powerhouse document instance, containing its data and history. - Pure Functions (for Reducers) – Principle that document model reducers must be pure (output depends only on input, no side effects) for predictable state transitions. - Reducers (Document Model Reducers) – Functions implementing a Document Model's logic; for each operation, a reducer takes current state and an action, returning new state. - Replay Events – The process of re-applying recorded events from a document's Event History to reconstruct or restore its state, a core capability of Event Sourcing. - Scope – A partition of a document's operation history. Operations are grouped by scope (e.g., `"global"`, `"local"`), allowing independent histories on the same document. Global scope contains shared state; local scope contains user-specific state. - Branch – A named fork of a document's operation history, enabling draft/published workflows. Operations are isolated per branch. The default branch is `"main"`. - State (Global State in Document Model) – The primary, persisted, shared data of a document instance, managed by its reducers. - State Schema – The component of a Document Model that defines the structure of the document, including its fields, data types, and validation rules, typically using a GraphQL-like syntax. It serves as a blueprint for how data is stored and validated. - Strands – A single synchronization channel that connects exactly one unit of synchronization to another, with all four parameters (drive_url, doc_id, scope, branch) set to fixed values. This allows synchronization between two distinct points of instances of a document or document drive. - Time Travel Debugging – A debugging technique, enabled by a document's Event History, that allows developers to reconstruct and inspect past states of the document by replaying events up to a specific point in time. - Type Safety (in Document Modeling) – Powerhouse's use of auto-generated TypeScript definitions from a model's schema (SDL) to prevent data type errors in development. - Version Control (for Document Models) – A planned feature for Document Models in Connect that will allow tracking of changes, comparison of different versions, and maintenance of data integrity over time, similar to version control systems for source code. ## Development & Tooling - Boilerplate (Powerhouse Project) – The `ph init` command's initial project structure, providing a standard starting point for new Powerhouse packages. - Connect Build – The output of the `ph connect build` command, which packages a Connect project into a distributable format. This build includes all necessary local/external packages, assets, and styles, and can be previewed locally with `ph connect preview` or deployed. - Development Environment (Powerhouse) – A local setup for developing Powerhouse applications. Use `ph reactor` to start the backend services (Powerhouse Switchboard) for real-time document model processing, code generation, and live updates, and `ph connect` to start the front-end Connect Studio. These can be run independently or together in separate terminals. - Document Model Editors – An interface or UI to a document model that allows users to create and modify the data captured by the document models. - Drive – A logical container in Powerhouse for storing, organizing, and managing collections of documents. - Drive-app – A UI application, often custom, providing tailored views and interactions with documents in a drive. - Environments (Powerhouse Environments) – Pre-defined configurations for a project's Powerhouse dependencies, such as `dev` (development), `prod` (production/latest), and `local`. The Powerhouse CLI (`ph use` command) allows developers to easily switch between these environments to use different versions of packages (e.g., bleeding-edge, stable, or from a local monorepo). - Host Applications – Applications that use the Powerhouse framework to create and manage documents and data. - Modules (in Document Model Editor) – An organizational feature in Connect Studio's model editor for grouping related operations. - Powerhouse Package – A collection of document models, document model editors, and other resources that are published as a package and can be used in any of the host applications. - Powerhouse Project – A collection of document models, document model editors, and other resources being build in Connect Studio. - Scalars (Design System Components) – Reusable UI building blocks (e.g., `Checkbox`, `InputField`) from `@powerhousedao/document-engineering/scalars`, used in editors (distinct from GraphQL scalars). - State (Local State in Editor) – Temporary, UI-specific data within an editor (e.g., form inputs), not persisted in the global document state. - Storybook (for Powerhouse Design System) – Interactive environment for browsing and testing Powerhouse Design System UI components. - Tailwind CSS (in Connect Studio) – Utility CSS framework integrated into Connect Studio for styling document editors. - Vetra – A Powerhouse platform for hosting remote drives, enabling collaborative development and document synchronization across team members. - Watch Mode (`--watch`) – A development mode flag for `ph vetra` that enables dynamic loading of local document models and editors, creating a separate Preview Drive for testing changes in real-time. ## AI & Automation - AI Assistants – AI-powered contributors paired with human contributors to automate tasks and improve productivity. - Document Model Agent – A specialized AI agent that guides users through creating document models, handling requirements gathering, design confirmation, and implementation using MCP tools for state schema definition, operation creation, and code generation. - AI Contributor Modes – Configurable states that determine the AI assistant's behavior, permissions, and task focus. - Task Automation & Scaling – The use of AI to streamline repetitive tasks, improve communications, and enhance decision-making. - Decentralized Identifier (DID) – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously. ## Organizational Concepts - Ceramic – A decentralized network for storing verifiable data, used by Powerhouse Renown for secure credential management. - Decentralized Identifier (DID) – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously. - Event-Driven Architecture (EDA) – A software design approach where system flows are determined by events that trigger actions asynchronously. - Network Organization – A group of independent contributors and teams working together towards a common purpose, relying on decentralization and resource sharing. --- ## LLM docs > Source: https://academy.vetra.io/academy/Lookup/LLMDocs The Powerhouse Academy follows the [llms.txt standard](https://llmstxt.org) to provide machine-readable documentation for LLMs and AI coding tools. ## Context7 [Context7](https://context7.com) is the easiest way to load up-to-date Powerhouse documentation directly into your AI coding assistant (Cursor, Windsurf, Zed, etc.). Search for powerhouse-inc/powerhouse in the Context7 library, or use the library ID `/powerhouse-inc/powerhouse`. ``` use context7 ``` ## Paste into Claude or ChatGPT Load the full documentation into a context window at once by pasting the URL directly into your chat: ``` https://academy.vetra.io/llms-full.txt ``` ## Programmatic access ```bash # Index (llms.txt) — links to every page with a short description (~22KB) curl https://academy.vetra.io/llms.txt # Full content (llms-full.txt) — all docs concatenated (~1MB) curl https://academy.vetra.io/llms-full.txt ``` ## Files | File | Purpose | Size | | ------------------------------- | ----------------------------------------------------------------------- | ----- | | [llms.txt](/llms.txt) | Navigation index — links to every doc page with a short description | ~22KB | | [llms-full.txt](/llms-full.txt) | All documentation concatenated into one file for full-context ingestion | ~1MB | ## Regenerating the files The files are generated from the academy source docs by the script at `scripts/generate-llm-docs.ts`. Run it with: ```bash npm run generate:llm-docs ``` This writes both `static/llms.txt` and `static/llms-full.txt`, which Docusaurus serves at the site root. ---

{doc.name}

{doc.header.name}

{document.name}

{document.name}

{drive.header.slug}

Failed to initialize

My App

Login Required

Profile

My App

Authentication Failed

My App

Authentication Required

{user.name || 'Anonymous User'}

Admin Panel

Failed to initialize

setIsEditing(true)} > {documentName}

TodoList

My Document Title

Related: {relatedDoc.name}

TodoList

TodoList

ToDos:

Document Title