fix(docs): add AsyncAPI mapping explanations and improve navigation

Author: huynguyengl99

docs/examples/fastapi.rst

@@ -574,18 +574,22 @@ Production Deployment
 Key considerations for production deployment:
 
 **1. Channel Layer Scaling**
+
 - Use Redis Cluster or RabbitMQ for high-availability channel layers
 - Configure appropriate connection pools and timeouts
 
 **2. Background Job Processing**
+
 - Deploy ARQ workers as separate processes/containers
 - Use Redis Sentinel for worker queue high availability
 
 **3. WebSocket Load Balancing**
+
 - Configure sticky sessions or use Redis for session storage
 - Consider using a WebSocket-aware load balancer
 
 **4. Monitoring and Observability**
+
 - Enable structured logging with correlation IDs
 - Monitor WebSocket connection counts and message rates
 - Set up health checks for both HTTP and WebSocket endpoints

docs/quick-start-django.rst

@@ -265,6 +265,12 @@ Next Steps
 
 Now that you have a working Django WebSocket consumer with Chanx:
 
+**Tutorial:**
+
+* :doc:`tutorial-django/prerequisites` - **Follow the comprehensive Django tutorial** to build a complete real-time application with chat, AI assistants, background tasks, and testing
+
+**Documentation:**
+
 * :doc:`user-guide/consumers-decorators` - Learn more about consumers and decorators
 * :doc:`user-guide/framework-integration` - Explore Django-specific features
 * :doc:`user-guide/asyncapi` - Learn about AsyncAPI documentation generation

docs/quick-start-fastapi.rst

@@ -271,6 +271,12 @@ Next Steps
 
 Now that you have a working FastAPI WebSocket consumer with Chanx:
 
+**Tutorial:**
+
+* :doc:`tutorial-fastapi/prerequisites` - **Follow the comprehensive FastAPI tutorial** to build a complete real-time application with system echo, room chat, background jobs, and multi-layer messaging
+
+**Documentation:**
+
 * :doc:`user-guide/consumers-decorators` - Learn more about consumers and decorators
 * :doc:`user-guide/framework-integration` - Explore FastAPI-specific features
 * :doc:`user-guide/asyncapi` - Learn about AsyncAPI documentation generation

docs/tutorial-django/cp1-chat-websocket.rst

@@ -169,6 +169,51 @@ This is the core chat functionality:
 - ``broadcast_message()`` sends the message to all clients in the same group
 - ``exclude_current=True`` means the sender won't receive their own message back
 
+How Message Handlers Send Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Understanding how messages are sent back to clients is important.
+
+**Pattern 1: Return value sends to sender only**
+
+.. code-block:: python
+
+    @ws_handler
+    async def handle_ping(self, message: PingMessage) -> PongMessage:
+        # What you return goes back to the sender only
+        return PongMessage()
+
+The ``handle_ping`` method demonstrates this - it returns ``PongMessage`` which is automatically sent to the client who sent the ping.
+
+**Pattern 2: Broadcasting to multiple users**
+
+.. code-block:: python
+
+    @ws_handler(output_type=NewChatMessage)
+    async def handle_new_chat_message(self, message: NewChatMessage) -> None:
+        # Explicitly broadcast to send to multiple users
+        await self.broadcast_message(message, exclude_current=True)
+
+The ``handle_new_chat_message`` method demonstrates this:
+
+- Return type is ``None`` (not sending directly to sender)
+- Use ``output_type`` parameter in ``@ws_handler`` for API documentation
+- Call ``broadcast_message()`` explicitly to send to all group members
+- ``exclude_current=True`` means the sender won't receive their own message
+
+.. note::
+
+   You'll see more advanced messaging patterns, including server-to-server communication with event handlers, in Part 4.
+
+AsyncAPI Documentation Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@ws_handler`` decorator generates AsyncAPI **RECEIVE** actions (documenting what messages clients can send). When handlers have a return type or ``output_type`` parameter, the RECEIVE action includes a **reply field** describing the response message.
+
+.. seealso::
+
+   For detailed information about AsyncAPI mapping, see :doc:`../user-guide/consumers-decorators` → AsyncAPI Documentation Mapping section.
+
 Step 3: Create WebSocket Routing
 ---------------------------------
 

docs/tutorial-django/cp3-system-websocket.rst

@@ -463,6 +463,102 @@ The ``@event_handler`` decorator marks this method as a channel layer event hand
 
 Similarly for ``handle_system_notification`` - handles broadcast notifications.
 
