Improved docs (#10)

README.md

@@ -8,6 +8,6 @@
   </p>
 
   <p>
-    <a href="https://harshadmanglani.github.io/polaris/docs/getting-started/">Installation</a> | <a href="https://harshadmanglani.github.io/polaris/docs/usage/">Documentation</a> | <a href="https://twitter.com/PolarisGithub">Twitter</a> | <a href="https://github.com/flipkart-incubator/databuilderframework">Inspiration</a>
+    <a href="https://harshadmanglani.github.io/polaris/docs/getting-started/">Installation</a> | <a href="https://harshadmanglani.github.io/polaris/docs/usage/">Documentation</a> | <a href="https://twitter.com/polaris_golang">Twitter</a> | <a href="https://github.com/flipkart-incubator/databuilderframework">Inspiration</a>
   </p>
 </div>

docs/docs/api.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 5
+sidebar_class_name: hidden
+---
+# API Reference

docs/docs/concepts/_category_.json

@@ -0,0 +1,7 @@
+{
+    "position": 3,
+    "label": "Concepts",
+    "collapsible": true,
+    "collapsed": false,
+    "className": "red"
+  }

docs/docs/concepts/builder.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 3
+---
+# Builder
+
+An actor that consumes a bunch of data and produces another data. It has the following meta associated with it:
+    * **Name** - Name of the builder.
+    * **Consumes** - A set of data that the builder consumes.
+    * **Produces** - Data that the builder produces.
+    * **Optionals** - Data that the builder can optionally consume; one possible use case for this: if a builder wants to be re-run on demand with the same set of consumable data already present, add an optional data in the Builder and restart the workflow by passing an instance of the optional data in the data-delta
+    * **Access** - Data that the builder will just access and has no effect on the sequence of execution of builders
+    * **BuilderContext** - A wrapper to access the data given to that builder to process.
+
+A Builder is a unit of work in the workflow. Builders must implement the `IBuilder` interface.
+
+```go
+type IBuilder interface {
+  GetBuilderInfo() BuilderInfo
+  Process(BuilderContext) IData
+}
+```
+
+Following the same example, for the first unit of work in a cab ride workflow:
+```go
+var database Database
+var cabbieHttpClient CabbieHttpClient 
+
+type UserInitiation struct {
+}
+
+func (uI UserInitiation) GetBuilderInfo() BuilderInfo {
+  return BuilderInfo{
+    Consumes: []IData{
+        UserInitiationRequest{},
+    },
+    Produces:  UserInitiationResponse{},
+    Optionals: nil,
+    Accesses:  nil,
+  }
+}
+
+func (uI UserInitiation) Process(context BuilderContext) IData {
+  userInitReq := context.get(UserInitiationRequest{})
+  // save the request in a database (different from Polaris storing workflows in `IDataStore`)
+  database.save(userInitReq)
+
+  // call another service to place a request, and wait for the response
+  cabbieResponse := cabbieHttpClient.request(RideRequest{
+    userId: userInitReq.userId,
+    source: userInitReq.source,
+    dest: userInitReq.dest
+  })
+
+  // once done, return the `Produces` of the data
+  return UserInitiationResponse{
+    success: true,
+    etaForCabbie: cabbieResponse.eta
+  }
+}
+```

docs/docs/concepts/data.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 4
+---
+
+# Data
+
+The basic container for information generated by an actor in the system.
+
+A Data is a struct that holds the data that will be consumed and/or produced by steps in your workflow.
+These objects must implement the `IData` interface, which basically means that they should be a `struct`.
+## Definition
+
+```go
+type IData interface {
+}
+```
+
+For a user initiating a cab ride request, this is what the initial `Data` might look like.
+
+```go
+type UserInitiationRequest struct{
+  userId string
+  source string
+  dest string
+}
+```

docs/docs/concepts/datastore.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 5
+---
+# Data Store
+
+Workflows need to be stored to a database. Whether you're using a key-value store or RDBMS, you need to implement the `IDataStore` interface and pass it to the `polaris.InitRegistry` method.
+
+```go
+type IDataStore interface {
+  Write(key string, value interface{})
+  Read(key string) (interface{}, bool)
+}
+```
+
+Once the interface is implemented, data stores must be set with polaris.
+```go
+polaris.InitRegistry(dataStore)
+```
+
+## In-memory data store
+**DO NOT DO THIS IN PRODUCTION!**
+
+While getting set up with polaris, you can start with a simple in-memory data store
+```go
+type mockStorage struct {
+  store map[string]interface{}
+}
+
+func (ms *mockStorage) Read(key string) (interface{}, bool) {
+  val, ok := ms.store[key]
+  return val, ok
+}
+
+func (ms *mockStorage) Write(key string, val interface{}) {
+  ms.store[key] = val
+}
+
+mockStorage := &mockStorage{
+  store: make(map[string]interface{}),
+}
+
+polaris.InitRegistry(dataStore)
+```

docs/docs/concepts/polaris.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+title: Polaris
+---
+# What is Polaris?
+
+
+Polaris helps you create, store and run workflows. 
+
+You don't need to worry about:
+- Feeding the sequence of steps (it will figure out which the sequence along with the ones that can run concurrently)
+- Explicitly pausing workflows (when it runs out of new data to move the workflow ahead, it pauses)
+
+A workflow is a series of multiple steps, and can often be long running. 
+
+Workflow orchestrators (like Polaris) help break workflows down into chunks, so they can be processed asynchronously. If a workflow is waiting on an event, state is stored and the logical execution of the workflow is paused (meaning, the CPU is free to move on with other tasks). When the event is received, state is recovered and execution is resumed.

docs/docs/concepts/workflow.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 2
+title: Workflow
+---
+# What is a workflow?
+
+A specification and container for a topology of connected builders that generate a final data. It has the following meta:
+    * **Builders** - List of <a href="/polaris/concepts/builder">Builders</a>
+    * **Target Data** - The name of the <a href="/polaris/concepts/data">Data</a> being generated by this data flow. Once this is produced, the workflow is complete. It can, however, be re-opened by feeding new data.
+
+### Definition
+Workflows must implement the `IWorkflow` interface.
+```go
+type IWorkflow interface {
+	GetWorkflowMeta() WorkflowMeta
+}
+```
+
+Let's take the example of a cab ride workflow. Essentially, for a cab ride workflow, builders (units of work) could be:
+    - User initiating a request
+    - Cabbie match
+    - Cabbie reaches source
+    - Ride starts
+    - Cabbie reaches destination
+    - User makes payment
+    - Ride ends
+
+```go
+type CabRideWorkflow struct {
+}
+
+func (cr CabRideWorkflow) GetWorkflowMeta() WorkflowMeta {
+	return WorkflowMeta{
+		Builders: []IBuilder{
+                    UserInitiation{},
+                    CabbieMatching{},
+                    CabbieArrivalAtSource{},
+                    CabDepartureFromSource{},
+                    CabArrivalAtDest{},
+                    UserPayment{},
+                    RideEnds{}
+		},
+		TargetData: WorkflowTerminated{},
+	}
+}
+```
+You don't have to sequentially define the builders in order of execution. Polaris will figure it out. However, **you should if you can. It helps readability.**
+
+### Registering a workflow
+```go
+polaris.RegisterWorkflow(workflowKey, workflow)
+```
+
+### Executing a workflow
+
+```go
+executor := polaris.Executor{
+  Before: func(builder reflect.Type, delta []IData) {
+    fmt.Printf("Builder %s is about to be run with new data %v\n", builder, delta)
+  }
+  After: func(builder reflect.Type, produced IData) {
+    fmt.Printf("Builder %s produced %s\n", builder, produced)
+  }
+}
+// sequentially execute builders
+response, err := executor.Sequential(workflowKey, workflowId, dataDelta)
+
+// concurrently execute builders (does not guarantee parallelism!)
+response, err := executor.Parallel(workflowKey, workflowId, dataDelta)
+```

docs/docs/extensions/_category_.json

@@ -0,0 +1,7 @@
+{
+    "position": 6,
+    "label": "Extensions",
+    "collapsible": true,
+    "collapsed": true,
+    "className": "hidden"
+  }

docs/docs/extensions/observability.md

@@ -0,0 +1,4 @@
+---
+sidebar_position: 1
+---
+# Observability

docs/docs/extensions/recons.md

@@ -0,0 +1,4 @@
+---
+sidebar_position: 1
+---
+# Reconciliations

docs/docs/get-started.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+title: Get Started
+tags: 
+    - go
+---
+# Getting started with Polaris
+
+## Install Go
+Make sure you have Go installed. These tutorials were produced using Go 1.21
+
+Check your version of Go with the following command:
+```
+go version
+```
+
+This will return your installed Go version:
+
+```
+go version go1.21.5 darwin/arm64
+```
+## Install Polaris
+
+If you are creating a new project using Polaris, you can start by creating a new directory:
+
+```
+mkdir goproject
+```
+
+Next, switch to the new directory:
+```
+cd goproject
+```
+
+Then, initialize a Go project in that directory:
+```
+go mod init
+```
+
+Finally, install the Polaris with go get:
+```
+go get github.com/harshadmanglani/polaris
+```

docs/docs/home.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+slug: /
+title: Home
+---
+
+# Documentation
+<!-- ![Light themed header](./assets/polaris-header-light.svg#gh-light-mode-only)![Dark themed header](./assets/polaris-header-dark.svg#gh-dark-mode-only)
+
+**If you have a Go backend, you (most probably) <i>need</i> polaris - you just don't know it yet.** -->
+
+<div style={{border: '1px solid white', padding: '20px', padding: '10px', width: '70%'}}>
+### Get started with Polaris
+
+New to Polaris? Follow our introductory tutorials to get a feel of the developer experience and the value of Polaris.
+
+- <a href="/polaris/get-started">Set up your development environment</a>
+- <a href="/polaris/usage">Create your first workflow</a>
+</div>
+<br/>
+<div style={{border: '1px solid white', padding: '20px', padding: '10px', width: '70%'}}>
+### Add Polaris with your existing Go app
+
+- <a href="/polaris/concepts/polaris">Dive into Polaris concepts</a>
+- <a href="/polaris/usage">Integrate Polaris</a>
+</div>