Merge pull request #1 from S-Nakib/develop

Some doc and basic-communication tutorial is added.

Author: OpenTransitLab

documentation/.gitignore

@@ -0,0 +1 @@
+_site/

documentation/docfx.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "OpenTransit",
+      "_appTitle": "OpenTransit",
+      "_appLogoPath": "images/logo.svg",
+      "_appFooter": "<footer></footer>",
+      "_enableSearch": true,
+      "pdf": true
+    }
+  }
+}

documentation/docs/concepts/generic-broker.md

@@ -0,0 +1,55 @@
+
+The generic broker concept is an abstraction of all the Broker supported by Masstransit. It contains all the common features of all the supported brokers. 
+
+# Common Broker Features
+
+Different message brokers provide different capabilities, but if you look at the most popular ones—RabbitMQ, Azure Service Bus, ActiveMQ, and Amazon SQS—you’ll notice a shared set of core features.  
+In practice, these common features cover the majority of real-world use cases.
+
+For example:
+
+- All of them offer a **Publish Endpoint** where messages can be published.  
+  - RabbitMQ calls this an **Exchange**.  
+  - Azure Service Bus, ActiveMQ, and Amazon SQS call it a **Topic**.
+
+- All of them provide a **Receive Endpoint**, typically referred to as a **Queue**, where consumers subscribe.
+
+Producers publish messages to Publish Endpoints, and Consumers subscribe to Receive Endpoints.
+
+Most brokers also allow you to configure **routing** between Publish Endpoints and Receive Endpoints.  
+This means that when a message arrives at a Publish Endpoint, the broker forwards it to one or more Receive Endpoints based on the defined routing configuration.  
+(You can still send messages directly to the ReceiveEndpoint if needed.)
+
+These behaviors are consistent across brokers.
+
+
+
+# The Generic Broker Concept
+
+OpenTransit takes advantage of these shared capabilities by introducing a **Generic Broker**—an abstraction that represents the common behavior of message brokers.  
+You configure your topology against this Generic Broker, and OpenTransit translates that configuration into the appropriate broker-specific topology under the hood.
+
+This abstraction is the foundation of the Generic Broker concept.
+
+
+## Generic Broker Terminologies
+
+A Generic Broker defines two types of endpoints:
+
+- **Publish Endpoints**  
+- **Receive Endpoints**
+
+You can create and configure the routing between PublishEndpoint to the ReceiveEndpoint based on Message Types.
+
+- Messages are generally **published** to a Publish Endpoint.  
+- Consumers **subscribe** to Receive Endpoints.  
+- Messages may also be sent **directly** to a Receive Endpoint if needed.
+
+You can define **routing mappings** between endpoints—specifying which Receive Endpoint(s) should receive messages published to a given Publish Endpoint.
+
+In the [Basic Communication Tutorial](../tutorials/basic-communication.md) we have seen how Message types is used to Create and Configure Create Endpoints and Receive Endpoints. 
+
+> [!NOTE]
+> Some concepts in this documentation are still evolving. Details on how the Generic Broker constructs the underlying topology for different message types will be added in a future update.
+
+

documentation/docs/concepts/toc.yml

@@ -0,0 +1,5 @@
+
+- name: Generic Broker
+  href: generic-broker.md
+- name: Topology
+  href: topology.md

documentation/docs/concepts/topology.md