+Understanding Event Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the first time we're using ``@event_handler``, so let's understand what it does and how it differs from ``@ws_handler``.
+
+**@ws_handler vs @event_handler:**
+
+.. code-block:: python
+
+    # Receives messages from WebSocket clients
+    @ws_handler
+    async def handle_user_message(self, message: UserMessage) -> Response:
+        ...
+
+    # Receives messages from channel layer (server-to-server)
+    @event_handler
+    async def handle_job_result(self, event: JobResult) -> Response:
+        ...
+
+**Key differences:**
+
++------------------+------------------------------------+--------------------------------------------+
+|                  | @ws_handler                        | @event_handler                             |
++==================+====================================+============================================+
+| **Source**       | WebSocket clients                  | Channel layer (server-side)                |
++------------------+------------------------------------+--------------------------------------------+
+| **Triggered by** | Client sends JSON message          | ``send_event()`` or ``broadcast_event()``  |
++------------------+------------------------------------+--------------------------------------------+
+| **Use case**     | Handle user interactions           | Handle background job results, external    |
+|                  |                                    | triggers, cross-consumer messages          |
++------------------+------------------------------------+--------------------------------------------+
+
+**How event handlers work:**
+
+**Pattern 1: Return value sends to WebSocket client**
+
+.. code-block:: python
+
+    @event_handler
+    async def handle_job_result(self, event: JobResult) -> JobResult:
+        # What you return is sent to the WebSocket client
+        return event
+
+Where the message goes depends on how the event was sent:
+
+- ``send_event(message, channel_name)`` → goes to **one specific client**
+- ``broadcast_event(message, groups=[...])`` → goes to **all clients in those groups**
+
+In our system example:
+
+.. code-block:: python
+
+    # Celery task sends to specific client
+    SystemConsumer.send_event_sync(JobResult(payload=result), channel_name)
+
+    # Event handler receives it and forwards to that client
+    @event_handler
+    async def handle_job_result(self, event: JobResult) -> JobResult:
+        return event
+
+**Pattern 2: Send multiple messages or complex logic**
+
+.. code-block:: python
+
+    @event_handler(output_type=Notification)
+    async def handle_complex_event(self, event: ComplexEvent) -> None:
+        # Send multiple messages
+        await self.send_message(Notification(payload="Processing..."))
+        await self.send_message(Notification(payload="Complete!"))
+
+When using complex logic:
+
+- Return type is ``None``
+- Use ``output_type`` parameter for API documentation
+- Call ``send_message()`` or ``broadcast_message()`` explicitly
+
+**Why use event handlers?**
+
+Event handlers enable server-to-server communication:
+
+- **Background workers** (Celery) can send results back to WebSocket clients
+- **External scripts** can trigger WebSocket notifications
+- **HTTP endpoints** can push messages to WebSocket connections
+- **Different consumers** can send messages to each other
+
+This is more powerful than ``@ws_handler`` which only handles client messages.
+
+AsyncAPI Documentation Mapping for Event Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@event_handler`` decorator generates AsyncAPI **SEND** actions (server-initiated messages). Only the output type (message sent to client) is documented. The input event type is NOT documented in AsyncAPI since it comes from internal sources (Celery, management commands, etc.), not from WebSocket clients.
+
+.. seealso::
+
+   For detailed information about AsyncAPI mapping, see :doc:`../user-guide/consumers-decorators` → AsyncAPI Documentation Mapping section.
+
 .. tip::
 
    **Optional: Generic Type Parameter for Better Type Hints**
@@ -497,13 +593,6 @@ Similarly for ``handle_system_notification`` - handles broadcast notifications.
 
    This catches bugs during development before runtime, providing better IDE autocomplete and static analysis. The generic type doesn't affect runtime behavior.
 
-.. important::
-
-   **Key Difference:**
-
-   - ``@ws_handler`` - Handles messages from **WebSocket clients**
-   - ``@event_handler`` - Handles messages from **channel layer** (server-to-server)
-
 Step 6: Create Routing
 ----------------------
 

docs/tutorial-fastapi/cp1-system-echo.rst

@@ -245,6 +245,15 @@ When broadcasting:
 
    You'll see more advanced messaging patterns, including server-to-server communication with event handlers, in Part 3.
 
+AsyncAPI Documentation Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@ws_handler`` decorator generates AsyncAPI **RECEIVE** actions (documenting what messages clients can send). When handlers have a return type or ``output_type`` parameter, the RECEIVE action includes a **reply field** describing the response message.
+
+.. seealso::
+
+   For detailed information about AsyncAPI mapping, see :doc:`../user-guide/consumers-decorators` → AsyncAPI Documentation Mapping section.
+
 Key Concepts Review
 -------------------
 

docs/tutorial-fastapi/cp3-background-jobs.rst

@@ -513,6 +513,15 @@ Event handlers enable server-to-server communication:
 
 This is more powerful than ``@ws_handler`` which only handles client messages.
 
+AsyncAPI Documentation Mapping for Event Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@event_handler`` decorator generates AsyncAPI **SEND** actions (server-initiated messages). Only the output type (message sent to client) is documented. The input event type is NOT documented in AsyncAPI since it comes from internal sources (ARQ workers, HTTP endpoints, etc.), not from WebSocket clients.
+
+.. seealso::
+
+   For detailed information about AsyncAPI mapping, see :doc:`../user-guide/consumers-decorators` → AsyncAPI Documentation Mapping section.
+
 Step 4: Register the WebSocket Route
 -------------------------------------