# microsoft/release-manager-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/release-manager-assistant
- Repository: https://github.com/microsoft/release-manager-assistant

## Overview

1. **Overall shape**
   This repo is a containerized, multi-service AI assistant for release management. It is split into a browser UI, a real-time session layer, an orchestration/agent backend, an MCP-based tool server, and Azure infrastructure code that deploys the whole stack.

2. **User-facing frontend**
   `src/frontend/react-app` is a React/Vite single-page app served as static content. It contains the chat UI, message rendering, and input controls. Its job is limited to presentation and user interaction; it does not contain business logic or direct integrations with Jira/Azure DevOps.

3. **Real-time session boundary**
   `src/backend/services/session_manager` is the WebSocket-facing service. It sits between the UI and the AI backend, managing client connections, conversation state, and message flow. The presence of `client_manager`, `conversation_handler`, and `websocket_handler` indicates it is the gateway for live chat sessions rather than the reasoning engine itself.

4. **Message/state infrastructure**
   The session layer uses shared utilities for queues, Redis messaging, and thread-safe caches from `src/backend/common/utilities`. The repo and README point to Redis as the backing service for session management and message queuing, so ephemeral conversation state is externalized rather than embedded in the frontend or orchestrator.

5. **Orchestrator as the reasoning core**
   `src/backend/services/orchestrator` is the main AI workflow service. It contains the agent coordinator, planner, fallback, final-answer generation, and domain agents. This is where user intent is interpreted and routed to the right capability, rather than directly answering in one model call.

6. **Agent specialization**
   The orchestrator splits work across agents such as `planner_agent`, `jira_agent`, `azure_devops_agent`, `visualization_agent`, and `fallback_agent`. This creates a clear internal boundary: planning and routing are separate from system-specific retrieval/update logic and separate again from response synthesis.

7. **External system integrations**
   Jira integration is handled through the orchestrator’s `jira_plugin`, while Azure DevOps integration is modeled through an MCP-oriented path plus the dedicated `src/backend/mcp_server`. The MCP server exposes Azure DevOps and Jira service adapters, including synthetic/static data for demo or offline scenarios. This makes tool access a separate service boundary rather than embedding every API client in the orchestrator.

8. **Shared contracts and cross-cutting code**
   `src/backend/common` is a shared package used by the services. It contains request/response schemas, configuration models, HTTP/caching clients, telemetry/logging, safety checks, and generic helpers. Architecturally, this is the glue layer that keeps the services consistent without coupling them tightly.

9. **Safety, telemetry, and storage**
   The common package includes text/image safety utilities and OpenTelemetry-style logging/tracing support. The README also calls out Azure Content Safety, Azure Storage, and Key Vault: storage is used for durable artifacts such as visualization outputs, Key Vault for secrets, and telemetry for observability across services.

10. **Azure deployment topology**
   The `infra` directory is the deployment boundary. Core modules provision networking, container apps environment, container registry, monitoring, storage, Key Vault, and AI project resources. App modules then deploy the frontend, session manager, orchestrator, Redis, and MCP server into that foundation.

11. **Runtime and packaging**
   Each backend service has its own Dockerfile and requirements file, so the runtime unit is a container per service. The repo also includes `docker-compose.yml`, devcontainer support, and deployment scripts for local and cloud workflows, which indicates the architecture is designed to run both locally and in Azure-managed containers.

12. **Delivery pipeline**
   `.github/workflows` and `.azdo/pipelines` show that CI/CD is supported in both GitHub and Azure DevOps. The scripts under `scripts/` handle image build/push and deployment orchestration, which reinforces that deployment is infrastructure-driven rather than manually assembled.

13. **Primary end-to-end flow**
   A user sends a chat message from the React app → the session manager receives it over WebSocket → the orchestrator plans the request and invokes the right agent → the agent calls Jira, Azure DevOps/MCP, or visualization tooling as needed → the orchestrator composes the final answer → the session manager returns it to the browser. This is the key diagram path to preserve.

14. **Important architectural boundaries**
   The main boundaries are: UI vs real-time session gateway, session gateway vs AI orchestration, orchestration vs external tools, and app runtime vs Azure infrastructure. Those separations are the core of the repository’s design and are the most important lines to draw in an architecture diagram.

