# perfectthymetech/m365-custom-agent architecture

> Architecture diagram of the GitHub repository perfectthymetech/m365-custom-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/perfectthymetech/m365-custom-agent
- Repository: https://github.com/perfectthymetech/m365-custom-agent

## Overview

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.

Main entry points: [`code/copilot/app/copilot/copilot.py`](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/copilot.py) (Copilot core), [`code/infra/webapplinux.tf`](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/webapplinux.tf) (Web App), [`code/copilot/app/agents/root.py`](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/root.py) (Root agent), [`code/copilot/app/main.py`](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/main.py) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App runtime"]
  node_main["Main<br/>FastAPI entrypoint<br/>[main.py]"]
  node_api["API v1<br/>REST layer<br/>[router.py]"]
  node_heartbeat(("Heartbeat<br/>health endpoint<br/>[heartbeat.py]"))
  node_messages(("Messages<br/>message endpoint<br/>[messages.py]"))
  node_copilot["Copilot core<br/>channel orchestration<br/>[copilot.py]"]
  node_handler["Handler base<br/>adapter contract"]
  node_teams["Teams handler<br/>channel adapter<br/>[handler_msteams.py]"]
  node_webchat["Webchat handler<br/>channel adapter<br/>[handler_webchat.py]"]
  node_scenarios{{"Scenarios<br/>routing rules<br/>[scenarios.py]"}}
  node_root_agent["Root agent<br/>[root.py]"]
  node_doc_agent["Document agent<br/>[document.py]"]
  node_sum_agent["Summarizer<br/>agent<br/>[summarizer.py]"]
  node_actions_agent["Actions<br/>agent<br/>[actions.py]"]
  node_files["File pipeline<br/>attachment processing<br/>[extraction.py]"]
  node_models[("Domain models<br/>data contracts<br/>[copilot.py]")]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_logs["Telemetry<br/>observability<br/>[logs.py]"]
end

subgraph group_infra["Azure infra"]
  node_webapp["Web App<br/>Azure Linux host<br/>[webapplinux.tf]"]
  node_botsvc["Bot Service<br/>Azure channel gateway<br/>[botservice.tf]"]
  node_stores[("Data stores<br/>Cosmos and Storage<br/>[cosmosdb.tf]")]
  node_ai["AI services<br/>Azure OpenAI and DI<br/>[aoai.tf]"]
  node_security["Secrets and identity<br/>Key Vault and MI<br/>[keyvault.tf]"]
  node_monitoring["App Insights<br/>telemetry backend"]
end

subgraph group_docs["Docs and packaging"]
  node_teams_manifest["Teams manifest<br/>package boundary<br/>[manifest.json]"]
  node_scenarios_def["Scenario defs<br/>config schema"]
  node_deploy_docs["Deploy docs<br/>documentation<br/>[README.md]"]
end

node_main -->|"mounts"| node_api
node_main -->|"starts"| node_copilot
node_api -->|"exposes"| node_heartbeat
node_api -->|"exposes"| node_messages
node_messages -->|"dispatches"| node_copilot
node_copilot -->|"uses"| node_handler
node_handler -->|"implements"| node_teams
node_handler -->|"implements"| node_webchat
node_copilot -->|"routes by"| node_scenarios
node_scenarios -->|"selects"| node_root_agent
node_root_agent -->|"delegates"| node_doc_agent
node_root_agent -->|"delegates"| node_sum_agent
node_root_agent -->|"delegates"| node_actions_agent
node_messages -->|"attaches"| node_files
node_files -->|"feeds"| node_doc_agent
node_copilot -->|"shares"| node_models
node_copilot -->|"reads"| node_settings
node_copilot -->|"emits"| node_logs
node_main -->|"deploys to"| node_webapp
node_webapp -->|"connects"| node_botsvc
node_webapp -->|"persists to"| node_stores
node_webapp -->|"calls"| node_ai
node_webapp -->|"auth via"| node_security
node_webapp -->|"reports"| node_monitoring
node_teams_manifest -->|"packages for"| node_botsvc
node_scenarios_def -->|"defines"| node_scenarios
node_deploy_docs -.->|"describes"| node_webapp

