docs: update docs (#76)

docs/docs/concepts/alert.md

@@ -0,0 +1,6 @@
+# Alert
+
+Alert is being one of the source of notification in Siren. Alert is ingested via ![Alert Webhook](../apis/siren-service-create-alerts.api.mdx) and the webhook is registered to a Monitoring System (e.g. Prometheus, Cortex).
+Once ingested by Siren, alert will be stored as Alert History. Alerts that are being sent by provider will be translated to a `Notification` by `Notification Service`. From this point, the notification is being dispatched by a `Notification Dispatcher` according to the strategy that it took.
+
+The next process could be found under ![Notification](./notification.md).

docs/docs/concepts/notification.md

@@ -1,28 +1,32 @@
 # Notification
 
-Notification is one of main features in Siren. Siren capables to send notification to various receivers (Slack, PagerDuty). Notification in Siren could be sent directly to a receiver or user could subscribe notifications by providing key-value label matchers. For the latter, Siren able to routes notification directly to receivers or to specific receivers by matching notification key-value labels with the provided label matchers.
+Notification is the main feature in Siren. Siren capables to send notification to various receivers (Slack, PagerDuty). Notification in Siren could be sent directly to a receiver or user could subscribe notifications by providing key-value label matchers. For the latter, Siren able to routes notification directly to receivers or to specific receivers by matching notification key-value labels with the provided label matchers.
 
 Sending bulk notifications is also supported in Siren. But this mode is only supporting subscription-based routing.
 
 Below is how the notification is implemented in Siren
 
 ![Notification in Siren](../../static/img/siren_notification.svg)
 
-There are multiple entry points in Siren: 
-- Alerts webhook API
-    - Use by provider to send alerts
-- `POST /notifications` API
+Apart from ![Alert Webhook](./alert.md), there are another entry points in Siren:
+- ![POST /notifications API](../apis/siren-service-post-notification.api.mdx)
     - To send a single notification through receiver based routing or subscription based routing
-- `POST /bulk-notifications` API
+- ![POST /bulk-notifications API](../apis/siren-service-post-bulk-notifications.api.mdx)
     - To send bulk notifications through subscription based routing
 
-Alerts that are being sent by provider will be translated to a `Notification` by `Notification Service`. From this point, the notification is being dispatched by a `Notification Dispatcher` according to the strategy that it took (Bulk or Single Notification).
+From this point, the notification is being dispatched by a `Notification Dispatcher` according to the strategy that it took (Bulk or Single Notification).
 
-For bulk notifications, notifications are evaluated by the subscription and meta messages will be generated. The generated meta messages could be grouped by a certain configuration. At the end, the messages will be enqueued and handled to be sent to the external notification services (e.g. Slack, Pagerduty, etc).
+The dispatched notification will be evaluated based on the routing strategy too. If it is receiver based routing, the notification will be routed to the receiver. If it is subscription based routing, the notification will be evaluated by the subscription matcher.
+
+Post this process, the `Meta Messages` will be generated. The generated meta messages could be reduced or grouped by a certain configuration. At the end, the meta messages will be rendered and this process produces the ![Notification Message](#notification-message) that will be enqueued and handled to be sent to the external notification services (e.g. Slack, Pagerduty, etc).
+
+## Notification Meta Message
+During dispatching Notification, the routed Notification will generate some `Meta Messages` from a single Notification. This is non-rendered version and the prototype of a ![Notification Message](#notification-message).
+This model is useful for Siren to manipulate the meta messages like grouping or other transformation within the `Reducer` step.
 
 ## Notification Message
 
-Each receiver might expect different payload. User needs to pass notification message payload in the same format as what receiver (notification vendor, e.g. slack, pagerduty, etc) expected. All message payload contracts could be found under [receivers](../receivers/slack.md).
+This is the rendered version of a ![Notification Meta Message](#notification-meta-message). In this state, the message would contain all information in the format that the receiver recognize or support. Each receiver might expect different payload. User needs to pass notification message payload in the same format as what receiver (notification vendor, e.g. slack, pagerduty, etc) expected. All message payload contracts could be found under [receivers](../receivers/slack.md).
 
 ### Templating Notification Message Payload
 

docs/docs/concepts/overview.md

@@ -2,17 +2,21 @@
 
 The following contains all the details about architecture and other technical concepts of Siren.
 
-Siren depends on monitoring and alerting provider for rule and alert creation. Sire also expects provider to send alerts to a Siren webhook API and Siren manages the notification routing and publication as well as storing the alerts history.
+Siren could help managing rules of a monitoring and alerting provider and dispatching alerts to a certain destination. This could be possible since Siren expect a provider to send alerts to a Siren webhook API and Siren manages the notification routing and publication as well as storing the alerts history.
 
 ## Features
 
 _**Alerting Rules**_
 
 Siren capables to manage alerting rules for various monitoring providers.
 
-_**Notification**_
+_**Alert Notification**_
 
-Siren capables to subscribe to triggered alerts and send notifications. It also capable to send an on-demand notification.
+Siren capables to subscribe to triggered alerts and send notifications to certain destinations.
+
+_**Event Notification**_
+
+Siren also capables to accept notificaton messages in its API and send and route notifications.
 
 _**GRPC and HTTP API**_
 
@@ -28,27 +32,45 @@ Siren CLI provides easy to use commands to perform various actions. Currently, t
 
 Let's have a look at the major components:
 
-- **Provider:** is a service/platform that does monitoring, observability, and alerting (Cortex, Influx). Provider is expected to send alerts information to siren via siren's webhook API everytime alerts are triggered. Siren does alerting rules management and synchronize the rules with the provider.
+### **Provider**
+
+A service/platform that does monitoring, observability, and alerting (Cortex, Influx). Provider is expected to send alerts information to siren via siren's ![Webhook API](../apis/siren-service-create-alerts.api.mdx) everytime alerts are triggered. Siren does alerting rules management and synchronize the rules with the provider.
 
-- **Upstream Services:** are services that sends observability metrics (via telegraf, prometheus-exporter, open-telemetry) to a monitoring & alerting provider (Cortex, Influx). A provider will trigger an alert if the incoming metrics meet certain rules.
+### **Upstream Services** 
 
-- **Notification Vendor:** is a service/platform that has capability to send notification (e.g. PagerDuty, Slack, etc). Siren has capability to store a specific notification vendor information and credentials, Siren calls it `receiver`. Siren ables to send notification to receivers.
+These are services that sends observability metrics (via telegraf, prometheus-exporter, open-telemetry) to a monitoring & alerting provider (Cortex, Influx). A provider will trigger an alert if the incoming metrics meet certain rules.
 
-### Siren Architecture
+### **Notification Vendor** 
+
+A service/platform that has capability to send notification (e.g. PagerDuty, Slack, etc). Siren has capability to store a specific notification vendor information and credentials, Siren calls it `receiver`. Siren ables to send notification to receivers.
+
+## Siren Detailed Architecture
 
 ![Siren Detailed Architecture](../../static/img/siren_detailed_architecture.svg)
 
-- **Server:** is a main component in Siren that exposes GRPC & HTTP API within the same port. Client interacts with Siren ecosystem through Server. Server talks to a provider e.g. Cortex and DB to configure alerting rules using stored templates and configure alertmanager per tenant with the stored credentials per team.
+### **Server** 
+
+A main component in Siren that exposes GRPC & HTTP API within the same port. Client interacts with Siren ecosystem through Server. Server talks to a provider e.g. Cortex and DB to configure alerting rules using stored templates and configure alertmanager per tenant with the stored credentials per team.
 
-- **PostgreSQL:** is a main storage of Siren. Secret information is stored encrypted in the DB. [Notification](../guides/notification.md) in Siren requires a Queue and for current version Siren uses PostgreSQL as a queue. Siren maintains two schemas in the PostgreSQL, `public` and `notification`. Siren uses `public` schema as its main storage to store all data (e.g. templates, rules, receivers) except notification messages. Notification messages are stored in `notification` schema and handled as a queue in PostgreSQL.
+### **PostgreSQL**
 
-- **Workers:** are another instances in Siren that run detached (although possibly to run within the server too) from the server. Notification handler and dlq handler are workers that run with short period to dequeue notification messages and publish the messages to the notification vendors (e.g. slack, PagerDuty, etc)
+A main storage of Siren. Secret information is stored encrypted in the DB. [Notification](../guides/notification.md) in Siren requires a Queue and for current version Siren uses PostgreSQL as a queue. Siren maintains two schemas in the PostgreSQL, `public` and `notification`. Siren uses `public` schema as its main storage to store all data (e.g. templates, rules, receivers) except notification messages. Notification messages are stored in `notification` schema and handled as a queue in PostgreSQL.
 
-- **Job:** is a task in Siren that could be executed and stopped once the task is done. The Job is usually run as a CronJob to be executed on a specified time.
+
+### **Workers** 
+
+Another instances in Siren that run detached (although possibly to run within the server too) from the server. Notification handler and dlq handler are workers that run with short period to dequeue notification messages and publish the messages to the notification vendors (e.g. slack, PagerDuty, etc)
+
+### **Job** 
+
+Atask in Siren that could be executed and stopped once the task is done. The Job is usually run as a CronJob to be executed on a specified time.
 
 ### Provider: Cortex
 
-- **Cortex Ruler:** is a microservice of Cortex responsible to handle alerting rules. The configured rules are stored in Cortex Ruler. Siren Rules HTTP APIs call Cortex ruler to create/update/delete rule group in a particular namespace. You can create a [provider](../guides/provider_and_namespace.md) for that purpose and provide appropriate hostname.
+#### **Cortex Ruler**
+A microservice of Cortex responsible to handle alerting rules. The configured rules are stored in Cortex Ruler. Siren Rules HTTP APIs call Cortex ruler to create/update/delete rule group in a particular namespace. You can create a [provider](../guides/provider_and_namespace.md) for that purpose and provide appropriate hostname.
+
+#### **Cortex Alertmanager** 
 
-- **Cortex Alertmanager:** is a microservice of Cortex responsible to handle alerting notification. Cortex sets up alert history webhook receiver to capture triggered alert history. Cortex Alertmanger hostname is fetched from [provider's](../guides/provider_and_namespace.md) host key.
+A microservice of Cortex responsible to handle alerting notification. Cortex sets up alert history webhook receiver to capture triggered alert history. Cortex Alertmanger hostname is fetched from [provider's](../guides/provider_and_namespace.md) host key.
 

docs/docs/concepts/receiver.md

@@ -0,0 +1,26 @@
+# Receiver
+
+## Parent vs Child Receiver
+
+In Siren, one receiver could depends to other receiver and inherit its configuration. However it only supports one level parent-child relation.The receiver that depends on other receiver is called a `Child Receiver` but the receiver that other receiver depends on is called a `Parent Receiver`.
+
+There is never an orphan `Child Receiver` in Siren. That means, a `Child Receiver` always has to have a `Parent Receiver`. However, not every receiver could be a `Child Receiver`. Only a specific receiver type that could be a `Child Receiver`. 
+
+Currently the only receiver type that is a `Child Receiver` is:
+- Slack Channel receiver, that depends on Slack receiver
+
+The Slack Channel receiver has config
+```
+{
+    "channel_name": "xxx"
+}
+```
+While the Slack receiver has config
+```
+{
+    "token": "1234",
+    "workspace": "gotocompany"
+}
+```
+
+When rendering a message, if a message is a child receiver, Siren would merge the configs of parent receiver to the child receiver.