Main entry points: [`src/backend/services/orchestrator/app.py`](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/app.py) (Orchestrator), [`src/backend/services/orchestrator/agents/agent_orchestrator.py`](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/agent_orchestrator.py) (Agent Router), [`infra/app`](https://github.com/microsoft/release-manager-assistant/tree/main/infra/app) (App Stack), [`src/backend/mcp_server/app.py`](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/mcp_server/app.py) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_react_app["React UI<br/>spa frontend"]
  node_chat_components["Chat Parts<br/>ui components"]
end

subgraph group_session["Session Layer"]
  node_session_app["Session Service<br/>ws gateway<br/>[app.py]"]
  node_ws_handler["WebSocket<br/>connection handler"]
  node_conversation_handler["Conversation<br/>state flow"]
  node_client_manager["Clients<br/>session registry<br/>[client_manager.py]"]
end

subgraph group_orchestrator["Orchestrator"]
  node_orchestrator_app["Orchestrator<br/>ai workflow service<br/>[app.py]"]
  node_agent_orchestrator["Agent Router<br/>workflow core"]
  node_planner_agent["Planner<br/>intent planning<br/>[planner_agent.py]"]
  node_jira_agent["Jira Agent<br/>issue workflow<br/>[jira_agent.py]"]
  node_devops_agent["DevOps Agent<br/>release workflow"]
  node_fallback_agent["Fallback<br/>recovery path<br/>[fallback_agent.py]"]
  node_final_answer["Answer Gen<br/>response synthesis"]
end

subgraph group_tools["Tooling"]
  node_jira_plugin["Jira Plugin<br/>jira integration<br/>[jira_plugin.py]"]
  node_devops_plugin["DevOps Plugin<br/>devops integration"]
  node_mcp_server["MCP Server<br/>tool service<br/>[app.py]"]
  node_mcp_factory["Tool Factory<br/>adapter factory<br/>[factory.py]"]
  node_mcp_services["Tool Adapters<br/>service adapters"]
end

subgraph group_shared["Shared Backend"]
  node_common_contracts["Contracts<br/>shared schemas"]
  node_common_utils["Utilities<br/>shared helpers"]
  node_common_telemetry["Telemetry<br/>observability"]
  node_common_safety["Safety<br/>guardrails"]
end

subgraph group_infra["Infrastructure"]
  node_infra_main["Infra Root<br/>azure deployment<br/>[main.bicep]"]
  node_infra_core["Core Stack<br/>foundation modules"]
  node_infra_app["App Stack<br/>service modules"]
end

subgraph group_delivery["Delivery"]
  node_workflows["CI/CD<br/>delivery pipeline<br/>[workflows]"]
end

node_react_app -->|"chat over WS"| node_session_app
node_chat_components -->|"compose UI"| node_react_app
node_session_app -->|"accepts"| node_ws_handler
node_ws_handler -->|"tracks clients"| node_client_manager
node_ws_handler -->|"routes messages"| node_conversation_handler
node_conversation_handler -->|"queues/state"| node_common_utils
node_conversation_handler -->|"forwards intent"| node_orchestrator_app
node_orchestrator_app -->|"starts workflow"| node_agent_orchestrator
node_agent_orchestrator -->|"plans"| node_planner_agent
node_agent_orchestrator -->|"routes jira"| node_jira_agent
node_agent_orchestrator -->|"routes devops"| node_devops_agent
node_agent_orchestrator -->|"degrades"| node_fallback_agent
node_agent_orchestrator -->|"synthesizes"| node_final_answer
node_jira_agent -->|"uses"| node_jira_plugin
node_devops_agent -->|"uses"| node_devops_plugin
node_devops_plugin -->|"tool calls"| node_mcp_server
node_jira_plugin -->|"tool calls"| node_mcp_server
node_mcp_server -->|"builds adapters"| node_mcp_factory
node_mcp_factory -->|"instantiates"| node_mcp_services
node_orchestrator_app -->|"uses schemas"| node_common_contracts
node_orchestrator_app -->|"emits traces"| node_common_telemetry
node_orchestrator_app -->|"checks content"| node_common_safety
node_orchestrator_app -->|"shares helpers"| node_common_utils
node_infra_main -->|"provisions"| node_infra_core
node_infra_main -->|"deploys"| node_infra_app
node_infra_app -->|"hosts"| node_session_app
node_infra_app -->|"hosts"| node_orchestrator_app
node_infra_app -->|"serves"| node_react_app
node_infra_app -->|"hosts"| node_mcp_server
node_infra_core -.->|"feeds monitoring"| node_common_telemetry
node_workflows -->|"deploys via"| node_infra_main

click node_react_app "https://github.com/microsoft/release-manager-assistant/tree/main/src/frontend/react-app"
click node_chat_components "https://github.com/microsoft/release-manager-assistant/tree/main/src/frontend/react-app/src/components"
click node_session_app "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/app.py"
click node_ws_handler "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/websocket_handler.py"
click node_conversation_handler "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/conversation_handler.py"
click node_client_manager "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/client_manager.py"
click node_orchestrator_app "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/app.py"
click node_agent_orchestrator "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/agent_orchestrator.py"
click node_planner_agent "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/planner_agent.py"
click node_jira_agent "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/jira_agent.py"
click node_devops_agent "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/azure_devops_agent.py"
click node_fallback_agent "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/fallback_agent.py"
click node_final_answer "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/final_answer_generator_agent.py"
click node_jira_plugin "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/plugins/jira_plugin.py"
click node_devops_plugin "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/plugins/az_devops_plugin.py"
click node_mcp_server "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/mcp_server/app.py"
click node_mcp_factory "https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/mcp_server/core/factory.py"
click node_mcp_services "https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/mcp_server/services"
click node_common_contracts "https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/contracts"
click node_common_utils "https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/utilities"
click node_common_telemetry "https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/telemetry"
click node_common_safety "https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/safety"
click node_infra_main "https://github.com/microsoft/release-manager-assistant/blob/main/infra/main.bicep"
click node_infra_core "https://github.com/microsoft/release-manager-assistant/tree/main/infra/core"
click node_infra_app "https://github.com/microsoft/release-manager-assistant/tree/main/infra/app"
click node_workflows "https://github.com/microsoft/release-manager-assistant/blob/main/.github/workflows"

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_react_app,node_chat_components,node_workflows toneBlue
class node_session_app,node_ws_handler,node_conversation_handler,node_client_manager toneAmber
class node_orchestrator_app,node_agent_orchestrator,node_planner_agent,node_jira_agent,node_devops_agent,node_fallback_agent,node_final_answer toneMint
class node_jira_plugin,node_devops_plugin,node_mcp_server,node_mcp_factory,node_mcp_services toneRose
class node_common_contracts,node_common_utils,node_common_telemetry,node_common_safety toneIndigo
class node_infra_main,node_infra_core,node_infra_app toneTeal
```

## Components

### Frontend

Browser UI and static app

- [React UI](https://github.com/microsoft/release-manager-assistant/tree/main/src/frontend/react-app): spa frontend · Chat interface and message rendering · `src/frontend/react-app`
- [Chat Parts](https://github.com/microsoft/release-manager-assistant/tree/main/src/frontend/react-app/src/components): ui components · Chat, message list, input, and header components · `src/frontend/react-app/src/components`

### Session Layer

WebSocket gateway and conversation state

- [Session Service](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/app.py): ws gateway · Entry point for live client sessions · `src/backend/services/session_manager/app.py`
- [WebSocket](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/websocket_handler.py): connection handler · Manages browser connections and live message transport · `src/backend/services/session_manager/handlers/websocket_handler.py`
- [Conversation](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/conversation_handler.py): state flow · Coordinates per-conversation message handling · `src/backend/services/session_manager/handlers/conversation_handler.py`
- [Clients](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/session_manager/handlers/client_manager.py): session registry · Tracks connected clients and routing state · `src/backend/services/session_manager/handlers/client_manager.py`

### Orchestrator

Planning and agent execution

- [Orchestrator](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/app.py): ai workflow service · Main reasoning and response service · `src/backend/services/orchestrator/app.py`
- [Agent Router](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/agent_orchestrator.py): workflow core · Coordinates planning, tool use, and answer generation · `src/backend/services/orchestrator/agents/agent_orchestrator.py`
- [Planner](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/planner_agent.py): intent planning · Breaks user requests into actionable steps · `src/backend/services/orchestrator/agents/planner_agent.py`
- [Jira Agent](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/jira_agent.py): issue workflow · Handles Jira-oriented actions and retrieval · `src/backend/services/orchestrator/agents/jira_agent.py`
- [DevOps Agent](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/azure_devops_agent.py): release workflow · Handles Azure DevOps-oriented actions and retrieval · `src/backend/services/orchestrator/agents/azure_devops_agent.py`
- [Fallback](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/fallback_agent.py): recovery path · Handles unsupported or degraded requests · `src/backend/services/orchestrator/agents/fallback_agent.py`
- [Answer Gen](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/agents/final_answer_generator_agent.py): response synthesis · Composes the final user-facing response · `src/backend/services/orchestrator/agents/final_answer_generator_agent.py`

### Tooling

MCP and external-system adapters

- [Jira Plugin](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/plugins/jira_plugin.py): jira integration · Orchestrator-side Jira tool integration · `src/backend/services/orchestrator/plugins/jira_plugin.py`
- [DevOps Plugin](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/services/orchestrator/plugins/az_devops_plugin.py): devops integration · Orchestrator-side Azure DevOps integration path · `src/backend/services/orchestrator/plugins/az_devops_plugin.py`
- [MCP Server](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/mcp_server/app.py): tool service · Separate service exposing tool adapters and demo data · `src/backend/mcp_server/app.py`
- [Tool Factory](https://github.com/microsoft/release-manager-assistant/blob/main/src/backend/mcp_server/core/factory.py): adapter factory · Builds MCP service adapters · `src/backend/mcp_server/core/factory.py`
- [Tool Adapters](https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/mcp_server/services): service adapters · Azure DevOps and Jira service implementations · `src/backend/mcp_server/services`

### Shared Backend

Common contracts, utilities, and cross-cutting code

- [Contracts](https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/contracts): shared schemas · Request, response, config, and domain models · `src/backend/common/contracts`
- [Utilities](https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/utilities): shared helpers · Queues, Redis messaging, caches, and config helpers · `src/backend/common/utilities`
- [Telemetry](https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/telemetry): observability · Logging, tracing, and trace context support · `src/backend/common/telemetry`
- [Safety](https://github.com/microsoft/release-manager-assistant/tree/main/src/backend/common/safety): guardrails · Text and image safety checks · `src/backend/common/safety`

### Infrastructure

Azure deployment and runtime foundation

- [Infra Root](https://github.com/microsoft/release-manager-assistant/blob/main/infra/main.bicep): azure deployment · Top-level Azure deployment composition · `infra/main.bicep`
- [Core Stack](https://github.com/microsoft/release-manager-assistant/tree/main/infra/core): foundation modules · Network, host, security, storage, monitoring, and AI foundation · `infra/core`
- [App Stack](https://github.com/microsoft/release-manager-assistant/tree/main/infra/app): service modules · Deploys frontend, session manager, orchestrator, Redis, and MCP server · `infra/app`

### Delivery

Container and CI/CD workflows

- [CI/CD](https://github.com/microsoft/release-manager-assistant/blob/main/.github/workflows): delivery pipeline · GitHub and Azure DevOps pipeline definitions · `.github/workflows`

## Connections

- React UI → Session Service: chat over WS · Browser UI sends user messages to the live session service
- Chat Parts → React UI: compose UI · Presentation components form the chat experience
- Session Service → WebSocket: accepts · Session service uses WebSocket handling as its entry path
- WebSocket → Clients: tracks clients · Connection handling relies on client tracking and routing state
- WebSocket → Conversation: routes messages · Inbound/outbound chat events flow through conversation handling
- Conversation → Utilities: queues/state · Conversation flow uses shared queueing, Redis messaging, and caches
- Conversation → Orchestrator: forwards intent · Session layer sends normalized requests to the orchestrator
- Orchestrator → Agent Router: starts workflow · Service entry point invokes the orchestration core
- Agent Router → Planner: plans · Orchestrator decomposes requests into steps
- Agent Router → Jira Agent: routes jira · Jira-related tasks are delegated to the Jira agent
- Agent Router → DevOps Agent: routes devops · Azure DevOps-related tasks are delegated to the DevOps agent
- Agent Router → Fallback: degrades · Unsupported or failed paths fall back to recovery behavior
- Agent Router → Answer Gen: synthesizes · Workflow concludes with final answer generation
- Jira Agent → Jira Plugin: uses · Jira agent calls the orchestrator-side Jira integration
- DevOps Agent → DevOps Plugin: uses · DevOps agent calls the orchestrator-side DevOps integration
- DevOps Plugin → MCP Server: tool calls · Azure DevOps access can be delegated to the MCP tool service
- Jira Plugin → MCP Server: tool calls · Jira access can also be mediated through the tool service
- MCP Server → Tool Factory: builds adapters · MCP app wires its service adapters through a factory
- Tool Factory → Tool Adapters: instantiates · Factory creates Azure DevOps and Jira service implementations
- Orchestrator → Contracts: uses schemas · Orchestrator depends on shared request/response and config models
- Orchestrator → Telemetry: emits traces · Orchestrator uses shared logging and tracing support
- Orchestrator → Safety: checks content · Safety utilities guard text and image handling
- Orchestrator → Utilities: shares helpers · Orchestrator uses shared config, HTTP, and storage helpers
- Infra Root → Core Stack: provisions · Root deployment composes the foundation Azure modules
- Infra Root → App Stack: deploys · Root deployment composes application modules
- App Stack → Session Service: hosts · Infrastructure deploys the session manager container app
- App Stack → Orchestrator: hosts · Infrastructure deploys the orchestrator container app
- App Stack → React UI: serves · Infrastructure deploys the frontend container/app
- App Stack → MCP Server: hosts · Infrastructure deploys the MCP tool service
- Core Stack → Telemetry: feeds monitoring · Monitoring and tracing are part of the Azure foundation
- CI/CD → Infra Root: deploys via · CI/CD pipelines drive the Azure deployment workflow