SOW Analyzer – Teams Bot Application

This document provides full technical documentation for the SOW Analyzer Teams Bot application. It is intended for:

• Engineers maintaining or extending the system
• Security and architecture reviewers
• Operations and platform teams
• Knowledge transfer and onboarding

This document describes:

• Application runtime behavior
• Source code responsibilities (file-by-file)
• Authentication and cross-tenant identity
• Teams message and file upload handling
• Data handling, storage, and retention
• Error cases and operational constraints

—

The SOW Analyzer is a document ingestion and analysis system exposed through Microsoft Teams.

Users interact with the system by uploading a PDF Statement of Work directly into a 1:1 Teams chat with a bot. The system:

1. Validates the uploaded file
2. Downloads the PDF securely
3. Compares the document against known SOW templates
4. Uses Azure OpenAI to generate a structured comparison
5. Returns a summarized analysis to the user

At no point does the system store uploaded SOWs long-term.

—

User uploads PDF in Teams
 → Teams stores file in OneDrive/SharePoint
 → Teams sends attachment metadata to bot
 → Bot validates + downloads file
 → Bot POSTs PDF to analyzer endpoint
 → Analyzer extracts text and compares templates
 → Azure OpenAI produces structured diff
 → Result returned to Teams

• PDF-only uploads
• Personal chat only
• Stateless processing
• No persistence of uploaded documents

—

The bot uses a single-tenant App Registration in the CDW Tenant.

This App Registration:

• Is referenced by Azure Bot Service
• Signs JWT tokens presented to the bot
• Is validated by the Bot Framework Adapter

Required environment variables:

MicrosoftAppId
MicrosoftAppPassword
MicrosoftAppTenantId

The bot will reject any token whose AppId does not match `MicrosoftAppId`.

—

Key configuration:

"bots": [
  {
    "botId": "<MicrosoftAppId>",
    "scopes": ["personal"],
    "supportsFiles": true
  }
]

Teams uploads files to OneDrive or SharePoint, then sends metadata to the bot.

Expected attachment type:

application/vnd.microsoft.teams.file.download.info

The bot does not receive raw bytes directly.

—

Acts as the FastAPI entry point for:

• Teams bot messages
• SOW analysis workflow

• Receives Teams activities
• Delegates processing to `teams_messages()`
• No business logic lives here

• Accepts multipart/form-data
• Expects field name: `file`
• Reads PDF bytes into memory
• Executes SOW analysis pipeline
• Returns structured JSON

• No disk writes
• No blob uploads
• File exists only in memory

—

Implements all Teams bot logic.

• Bot Framework authentication
• Activity validation
• File validation and download
• Integration with analyzer
• User-facing messaging

BotFrameworkAdapterSettings(
  MicrosoftAppId,
  MicrosoftAppPassword,
  channel_auth_tenant=MicrosoftAppTenantId
)

This enforces:

• Single-tenant authentication
• Cross-tenant correctness

1. Trust incoming service URL 2. Ignore non-message activities 3. Extract attachments 4. If no attachment → return silently 5. Extract filename + download URL 6. Enforce `.pdf` extension 7. Download file bytes 8. Validate PDF magic bytes (`%PDF`) 9. POST file to analyzer 10. Format and send result

Two layers:

• Filename check
• Byte-level PDF header check

Maximum allowed size enforced before analysis.

• File exists only as a Python byte array
• Eligible for garbage collection after request

—

Performs AI-driven comparison between uploaded SOW and known templates.

• Load templates
• Construct structured prompt
• Call Azure OpenAI
• Parse JSON response
• Normalize output fields

{
  "chosen_template_title": "string",
  "summary": "string",
  "missing_sections": [],
  "extra_sections": [],
  "changed_clauses": {}
}

• No fine-tuning
• No training on customer data
• Prompt-only inference

—

Provides access to stored SOW templates.

• Azure Blob Storage
• Read-only access

• Only templates are stored
• Uploaded SOWs are never written here

—

• Stored in memory only
• Lifetime limited to request scope
• Never written to disk or blob

• Teams stores original file in OneDrive/SharePoint
• Retention governed by M365 policies

• File contents never logged
• Metadata only (filename, size, correlation id)

—

• Logged without sensitive data
• Returned as generic user messages

—

• Bot Framework JWT validation
• AppId + TenantId enforcement

• Teams-scoped access
• Optional user allow-listing via AAD object ID

• No persistent storage
• No request body logging
• No file caching

—

• Azure App Service
• Environment variable configuration
• No startup jobs or migrations

• Stateless
• Horizontal scale-out supported

• Application Insights optional
• Sensitive logging disabled

—

• Personal chat only
• PDF files only
• Channel uploads not supported
• No user authentication beyond Teams identity

—

The system:

• Does not store customer documents
• Minimizes data exposure
• Uses Azure-native security boundaries
• Aligns with enterprise data governance practices

—

Future enhancements may include:

• Channel support via Graph
• Adaptive Card responses
• Template versioning
• Per-user access controls