adds section to articulate the topic

docs/pages/_section.md

@@ -0,0 +1,4 @@
+---
+title: Glee
+weight: 10
+---

docs/pages/index.md

@@ -1,42 +1,21 @@
 ---
-title: 'Installation guide'
-weight: 30
+title: Getting Started
+weight: 80
 ---
 
-## Glee Installation
+## Introduction
 
-Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system.
+[Glee](https://github.com/asyncapi/glee) is a spec-first framework that helps you build server-side applications. That means it operates on the principle of defining the API specification (AsyncAPI) before diving into the actual implementation of the application logic. It leverages that principle to make you more productive:
 
-### Automatic Installation
+- Glee ensures your code and AsyncAPI definition are on par, eliminating the problem of outdated documentation. By having both the code and the AsyncAPI definition in sync, you can ensure that the API documentation is always up to date, accurate, and reflects the current state of the application. Glee takes care of this automatically for you.
+- Glee lets you focus on what matters and handles the rest for you. You only write the code for your business use-case. Glee takes care of performance, scalability, resilience, and everything you need to make your application production-ready.
+- Glee validates the schema of the payload that it receives, if it doesn't conform to the schema that is defined in the AsyncAPI document, it throw an error telling user that the server received an invalid payload.
 
-The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. 
-To create a project, run:
+Now, before you get started with a glee project, let's take a high level view of Application structure what glee resonates with.
 
-```sh
-asyncapi new glee
-```
-
-> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
-
-On installation, you'll find next steps after your project created:
-
-```
-Your project "project" has been created successfully!
-
-Next steps:
-
-  cd project
-  npm install
-  npm run dev
-
-Also, you can already open the project in your favorite editor and start tweaking it
-```
-
-While making twists to your application, you can follow along with our getting started guide on the relevant page.
+## Application structure
 
-### Manual Installation
-
-To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below;
+Glee expects your project to have some files and folders with special names. When you run `asyncapi new glee`, [AsyncAPI CLI](https://github.com/asyncapi/cli) generates a boilerplate application structure by creating a new folder and populating an initial set of files as shown below. You can continue working in this default structure, adding new components, as described throughout the documentation of asyncapi cli.
 
 ```
 ├─ functions          (required)
@@ -51,84 +30,130 @@ To manually create a new app, create a new folder e.g. `myapp` so the folder str
 ├─ package.json       (required)
 ```
 
-Install the required packages inside a new folder:
+|File/Directory|Description|
+|---|---|
+|functions|**Required.** This directory contains all the functions that Glee must execute when it receives a message from the server. Each file must export a default async function.
+|lifecycle|This directory contains application lifecycle functions. These functions will be executed when certain events happen in the application. E.g., `onConnect`, `onServerReady`, `onDisconnect`, etc.
+|.env|The environment variables of your application. **DO NOT PUT SECRETS HERE**.
+|asyncapi.(yaml or json or yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defines your API. Make sure all the `publish` operations have an assigned `operationId` that matches a file name (excluding the extension) in the `functions` directory.
+|glee.config.js| The Glee configuration file.
+|package.json|**Required.** The Node.js package definition file. Make sure you include `@asyncapi/glee` as a dependency and add two scripts: `dev` and `start`. They should be running `glee dev` and `glee start` respectively.
 
-```js
-npm init -y
-npm install @asyncapi/glee
-```
+To understand the structure in a broader way, please refer to the associated page's links. 
 
-Open your package.json file and add the following scripts:
+### Let's create a glee project to simplify the app structure
 
-```js
-{
-  "scripts": {
-    "docs": "glee docs",
-    "dev": "glee dev",
-    "start": "glee start",
-  }
-}
-```
+We will consider a simple WebSocket API using glee to understand its magic. We will create a simple WebSocket server that receives a current time from the client and then send a "good morning", "good evening" or "good night" respectively.
 
-These scripts refer to the different stages of developing an application.
+To setup a project, you should follow our installation page on how to setup glee on your environment.
 
-- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions.
+We recommend creating a new Glee app using our official CLI which sets up everything automatically. (You don't need to create an empty directory. create-glee-app will make one for you.) To create a project, run: `asyncapi new glee`
 
-- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks.
+Once the process is completed, you should have a new Glee app ready for development and see these files that were made.
 
-- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance.
+![glee_structure](glee_struct.png)
 
-#### Creating `asyncapi.yaml` file and other required directories
+#### Define our Spec for our API
 
-Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name  as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel.
+Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API:
 
 ```yaml
 asyncapi: 3.0.0
 info:
-  title: 'Hello, Glee!'
+  title: Greet Bot
   version: 1.0.0
 servers:
   websockets:
     host: 0.0.0.0:3000
     protocol: ws
 channels:
-  hello:
-    address: hello
+  greet:
+    address: greet
+    messages:
+      greet:
+        $ref: '#/components/messages/greet'
+      time:
+        $ref: '#/components/messages/time'
+  time:
+    address: time
     messages:
-      hello:
-        $ref: '#/components/messages/hello'
+      time:
+        $ref: '#/components/messages/time'
 operations:
-  onHello:
+  onGreet:
     action: receive
     channel:
-      $ref: '#/channels/hello'
+      $ref: '#/channels/greet'
     reply:
       channel:
-        $ref: "#/channels/hello"
-  SendHello:
+        $ref: '#/channels/greet'
+  sendGreet:
     action: send
-    channel: 
-      $ref: "#/channels/hello"
+    channel:
+      $ref: '#/channels/time'
 components:
   messages:
-    hello:
+    time:
+      payload:
+        type: object
+        properties:
+          currentTime:
+            type: number
+          name:
+            type: string
+    greet:
       payload:
         type: string
+
 ```
 
-Create an operation function `onHello.js` inside `myapp/functions`:
+This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly.
+
+One thing to note here is the `operations` item, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `onGreet` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel receives a message, `onGreet` function is called.
 
-```js
-export default async function (event) {  
+#### Define our operation function
+
+Now for our case, we will be adding a file `functions/onGreet.js` and writing up the logic for parsing our time and sending a response.
+
+```javascript
+export default async function (event) {
+  const { name, time } = event.payload
+  const t = new Date(time)
+  const curHr = t.getHours()
+  let response = ''
+  if (curHr < 12) {
+    response = `Good Morning ${name}`
+  } else if (curHr < 18) {
+    response = `Good Afternoon ${name}`
+  } else {
+    response = `Good Evening ${name}`
+  }
   return {
-    reply: [{
-      payload: `Hello from Glee! You said: "${event.payload}".`
-    }]
+    reply: [
+      {
+        payload: response,
+      },
+    ],
   }
 }
+
+```
+
+Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details.
+
+#### Running and testing your application
+
+We will not execute the application and carry out testing with Postman to ensure that it is functioning as intended.
+
+Now to execute your glee application, just run:
+
+```
+npm run dev
+# or 
+npm run start
 ```
+To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint:
 
-#### Run the Development Server
+![glee_response](glee_resp.png)
 
-- Run `npm run dev` to start the development server.
-- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"}
+So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot).

docs/pages/installation.md

@@ -0,0 +1,134 @@
+---
+title: 'Installation guide'
+weight: 30
+---
+
+## Glee Installation
+
+Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system.
+
+### Automatic Installation
+
+The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. 
+To create a project, run:
+
+```sh
+asyncapi new glee
+```
+
+> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
+
+On installation, you'll find next steps after your project created:
+
+```
+Your project "project" has been created successfully!
+
+Next steps:
+
+  cd project
+  npm install
+  npm run dev
+
+Also, you can already open the project in your favorite editor and start tweaking it
+```
+
+While making twists to your application, you can follow along with our getting started guide on the relevant page.
+
+### Manual Installation
+
+To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below;
+
+```
+├─ functions          (required)
+│  ├─ onHello.js
+│  └─ ...
+├─ lifecycle          (optional)
+│  ├─ onConnect.js
+│  └─ ...
+├─ .env               (optional)
+├─ asyncapi.(yaml | yml | json)      (required)
+├─ glee.config.js     (optional)
+├─ package.json       (required)
+```
+
+Install the required packages inside a new folder:
+
+```js
+npm init -y
+npm install @asyncapi/glee
+```
+
+Open your package.json file and add the following scripts:
+
+```js
+{
+  "scripts": {
+    "docs": "glee docs",
+    "dev": "glee dev",
+    "start": "glee start",
+  }
+}
+```
+
+These scripts refer to the different stages of developing an application.
+
+- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions.
+
+- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks.
+
+- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance.
+
+#### Creating `asyncapi.yaml` file and other required directories
+
+Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name  as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel.
+
+```yaml
+asyncapi: 3.0.0
+info:
+  title: 'Hello, Glee!'
+  version: 1.0.0
+servers:
+  websockets:
+    host: 0.0.0.0:3000
+    protocol: ws
+channels:
+  hello:
+    address: hello
+    messages:
+      hello:
+        $ref: '#/components/messages/hello'
+operations:
+  onHello:
+    action: receive
+    channel:
+      $ref: '#/channels/hello'
+    reply:
+      channel:
+        $ref: "#/channels/hello"
+  SendHello:
+    action: send
+    channel: 
+      $ref: "#/channels/hello"
+components:
+  messages:
+    hello:
+      payload:
+        type: string
+```
+
+Create an operation function `onHello.js` inside `myapp/functions`:
+
+```js
+export default async function (event) {  
+  return {
+    reply: [{
+      payload: `Hello from Glee! You said: "${event.payload}".`
+    }]
+  }
+}
+```
+
+#### Run the Development Server
+
+- Run `npm run dev` to start the development server.
+- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"}