Azure / Azure/GPT-RAG

Architecture diagram shows the classic topology and contradicts the hosted default in README

Open
#683 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.2k
Forks
321
Avg merge
6h 22m
Merged PRs (30d)
26

Description

`README.md` L36 embeds `media/architecture_zero_trust.png`, which draws the
classic topology: the orchestrator as a Container App, an MCP Container App,
and Cosmos DB under *GenAI App Backing Services*. None of those hold for a
fresh deployment today.

A fresh deployment resolves to `HOSTED_NO_PANEL` (ADR-0001 revision 5;
`config/deployment/composition.py` L255), so the diagram describes a topology
the template no longer provisions by default.

## Evidence

| Diagram element | Behaviour in hosted mode |
| --- | --- |
| Orchestrator drawn inside the Container App Environment | `config/deployment/composition.py` L624-629 filters `service_name == "orchestrator"` out of `containerAppsList`; the Container App is never provisioned. `selected_components` (L442-449) returns only `gpt-rag-ui` and `gpt-rag-ingestion`. The orchestrator runs as a Foundry hosted agent pinned to an immutable digest. |
| MCP drawn as a Container App | `manifest.json` on `main` (`v3.8.3`) pins three components and no `gpt-rag-mcp`; `main.parameters.json` declares only `orchestrator`, `frontend`, and `dataingest` in `containerAppsList`. |
| Cosmos DB under *GenAI App Backing Services* | `deployCosmosDb` (L565-569) is true only for classic, hosted/panel, or a hosted deployment still preserving the classic runtime. Hosted/no-panel provisions no account, and `resolve_database_containers` (L435-439) returns an empty container list. |
| "Build Agent" in the DevOps Build Subnet | Placement is right, the label is not. `infra/main.bicep` L2671-2682 provisions a `Microsoft.ContainerRegistry/registries/agentPools` injected into `devopsBuildAgentsSubnetName` — an ACR Tasks agent pool, not a build VM. `composition.py` L570-571 forces it on whenever hosted mode runs with `NETWORK_ISOLATION`. |

Nothing in the diagram represents the hosted image lifecycle — ACR build,
immutable digest publication, and digest-to-digest rollback — even though the
**Foundry Agent Service** box is already drawn inside the AI Foundry Project.
The diagram never connects the orchestrator to it.

## Resolved

- [x] **README scope decided.** #684 relabels the export *"Zero-Trust
Architecture, classic topology"* and adds a paragraph stating that a fresh
deployment defaults to the hosted topology, linking to *Hosted
conversation continuity*. The decision was to keep the classic diagram
alongside the hosted description rather than replace it outright, so the
README no longer contradicts itself while the artwork is still pending.
- [x] **Written specification published.**
`docs/architecture_legacy_diagram_handoff.md` on the `docs` branch carries
the full redraw spec across five sections: shapes and labels, connections
and labels, hosted image preparation inset, legend and visual treatment,
and what to remove or relabel.
- [x] **Editable source located.** The original is committed at
`docs/media/GPT-RAG.vsdx` on the `docs` branch (2,721,450 bytes, unchanged
since 2026-06-04). An earlier revision of this issue claimed the diagram
"cannot currently be revised without the original file" — that was wrong.
The file is available; it just does not sit next to the `.png` on `main`.

## Remaining

Only the artwork. Apply `docs/architecture_legacy_diagram_handoff.md` to
`docs/media/GPT-RAG.vsdx`, re-export, and commit the new export to **both**
paths:

| Path | Branch | Consumed by |
| --- | --- | --- |
| `media/architecture_zero_trust.png` | `main` / `develop` | `README.md` L36 |
| `docs/media/architecture_zero_trust.png` | `docs` | published documentation site |

Both paths currently reference the same blob (`51df4f5f`). Updating one without
the other splits the published site from the repository README.

Not blocking, but worth doing in the same change: commit the re-export beside an
editable source, matching the pattern already used by
`docs/media/orchestrator_strategy/` (`.drawio` plus `.png` plus `.svg`) and
`docs/media/architecture_chat_runtime_modes.excalidraw` (source plus `.svg`).

## Not tracked here

Runtime behaviour of the hosted path (#597), the administrative panel (#611),
and document-level authorization (#591) are tracked separately. This issue
covers the architecture diagram and the README section that embeds it.

Contributor guide

Open the contributing guide

Research direction

Read docs/architecture_legacy_diagram_handoff.md and edit docs/media/GPT-RAG.vsdx using its five-section redraw specification. Re-export the artwork to media/architecture_zero_trust.png and docs/media/architecture_zero_trust.png, preserving the same content in both paths; optionally commit an editable source beside the exports. Done means the diagram represents the hosted default, labels the ACR Tasks agent pool correctly, and connects the orchestrator to Foundry Agent Service.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, python
Domain
cloud, documentation, infrastructure
Issue type
Documentation
Difficulty
3/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.