@@ -0,0 +1,100 @@
+The term Topology is used in many context and have different meaning in different context. 
+
+However, in distributed system, it is generally used in two Contexts. They are, 
+1. Broker
+2. Architectural pattern. 
+
+In the context of a **broker**, it means the broker’s internal routing configuration i.e. the route mapping between the Publish Endpoint(i.e. Topics, Exchanges, etc) to Receive Endpoint(i.e Queues). 
+
+In the context of **Architectural patterns**, the Producers, Consumers and the Broker consists of the Topology. 
+
+Opentransit’s Definition is sort of a combination of the both cause opentransit helps you not only to Configure the Broker internally, but also helps to interact with it(i.e to Produce, consume, etc). 
+
+So in OpenTransit, **Topology is the broker’s internal configuration, and also the Configuration of how the Application (via OpenTransit) interacts with the broker.**
+
+However, when we want to mean only in broker's context, we will use the term 'Broker's Underlying Topology' throughout the doc. 
+
+
+
+## Configuring the Topology:
+So we now know what a topology is. Now we will know how to Configure the topology. 
+
+From the definition, Configuring topology may mean Configuring both of the following things, 
+
+- Configuring the broker’s internal configuration like Publishendpoints(topic, exchange), Receive Endpoints(i.e. queue),  routing, etc. 
+- Configuring how OpenTransit interacts with the broker. 
+
+OpenTransit defines topology via the Message type 
+
+### Message Types as First-class citizens:
+You have already seen in the [tutorial](../tutorials/basic-communication) how Message Types (classes, records, or interfaces) are used when Configuring the broker, and how Producers and Consumers interact with the PublishEndpoint and ReceiveEndpoint depending on the Message Type. 
+It gives a strongly typed facility that you wouldn’t have found if you were to use the raw .NET Client of the broker. 
+It also abstracts away the details of topology from the Broker interaction point of view and provides a Method call-like syntax and hides the detail of broker Communication. 
+
+However, OpenTransit is flexible enough to provide lower level API’s if we want a lower level interaction.
+
+OpenTransit provides two ways to define the broker topology.
+
+- Broker Agnostic way(Common for any broker)
+- Broker Specific way(features provided by the broker, for example, routing key by RabbitMQ)(give an example link)
+
+
+## Broker agnostic Way:
+We can define both the Broker’s internal Configuraiton and OpenTransit’s Interaction in a Broker agnostic way. 
+
+In the [tutorial](../tutorials/basic-communication.md), the topology is defined in a broker agnostic way. 
+
+One of the most powerful feature of OpenTransit is the way it abstracts away the detail of a broker. 
+We can use an underlying broker without knowing the intrinsic details. 
+
+How Masstransit defines the abstraction and what are the benefits is discussed in the [Generic Broker](generic-broker.md).
+
+The abstraction provides many benefits and most of the time it provides the feature we needs so we should choose the Broker agnostic configuration whenever possible. 
+
+
+## Broker Specific Way:
+Though broker agnostic configuration is recommended, however, in some scenarios, we may have some special requirements and need to use some special features that is provided by a specific broker. 
+OpenTransit is flexible and provides a way where you can define broker specific features. 
+
+> [!NOTE]
+> We will add tutorials/examples later. 
+
+
+
+
+
+
+### Producer, Consumer, Publish, Subscribe, etc:
+
+You may get confused with the usage of these terms in the doc with the terms used on Producer Consumer or Pub-Sub pattern. 
+
+Well, in OpenTransit, we generally use the terms in our own way which may sometimes not exactly the same as their definition in other contexts. 
+
+For example, 
+
+- Producer Publishes Messages to the PublishEndpoint
+- Producer Sends Messages directly to the ReceiveEndpoint
+- Consumer Subscribes to a Receive Endpoint
+- Consumer Consumes Messages
+
+Here,
+Producer is something that Publishes/Sends Messages to the broker. 
+Consumer is something that Consumes/Subscribes to a ReceiveEndpoint to Consume Messages.  
+
+If two consumer subsribes to the Same ReceiveEndpoint, then only one will get a particular message(Competing Consumer pattern). So in that way it matches the Consumer’s definition of the Producer-Consumer pattern. 
+
+Sometimes the terms Producer and Consumer is used to Describe the Application. 
+For example, the Applicaiton that publishes messages is a Producer Application, the application that Consumes messages is a Consumer. 
+However, an application may be both Producer and Consumer at the same time. 
+
+
+
+
+
+
+
+
+
+
+
+

documentation/docs/documentation.md

