chore: adds more comprehensive docstrings

Author: bencegadanyi1-nhs

packages/slackBotFunction/app/handler.py

@@ -1,8 +1,9 @@
 """
-Main entry point for the Slack Bot Lambda Function
+Main Lambda handler - dual-purpose function for Slack bot operations
 
-This is the Lambda handler that coordinates all the components, it handles both regular Slack webhooks
-and async processing requests
+This Lambda function serves two purposes:
+1. Handles incoming Slack events (webhooks) via API Gateway
+2. Processes async operations when invoked by itself to avoid timeouts
 """
 
 from slack_bolt.adapter.aws_lambda import SlackRequestHandler
@@ -18,11 +19,12 @@
 
 def handler(event: dict, context: LambdaContext) -> dict:
     """
-    Main Lambda handler - handles Slack webhooks and async processing
+    Main Lambda entry point - routes between Slack webhook and async processing
 
-    Two modes:
-    1. Slack webhook -> acknowledge quickly, trigger async processing
-    2. Async processing -> handle the conversation (query Bedrock, respond)
+    Flow:
+    1. Slack sends webhook -> API Gateway -> Lambda (sync, 3s timeout)
+    2. Lambda acknowledges immediately and triggers async self-invocation
+    3. Async invocation processes Bedrock query and responds to Slack
     """
     logger.info("Lambda invoked", extra={"is_async": event.get("async_processing", False)})
 

packages/slackBotFunction/app/slack/slack_events.py

@@ -21,8 +21,10 @@
 
 def process_async_slack_event(slack_event_data):
     """
-    Process the actual Slack event
-    Gets called asynchronously to avoid Lambda timeouts
+    Process Slack events asynchronously after initial acknowledgment
+
+    This function handles the actual AI processing that takes longer than Slack's
+    3-second timeout. It extracts the user query, calls Bedrock, and posts the response.
     """
     event = slack_event_data["event"]
     event_id = slack_event_data["event_id"]
@@ -132,13 +134,16 @@ def store_conversation_session(conversation_key, session_id, user_id, channel_id
 
 def query_bedrock(user_query, session_id=None):
     """
-    Query Bedrock knowledge base with optional conversation context
+    Query Amazon Bedrock Knowledge Base using RAG (Retrieval-Augmented Generation)
+
+    This function retrieves relevant documents from the knowledge base and generates
+    a response using the configured LLM model with guardrails for safety.
     """
+
     client = boto3.client(
         service_name="bedrock-agent-runtime",
         region_name=AWS_REGION,
     )
-
     request_params = {
         "input": {"text": user_query},
         "retrieveAndGenerateConfiguration": {

packages/slackBotFunction/app/slack/slack_handlers.py

@@ -1,5 +1,5 @@
 """
-Slack event handlers - handles @mentions and DMs
+Slack event handlers - handles @mentions and direct messages to the bot
 """
 
 import time
@@ -23,7 +23,8 @@ def log_request(slack_logger, body, next):
     @app.event("app_mention")
     def handle_app_mention(event, ack, body):
         """
-        Handle @mentions in channels
+        Handle @mentions in channels - when users mention the bot in a channel
+        Acknowledges the event immediately and triggers async processing to avoid timeouts
         """
         ack()
 
@@ -40,7 +41,8 @@ def handle_app_mention(event, ack, body):
     @app.event("message")
     def handle_direct_message(event, ack, body):
         """
-        Handle direct messages to the bot
+        Handle direct messages to the bot - private 1:1 conversations
+        Filters out channel messages and processes only direct messages
         """
         ack()
 
@@ -61,7 +63,10 @@ def handle_direct_message(event, ack, body):
 
 def is_duplicate_event(event_id):
     """
-    Check if we've already processed this event
+    Check if we've already processed this event using DynamoDB conditional writes
+
+    Slack may send duplicate events due to retries, so we use DynamoDB's
+    conditional write to atomically check and record event processing.
     """
     try:
         ttl = int(time.time()) + 3600  # 1 hour TTL
@@ -78,7 +83,13 @@ def is_duplicate_event(event_id):
 
 
 def trigger_async_processing(event_data):
-    """Fire off async processing to avoid timeout."""
+    """
+    Trigger asynchronous Lambda invocation to process Slack events
+
+    Slack requires responses within 3 seconds, but Bedrock queries can take longer.
+    This function invokes the same Lambda function asynchronously to handle the
+    actual AI processing without blocking the initial Slack response.
+    """
     # incase we fail to re-invoke the lambda we should log an error
     try:
         lambda_client = boto3.client("lambda")