From 7804b34d590796be1bec505174e9cfd4ea1a67cf Mon Sep 17 00:00:00 2001
From: Drish-xD <drish.xd@gmail.com>
Date: Sun, 11 Jun 2023 16:44:38 +0530
Subject: [PATCH] fixed readme
---
README.md | 233 ++++++++++++++++++++++++++++--------------------------
1 file changed, 122 insertions(+), 111 deletions(-)
diff --git a/README.md b/README.md
index cea0a91..4db4017 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,14 @@
-<p align="center">
- <h1>Workflow Module</h1>
-</p>
+<h1 align="center">Workflow Module</h1>
+
+<div align="center">
[](https://gitpod.io/#https://github.com/Samagra-Development/workflow/tree/dev)
+</div>
+
## About :open_book:
-Enketo has been used all around the world for a wide range of purposes, from needs assessments in humanitarian aid, to raising historical awareness, to clinical research, to election monitoring.
+Workflow is an Open Source project aimed towards the creation of data flow models using config files thereby allowing you to easily create and interact with stateful applications with minimum setup.
## Features :dart:
@@ -22,102 +24,140 @@ Enketo has been used all around the world for a wide range of purposes, from nee
+# Setup :gear:
+
## Requirements :scroll:
1. Your machine should have [Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable) or [Npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), [Docker](https://docs.docker.com/get-docker/), [Python](https://www.python.org/downloads/) installed.
-*Note: Preferable Npm version (6.14.15) and Node version(v14.18.1) and Ubuntu OS version(18.04)**
+ > Note: Preferable Npm version (6.14.15) and Node version(v14.18.1) and Ubuntu OS version(18.04)
2. Check the node and npm version by running following commands.
-```sh
-node -v
-npm -v
-```
+ ```sh
+ node -v
+ npm -v
+ ```
-# How to get up and running?
+ <details>
+ <summary><b>Method 1 (Using Gitpod)</b></summary>
- Fork this repo ðŸ´
- Click on the Gitpod button above â˜ï¸
- It opens a complete development setup directly 😄
- No need to clone and struggle with installing packages, managing node versions, banging head on the keyboard, etc (Cool right?)
-### This is how it looks 👀
-
+ ### This is how it looks 👀
-# How to interact?
-- If you go to ports on terminal and open the `React Wrapper app` running on port 3000 you can see a demo UI like this 👇
+ 
-
-- Currently offering 4 demo flows namely
-- Jumping Forms (Opening of next form once the first one is submitted)
-- Hasura Submissions (Basically saving the form data to any database, hasura extending postgres in this case)
-- Offline capabilites (How the form behaves when working offline)
-- File Upload (How to handle uploading files to any desired CDN, Minio in this case)
+ </details>
-# Flows Explained ðŸ“
-## Jumping Forms
-- This flow basically covers how you can configure your forms using form spec file (covered in a little while) to handle how the submission works. Like opening another form or redirecting to some page within the app or opening this link [here](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
+ <details>
+ <summary><b>Method 2 (Manually on Local Machine)</b></summary>
-
+1. Fork the repository ðŸ´
+2. Clone the forked repository to your local machine. And goto the root directory of repository.
+3. Change the enviroment variables in sample.env or .env file as shown below.
+ It will use the locally created containers and connect to those services.
-## Hasura Submissions
-- Covering how to handle form data submission to your database be it a sql or NoSql based db. In our setup we have used Hasura which creates an instant GraphQL data provider to use with Postgres based db
+ ```
+ REACT_APP_ENKETO_URL=http://localhost:8065
+ REACT_APP_FORM_MANAGER_URL=http://localhost:3006
+ REACT_APP_HASURA_URL=http://localhost:8080
+ ```
+4. Start the docker services
-
+ ```sh
+ docker-compose up -d --build
+ ```
-## Offline Capabilites
-- Just touching on to the offline capabilites offered right now. Here we have configured the form such that rather than failing form submissions entirely, it throws a warning/info message to the user indicating that the user is offline and is advised to resubmit the form once they're back online.
+5. Stop and remove the container of React app named `wrapper`
-
+ ```sh
+ docker ps -aqf "name=wrapper"
+ # Use the output `<id>` to stop the wrapper container.
+ docker stop <id> && docker rm <id>
+ ```
+6. Navigate to the `wrapper` directory.
-## File Upload
-- One of the most important thing in any kind of form input is how to handle file uploads. Workflow module allows you to configure your cdn easily and point file uploads directly to the CDN effortleslly 💃 In our configuration we have used Minio to store all the uploaded files.
+ ```sh
+ cd apps\wrapper\
+ ```
-
+7. Using pnpm to install dependencies and run the app live
+
+ ```sh
+ pnpm install
+ pnpm run start
+ ```
+
+> NOTE: For local development enketo-express needs node 14 and pnpm@7. Run nvm use 14 && `npm i -g pnpm@7` if developing in enketo-express
+
+</details>
+
+---
+
+# How to interact?
+
+- If you go to ports on terminal and open the `React Wrapper app` running on port 3000 you can see a demo UI
+ <details>
+ <summary><b>Like This 👇</b></summary>
+
+ 
+
+ </details>
-# Setup gitpod to change in code and run on live server
+- Currently offering 4 demo flows namely
+ - Jumping Forms (Opening of next form once the first one is submitted)
+ - Hasura Submissions (Basically saving the form data to any database, hasura extending postgres in this case)
+ - Offline capabilites (How the form behaves when working offline)
+ - File Upload (How to handle uploading files to any desired CDN, Minio in this case)
-## By using npm
+## Flows Explained ðŸ“
-1. cd apps
+<details>
+<summary><b>Jumping Forms</b></summary>
- cd wrapper
+This flow basically covers how you can configure your forms using form spec file (covered in a little while) to handle how the submission works. Like opening another form or redirecting to some page within the app or opening this link [here](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
-2. run docker ps
+
- copy CONTAINER ID of wrapper
+</details>
-3. run docker stop ID(copied on step2)
+<details>
+<summary><b>Hasura Submissions</b></summary>
-4. run docker rm ID(copied on step2)
+Covering how to handle form data submission to your database be it a sql or NoSql based db. In our setup we have used Hasura which creates an instant GraphQL data provider to use with Postgres based db
-5. run docker images
+
- copy IMAGE ID of wrapper
+</details>
-6. docker rmi ID(copied on step5)
+<details>
+<summary><b>Offline Capabilites</b></summary>
-7. make .env in wrapper directory
+Just touching on to the offline capabilites offered right now. Here we have configured the form such that rather than failing form submissions entirely, it throws a warning/info message to the user indicating that the user is offline and is advised to resubmit the form once they're back online.
-8. REACT_APP_ENKETO_URL=COPY REACT_APP_ENKETO_URL FROM .env (main directory-WORKFLOW)
+
- REACT_APP_FORM_MANAGER_URL=COPY REACT_APP_FORM_MANAGER_URL FROM .env (main directory-WORKFLOW)
-
- REACT_APP_HASURA_URL=COPY REACT_APP_HASURA_URL FROM .env (main directory-WORKFLOW)
+</details>
+<details>
+<summary><b>File Upload</b></summary>
-9. npm i --legacy-peer-deps
-10. npm audit fix --force(1 or 2 times)
+One of the most important thing in any kind of form input is how to handle file uploads. Workflow module allows you to configure your cdn easily and point file uploads directly to the CDN effortleslly 💃 In our configuration we have used Minio to store all the uploaded files.
-11. npm run start
+
+</details>
-# How to integrate custom backend?
+## How to integrate custom backend?
In order to achiever this, the submission url in the form spec (covered later below) with your hosted backend.
+
# Future Enhancements :rocket:
@@ -132,9 +172,14 @@ We are trying to an inversion of control here.
### For Get API
-`curl --location --request GET 'http://localhost:3002/form/form2'`
+```sh
+curl --location --request GET 'http://localhost:3002/form/form2'
+```
-### Form PrefillXML API
+<details>
+ <summary><b>
+ Form PrefillXML API
+ </b></summary>
```sh
curl 'https://3006-samagradevelop-workflow-mxpsr1yqse0.ws-us92.gitpod.io/prefillXML?form=jumping_form_1&onFormSuccessData=formFunction' \
@@ -155,15 +200,13 @@ curl 'https://3006-samagradevelop-workflow-mxpsr1yqse0.ws-us92.gitpod.io/prefill
--compressed
```
-## Architecture
-
-<!-- Insert LLD Image here -->
-
+</details>
+<details>
+ <summary><b>
+ Example Wrapper Config
+ </b></summary>
-## Wrapper Config
-
-Example config
```json
{
"start": "form1",
@@ -222,7 +265,7 @@ Example config
"id": "https://google.com"
}
},
- "metaData": {
+ "metaData": {
"constantForm2": "Test"
}
}
@@ -242,60 +285,28 @@ Example config
}
```
-### State
-State for prefilling, sideEffect.
+</details>
+
+<!-- ## Architecture
+
+  -->
+
+<details>
+ <summary><b>State for prefilling, sideEffect</b></summary>
+
```json
{
- "onFormSuccessData": {},
- "formConfig": {},
- "formState": {},
+ "onFormSuccessData": {},
+ "formConfig": {},
+ "formState": {}
}
```
-TODO: Add details on the specifications
+</details>
+
+> TODO: Add details on the specifications
## Possible Attack Vectors
+
1. XSS (High Priority) - Simple form
2. SQL Injection (High Priority) - needs to be fixed.
-
-
-### LocalSetup
-1. Fork the repository on your local machine.
-2. Make sure you have docker and docker compose on your machine.
-3. Change the enviroment variables in sample.env or .env file as shown below.
- It will use the locally created containers and connect to those services.
- ```
- REACT_APP_ENKETO_URL=http://localhost:8065
- REACT_APP_FORM_MANAGER_URL=http://localhost:3006
- REACT_APP_HASURA_URL=http://localhost:8080
- ```
-4. Run the command
- - For Development Environment
- ```sh
- type -p curl >/dev/null || sudo apt install curl -y
- curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
- sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
- echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
- sudo apt update
- sudo apt install gh -y
- ```
- - For installing ODK-Central
- ```sh
- bash install-central.sh
- ```
- - To start Services
-
- 1. If you have v1 of docker then excute this command
- ```sh
- docker-compose up -d
- ```
- 2. Otherwisse execute this
- ```sh
- docker compose up -d
- ```
-NOTE:
------
-```
-For local development enketo-express needs node 14 and pnpm@7
-Run nvm use 14 && npm i -g pnpm@7 if developing in enketo-express
-```
\ No newline at end of file
--
GitLab