perfectthymetech/m365-custom-agent

1. Repository shape

- This is a three-part repo: code/copilot contains the runtime service, code/infra contains Azure Terraform, and docs/ contains deployment and setup guidance. code/teams/manifest.json is the Teams app packaging boundary.

2. Primary runtime

- The application is a Python FastAPI backend (code/copilot/app/main.py) packaged with uv/Poetry-style dependency management and run in a container (Dockerfile). The README positions it as the reference implementation for the Microsoft 365 Agents SDK.

3. HTTP API boundary

- The explicit API surface is versioned under app/api/v1/, with endpoints for:

- heartbeat for service health/readiness

- messages for conversational interaction

- This suggests the service exposes a lightweight REST layer in front of the agent/coprocessing logic.

4. Agent orchestration layer

- app/agents/ contains reusable agent behaviors: root, document, summarizer, and actions.

- These are the main business-logic units that likely decide how a request is interpreted, whether a document-oriented workflow is needed, and how results are summarized or actioned.

5. Microsoft 365 Agents SDK / channel integration

- The app/copilot/ package is the channel and SDK integration layer.

- It includes:

- channel-specific handlers for Microsoft Teams and web chat

- activity adapters for those channels

- shared copilot configuration, scenario routing, and common abstractions

- handler_abstract.py and the concrete channel handlers indicate a polymorphic boundary between inbound activities and agent execution.

6. Scenario-driven behavior

- The presence of app/copilot/scenarios.py, code/schemas/scenarios.schema.json, and docs/SCENARIO_DEFINITIONS.yaml shows the app is not a single-purpose bot; it is driven by configurable scenarios.

- That configuration boundary likely maps user messages to predefined workflows, prompts, or tool-use patterns.

7. Document and attachment pipeline

- app/files/compression.py and app/files/extraction.py, plus app/models/attachments.py, indicate the service can accept and process files.

- This is an important subsystem boundary: inbound messages may carry attachments, which are then compressed/extracted before being handed to document-centric agents.

8. Domain models

- app/models/ defines contracts for the service’s core entities: agents, copilot state, heartbeat, scenarios, and attachments.

- These models likely sit between the API layer, the agent layer, and the channel adapters, providing typed data exchange within the app.

9. Configuration, logging, and runtime settings

- app/core/settings.py, app/copilot/configuration.py, and app/logs.py centralize environment-driven settings and observability setup.

- The README calls out logging/monitoring via OpenTelemetry, so telemetry is a first-class cross-cutting concern rather than an afterthought.

10. Azure infrastructure footprint

- code/infra/ defines the deployment target and dependencies:

- Azure Web App for Linux for hosting the backend

- App Service Plan

- Bot Service for channel connectivity

- Cosmos DB for persistent state/data

- Storage Account for files or artifacts

- Key Vault for secrets

- Azure OpenAI and Document Intelligence as external AI/document services

- Application Insights for telemetry

- Managed Identity and role assignments for secure resource access

- The network and DNS Terraform files show the stack is designed for controlled Azure networking, not a simple public-only deployment.

11. Deployment and environment separation

- There are two Terraform layers:

- docs/prereqs/ for shared prerequisite infrastructure

- code/infra/ for the application environment itself

- config/PerfectThymeTech/*.tfvars suggests named environment configuration, and the GitHub Actions workflows indicate automated linting, Terraform, and webapp deployment pipelines.

12. Teams packaging

- code/teams/manifest.json is the distribution boundary for Microsoft Teams installation.

- Combined with the bot service and Teams handler code, this repo supports a Teams-connected agent rather than just a standalone API.

13. Test and quality boundary

- code/copilot/tests/ and the top-level CI files indicate the service has automated validation around the app layer, while pre-commit and lint workflows enforce code quality before deployment.

14. How data moves through the system

- A user message arrives from Teams or web chat, is normalized by the channel handler/activity layer, routed through scenario/agent logic, may invoke file extraction or document workflows, and then returns a response through the same channel boundary.

- Separately, direct API calls can hit the FastAPI endpoints for health checks or message handling.

15. What to draw in an architecture diagram

- The key boxes are: client channels (Teams/web chat), bot/channel adapter layer, FastAPI service, agent/scenario orchestration, file-processing subsystem, and Azure dependencies (OpenAI, Document Intelligence, Cosmos DB, Storage, Key Vault, App Insights).

- The main trust boundaries are external channels, the API service, and the Azure resource boundary enforced by managed identity and secrets in Key Vault.