@@ -0,0 +1,33 @@
+## Documentation as a First-Class Citizen
+
+At OpenTransit, documentation is a **first-class citizen**. We believe that great software is only as good as its ability to be understood, adopted, and extended. 
+
+That’s why we treat documentation with the same level of importance as the project’s source code — clear, accurate, and helpful documentation is a core part of our mission.
+
+
+## Our Current Focus: Understanding Through Clarity
+
+MassTransit v8 will continue receiving support until the end of 2026. During this period, our primary focus is to build an outstanding documentation experience for OpenTransit.  
+We are actively researching the codebase, exploring real-world use cases, and developing analogies, explanations, and examples that make distributed system concepts easier to understand.  
+
+For example, As part of this effort, we have introduced a concept called the **[Generic Broker](concepts/generic-broker.md)** — an abstraction that captures the common functionalities shared by all message brokers.  
+For each [pattern](why-opentransit#patterns) and other concepts, we will explain the underlying [topology](concepts/topology) using the [Generic Broker](concepts/generic-broker.md) first, and then show how to customize it for each broker’s specific implementation.
+
+Initially, the examples, will be given with **RabbitMQ**, and **Mongodb**. however, we will cover other broker's and db's soon. 
+
+
+Our goal is to create **Understanding Documentation** — content that not only tells you *how* to use the framework, but also helps you truly *grasp* the reasoning and patterns behind it.
+
+## Community Feedback Matters
+
+Because documentation is a first-class citizen, we strongly encourage the community to participate.  
+If any part of the documentation feels unclear, incomplete, confusing, or could simply be improved — **please let us know**.
+
+We welcome:
+
+- Feedback  
+- Suggestions  
+- Requests for clarification  
+- Reports of unclear or hard-to-follow sections  
+
+Your input directly helps us improve OpenTransit for everyone. We’re fully open to community collaboration and want to build documentation that genuinely serves developers at all levels.

documentation/docs/toc.yml

@@ -0,0 +1,9 @@
+
+- name: Documentation
+  href: documentation.md
+- name: Why OpenTransit?
+  href: why-openTransit.md
+- name: Tutorials
+  href: tutorials/toc.yml
+- name: Concepts
+  href: concepts/toc.yml

documentation/docs/tutorials/basic-communication.md

@@ -0,0 +1,143 @@
+
+In this tutorial, we will explore the basics of publishing and consuming messages.
+The source code for this example is available **[here](https://github.com/OpenTransitLab/Tutorials/tree/main/Tutorials.BasicCommunication)**
+
+
+## Introducing the Services
+In this tutorial, we’ll work with three services:
+
+- **Client** – A simple console application that publishes a message to simulate an order arriving from the frontend.
+- **OrderService** – Handles incoming orders. After processing an order, it publishes another message to continue the workflow.
+- **InventoryService** – Listens for order-processing–related messages and handles the inventory side of the workflow.
+
+In this setup:
+- The **Client** acts as a **Producer** — it only publishes messages.  
+- The **InventoryService** acts as a **Consumer** — it only receives messages.  
+- The **OrderService** is both a **Producer** and a **Consumer** — it consumes one message and then publishes another.
+
+
+## Explanation
+You need to understand these 5 things to have a basic knowledge of Distributed Communication with OpenTransit. 
+
+1. [Defining Messages](#1-defining-messages)
+2. [How Messages are published](#2-publishing-messages)
+3. [How Messages are Consumed](#3-consuming-a-message)
+4. [How the OpenTransit Setup is done](#4-masstransit-setup) 
+5. [The Topology Created inside the Broker](#5-the-broker-topologyrabbitmq)
+
+
+### 1. Defining Messages
+
+Messages are the means of communication between Services. They can be defined using **classes**, **interfaces**, or **records**.
+
+In this project, we define two messages using C# classes: **SubmitOrder** and **ProcessOrder**.
+
+- The **Client** publishes a **SubmitOrder** message.  
+- The **OrderService** consumes **SubmitOrder**, processes it, and then publishes **ProcessOrder**.  
+- The **InventoryService** consumes **ProcessOrder**.
+
+#### Sharing Message Types Across Projects
+
+When a message is used by multiple applications—such as a producer and a consumer—they **must use the exact same namespace** for the message type.  
+
+For example:
+
+- **SubmitOrder** is used by both Client and OrderService → same namespace required  
+- **ProcessOrder** is used by OrderService and InventoryService → same namespace required
+
+To simplify this, we created a **shared class library** that contains the message definitions. This is the easiest and most maintainable approach.
+
+However, using a shared library is **not mandatory**. Each project may define its own copy of the message class, as long as the **namespace matches exactly**, ensuring that the broker treats them as the same message type.
+
+---
+
+### 2. Publishing Messages
+
+Messages are published by **Producers**. A Producer exposes a `Publish(T message)` method, which is used to send messages to the broker.  
+(We’ll cover Producers in detail later in the documentation.)
+
+In this example, messages are published from two places:
+
+- From the **Client** project’s `Program.cs`  
+[!code-csharp[](code-sample/Client.Program.cs#L25-L33)]
+
+
+- From inside the **SubmitOrderConsumer**
+[!code-csharp[](code-sample/OrderService.SubmitOrderConsumer.cs#L6-L18)]
+
+Both `IBus` and `ConsumeContext<T>` act as Producers, because you can call `Publish(T message)` on either of them.
+
+When publishing inside a [Consumer](#publishing-from-inside-a-consumer), it is **highly recommended** to use the `ConsumeContext<T>` Producer as we have done in the SubmitOrderConsumer. We’ll discuss why in the dedicated Producers section.
+
+When publishing *outside* a Consumer, you can resolve the `IBus` service and publish messages using it like we have done in the **Client** Project's `Program.cs`.
+
+In OpenTransit, the necessary services (such as `IBus`) are registered in `Program.cs`(See the [Setup](#4-masstransit-setup), allowing you to resolve and use them throughout the application.
+
+---
+
+### 3. Consuming a Message:
+
+To consume a message of type `T`, you need to implement `IConsumer<T>`.
+
+In our example, we have two consumers:
+
+- **SubmitOrderConsumer** in the **OrderService**  
+[!code-csharp[](code-sample/OrderService.SubmitOrderConsumer.cs#L6-L18)]
+- **ProcessOrderConsumer** in the **InventoryService**
+[!code-csharp[](code-sample/InventoryService.ProcessOrderConsumer.cs#L6-L13)]
+
+Each consumer must also be registered in the OpenTransit [Setup](#4-masstransit-setup) so the framework knows to create and connect them to the message pipeline.
+
+#### Publishing from inside a Consumer
+
+The `IConsumer<T>` defines a `Consume` method which is called when a message of type `T` is consumed. The method passes a Producer namely `ConsumeContext<T>`, it is highly recommended to use this producer(`ConsumeContext`) when we publish messages from inside the consumer. As you see we have done it in the SubmitOrderConsumer. 
+
+---
+
+
+### 4. MassTransit Setup:
+We configure OpenTransit in the **Service Registration** section of `Program.cs`.  
+In this step, we perform three main tasks:
+
+1. **Register the required services**  
+   Simply call `builder.Services.AddMassTransit()` and it will register everything needed.
+
+2. **Configure the connection to the message broker**
+
+3. **Register the consumers**(if any)
+
+All the above 3 tasks is done onthe `Program.cs` of OrderService
+[!code-csharp[](code-sample/OrderService.Program.cs#L12-L25)]
+
+
+---
+
+### 5. The Broker Topology(RabbitMQ):
+
+This example uses **[broker-agnostic](../concepts/topology#broker-agnostic-way)** configuration, so you don’t need to understand the underlying broker [topology](../concepts/topology) for basic communication.  
+Here, we only used the `UsingRabbitMq` method to provide the Connection Configuration and to configure the [ReceiveEndpoint](../concepts/generic-broker#generic-broker-terminologies)(a generic concept among all the brokers) on the broker. 
+
+Since this Configurations aren't RabbitMQ specific, and you may use any other broker here and, the Message Communication would work fine. 
+
+However, knowing the underlying broker [topology](../concepts/topology) is very helpful when debugging message-routing issues.
+
+In our example, Each Consumer is consuming a single message type. 
+Here, for each MessageType, 2 **Exchanges** and one **Queue** are being created. 
+
+For example, if you open the RabbitMq management plugin, you will see, for the SubmitOrder MessageType, a **Queue** named `SubmitOrder` is bound to the **Exchange** Named `SubmitOrder`. 
+Another **Exchange** named `Shared:SubmitOrder` is created and the `SubmitOrder` **Exchange** is bound to it. (Here, **'Shared'** came from the **Namespace** of the message)
+
+When we publish SubmitOrder messages via a Producer, the message is published to the `Shared:SubmitOrder` exchange, then routed to the SubmitOrder exchange and, then ultimately routed to the SubmitOrder queue. 
+
+
+#### Generic Broker's Perspective
+From the perspective of the [Generic Broker](../concepts/generic-broker), the `Shared:SubmitOrder` **Exchange** is the PublishEndpoint, the `SubmitOrder` **Queue** is the ReceiveEndpoint. 
+The `SubmitOrder` **Exchange** can be seen as an Internal ReceiveEndpoint. However, we haven't added such concept/term in the [Generic Broker](../concepts/generic-broker) yet.  
+
+
+Why the topology is defined that way, what we are gaining, etc, is out of scope of this tutorial. We will have separate sections for it. 
+
+To have a better understanding, you may clone the [project](https://github.com/OpenTransitLab/Tutorials/tree/main/Tutorials.BasicCommunication) and create more message types experimentation.
+
+
+