Document model generation
This page focused on developers starting out with document model generation.
Introduction to Document Models
Document models are at the core of the Powerhouse platform, defining the structure and behavior of documents within the system. These models capture critical business logic and data structure, facilitating a systematic approach to managing a DAO’s business processes.
Document models live inside connect, but the data they capture can be propagated through all of Powerhouse's core applications. Each document model can be interacted with through a customised user interface within connect.
Step 1: Getting Started
Setup: To begin working with Connect, you'll need to set up the environment locally. This involves:
Cloning the repository, installing dependencies, and starting the application.
Alternatively you could also head over to our release page and install the latest release for the OS you're running or make use of the webapp of connect: https://document-model-electron.vercel.app/
You could also have a quick glance at the document model libs repository to see what a document models code looks like. This repository will be handy for future references.
Step 2: Setting the initiale state
Creating a Document Model: Within Connect, under "New Document" you'll find the different document models that are currently available. Select "DocumentModel" to start creating your first document model.
The foundation or base of a document model is itself also structured as document model. This principle is called meta-modelling.
Foundational document model = DocumentType: Powerhouse/document-model This is a foundational document model that forms a base for other document models to be build upon.
Example Creation: As an illustrative example, consider creating a document model named "Team Operations Flow." This model could potentially specify the structure for the document model related to a teams 'Operational processes' and intent to capture the team structure, meeting schedules and operational flow.
Fill in the required information for your document model, such as:
Model Type:
Model Description: A description of the model's purpose
File Extension(s): A 3 letter short code for your document model name. (e.g. TOF: TeamOperationsFlow)
Author name & Author URL
Defining Global vs. Local States
Understanding 'States':
Global State: Refers to data that is shared across all instances of a document existing in the different drives of connect. Modifications to the global state are synchronized across all users, ensuring consistency. Therefor Global State operations can be understood as "Public", "Common state" between users or "Transparent content"
Local State: Pertains to data unique to a user's interaction with a document. Changes to the local state, or local state operations are not distributed to other users, allowing for personalized interactions while maintaining privacy.
Different Usage Scenarios:
Use global state for data that needs to be consistent and shared among all users of a document.
Use local state for user-specific settings or data that shouldn't be shared across the network (yet).
In the future different sections of a document model will be able to be assigned different states.
Both of the global and local state schema's can be defined in GraphQL programming languages and allow for the definitions of "types". The global initial state will define the initial state of the document and will make use of the schema's you'll be defining in the state schema.
Defining Modules & Operations
Now we'll need to create the different "operations" that allow a user to interact with the document model. Each set of operations around a specific theme will be grouped under a "module". In the example above you'll see that we've defined an operation "ADD_TEAM_MEMBER" under the module "TEAM STRUCTURE". Modules are a way to keep things organised and tidy in your document model
Operations represent the fundamental "actions" or transformations that can be applied to the document's state, capturing the essence of how data within the document changes over time. Each operation is a discrete, recorded action, such as adding, updating, or deleting content, that transitions the document from one state to another. Developers can define custom operations tailored to specific business logic, ensuring that the document model precisely reflects the dynamics of the information it represents. Operations also facilitates undo/redo actions, version control, and collaborative editing. Operations enable you to programmatically capture and manipulate the evolving state of your data within a document model and throughout Powerhouse native apps.
You'll be able to add more operations and modules with the help of a code editor in the next few steps. For now we've shown you how to set up basic details to get you started with your "document model definition". Let's move on to the next step.
Step 3: Exporting your documentmodel ZIP file
After creating your document model hit the save button and export it as a ZIP file. You'll see it has the name you set at the beginning followed by ".phdm.zip."
Phdmstands for the Powerhouse Document Model file extension. Once you'll have created your specific document model it will have the file extension shortcode you set at the start of the document model creation. In our example that will be 'tof' (team operations flow).You'll now be able to open the zipfile in a code editor. The zipfile contains several Json files that offer a framework to further define the document model:
Header.json: Here you'll see the title you gave your document model. You'll also find out that the documentType it's based on is the foundational document model:
powerhouse/document-model.Operations.json: Here you'll get a look at the inner workings of the foundational document model as the recorded operations are the ones we've been applying to the base document model to create a document model of our own. With types defined such as
SET_NAME,SET_MODEL_EXTENSIONetc.
Step 4: Create or Clone a Document Model Library Project
Option 1: Create a New Document Model Library Project
You'll now have to setup your directory and project to start developing your document model further. Use Yarn to create a new document model library project. Replace "PROJECT_NAME" with your desired project name:
After running the command, you'll have a new project directory created.
Option 2: Clone an existing Document Model Library Project from Powerhouse
Step 5: Generate the Document Model
You'll now run a code generation system on your "document model definition" (The ZIP file).
It will automatically generate a series of templates, folders and files that contain the basics of the actual code you'll need to have your document model functioning. Such as the build scripts, type configuration and dependencies.
So let's start to generate the document model using the following command, replacing "DOCUMENT_MODEL" with the the path to the ZIP file you've saved previously:
This command will create a directory for the /document-models directory within your project which contains all of the files and folders for further document model development.
JSON file with the document model specification, it's modules and the operations you've been alongside the schema's.
GraphQL file with the state and operation schemas and different types that have been created.
genfolder with autogenerated code.srcfolder with custom code that requires to be completed for a functional document model. This is the folder were you'll actually be making changes. Here you will find the reducers for each of the "Modules" that we will work with in the next step.
Last updated