click node_main "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/main.py"
click node_api "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/router.py"
click node_heartbeat "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/endpoints/heartbeat.py"
click node_messages "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/endpoints/messages.py"
click node_copilot "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/copilot.py"
click node_handler "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_abstract.py"
click node_teams "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_msteams.py"
click node_webchat "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_webchat.py"
click node_scenarios "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/scenarios.py"
click node_root_agent "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/root.py"
click node_doc_agent "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/document.py"
click node_sum_agent "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/summarizer.py"
click node_actions_agent "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/actions.py"
click node_files "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/files/extraction.py"
click node_models "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/models/copilot.py"
click node_settings "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/core/settings.py"
click node_logs "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/logs.py"
click node_webapp "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/webapplinux.tf"
click node_botsvc "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/botservice.tf"
click node_stores "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/cosmosdb.tf"
click node_ai "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/aoai.tf"
click node_security "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/keyvault.tf"
click node_monitoring "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/applicationinsights.tf"
click node_teams_manifest "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/teams/manifest.json"
click node_scenarios_def "https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/schemas/scenarios.schema.json"
click node_deploy_docs "https://github.com/perfectthymetech/m365-custom-agent/blob/main/docs/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_api,node_heartbeat,node_messages,node_copilot,node_handler,node_teams,node_webchat,node_scenarios,node_root_agent,node_doc_agent,node_sum_agent,node_actions_agent,node_files,node_models,node_settings,node_logs toneBlue
class node_webapp,node_botsvc,node_stores,node_ai,node_security,node_monitoring toneAmber
class node_teams_manifest,node_scenarios_def,node_deploy_docs toneMint
```

## Components

### App runtime

Python FastAPI service and copilot logic

- [Main](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/main.py): FastAPI entrypoint · Application bootstrap and server startup · `code/copilot/app/main.py`
- [API v1](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/router.py): REST layer · Versioned HTTP surface for service operations · `code/copilot/app/api/v1/router.py`
- [Heartbeat](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/endpoints/heartbeat.py): health endpoint · Readiness and service health checks · `code/copilot/app/api/v1/endpoints/heartbeat.py`
- [Messages](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/api/v1/endpoints/messages.py): message endpoint · Conversation entrypoint for user requests · `code/copilot/app/api/v1/endpoints/messages.py`
- [Copilot core](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/copilot.py): channel orchestration · Shared activity handling and scenario routing · `code/copilot/app/copilot/copilot.py`
- [Handler base](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_abstract.py): adapter contract · Abstract boundary for channel-specific handlers · `code/copilot/app/copilot/handler_abstract.py`
- [Teams handler](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_msteams.py): channel adapter · Microsoft Teams activity processing · `code/copilot/app/copilot/handler_msteams.py`
- [Webchat handler](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/handler_webchat.py): channel adapter · Web chat activity processing · `code/copilot/app/copilot/handler_webchat.py`
- [Scenarios](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/copilot/scenarios.py): routing rules · Scenario-driven workflow selection and configuration · `code/copilot/app/copilot/scenarios.py`
- [Root agent](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/root.py): agent · Top-level request interpretation and dispatch · `code/copilot/app/agents/root.py`
- [Document agent](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/document.py): agent · Document-oriented workflow handling · `code/copilot/app/agents/document.py`
- [Summarizer](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/summarizer.py): agent · Response condensation and synthesis · `code/copilot/app/agents/summarizer.py`
- [Actions](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/agents/actions.py): agent · Action execution and tool-oriented behavior · `code/copilot/app/agents/actions.py`
- [File pipeline](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/files/extraction.py): attachment processing · Attachment compression and extraction flow · `code/copilot/app/files/extraction.py`
- [Domain models](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/models/copilot.py): data contracts · Typed service entities for copilot, scenarios, attachments, and heartbeat · `code/copilot/app/models/copilot.py`
- [Settings](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/core/settings.py): config · Environment-driven runtime configuration · `code/copilot/app/core/settings.py`
- [Telemetry](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/copilot/app/logs.py): observability · Logging and OpenTelemetry setup · `code/copilot/app/logs.py`

### Azure infra

Terraform-managed deployment and platform dependencies

- [Web App](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/webapplinux.tf): Azure Linux host · Container hosting for the FastAPI service · `code/infra/webapplinux.tf`
- [Bot Service](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/botservice.tf): Azure channel gateway · Channel connectivity for Teams and bot traffic · `code/infra/botservice.tf`
- [Data stores](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/cosmosdb.tf): Cosmos and Storage · Persistent state, artifacts, and file storage · `code/infra/cosmosdb.tf`
- [AI services](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/aoai.tf): Azure OpenAI and DI · Model inference and document intelligence dependencies · `code/infra/aoai.tf`
- [Secrets and identity](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/keyvault.tf): Key Vault and MI · Managed identity, secret access, and role assignments · `code/infra/keyvault.tf`
- [App Insights](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/infra/applicationinsights.tf): telemetry backend · Application monitoring and traces · `code/infra/applicationinsights.tf`

### Docs and packaging

Repository docs, Teams manifest, and scenario definitions

- [Teams manifest](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/teams/manifest.json): package boundary · Microsoft Teams app packaging and distribution · `code/teams/manifest.json`
- [Scenario defs](https://github.com/perfectthymetech/m365-custom-agent/blob/main/code/schemas/scenarios.schema.json): config schema · Repository-level scenario configuration contract · `code/schemas/scenarios.schema.json`
- [Deploy docs](https://github.com/perfectthymetech/m365-custom-agent/blob/main/docs/README.md): documentation · Deployment, setup, and scenario guidance · `docs/README.md`

## Connections

- Main → API v1: mounts · Bootstraps the versioned HTTP API
- Main → Copilot core: starts · Initializes the copilot runtime
- API v1 → Heartbeat: exposes · Health and readiness endpoint
- API v1 → Messages: exposes · Conversation endpoint
- Messages → Copilot core: dispatches · Hands message requests to orchestration
- Copilot core → Handler base: uses · Relies on abstract channel handling
- Handler base → Teams handler: implements · Teams-specific adapter
- Handler base → Webchat handler: implements · Web chat adapter
- Copilot core → Scenarios: routes by · Scenario-driven workflow selection
- Scenarios → Root agent: selects · Primary request entry agent
- Root agent → Document agent: delegates · Document-centric workflows
- Root agent → Summarizer: delegates · Response summarization
- Root agent → Actions: delegates · Action-oriented execution
- Messages → File pipeline: attaches · Attachment preprocessing for inbound messages
- File pipeline → Document agent: feeds · Processed file content enters document flow
- Copilot core → Domain models: shares · Uses typed internal contracts
- Copilot core → Settings: reads · Loads runtime configuration
- Copilot core → Telemetry: emits · Sends telemetry and logs
- Main → Web App: deploys to · Runs as a Linux container app
- Web App → Bot Service: connects · Receives channel traffic through bot service
- Web App → Data stores: persists to · Uses Cosmos DB and storage
- Web App → AI services: calls · Invokes OpenAI and document intelligence
- Web App → Secrets and identity: auth via · Uses managed identity and secrets
- Web App → App Insights: reports · Application telemetry sink
- Teams manifest → Bot Service: packages for · Teams app boundary for bot connectivity
- Scenario defs → Scenarios: defines · Scenario configuration contract
- Deploy docs → Web App: describes · Deployment guidance for the runtime