# ecvanlare/cloud-standards-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ecvanlare/cloud-standards-assistant
- Repository: https://github.com/ecvanlare/cloud-standards-assistant

## Overview

This repository is an Azure-hosted, agentic assistant for cloud and DevOps standards. Its main interaction runs from the browser chat through a FastAPI backend to a Foundry agent, which retrieves indexed guidance and can call live ASB and Terraform-version tools before returning an answer with citations and trace metadata. Separate product branches cover corpus ingestion, safety, observability, evaluation, and multi-environment infrastructure. The graph follows documented capabilities and sampled call sites; unsampled subsystem wiring is shown only where README documentation supports it.

Main entry points: [`agents/standards-assistant.json`](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/agents/standards-assistant.json) (Foundry agent), [`serving/app/main.py`](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/main.py) (Chat BFF), [`search/index.json`](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/search/index.json) (AI Search index), [`terraform/envs`](https://github.com/ecvanlare/cloud-standards-assistant/tree/main/terraform/envs) (Azure resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Chat and agent"]
  node_chat_ui["Chat UI<br/>[app.js]"]
  node_bff["Chat BFF<br/>[main.py]"]
  node_foundry_agent["Foundry agent"]
  node_answer["Answer and citations<br/>[main.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_corpus["Standards corpus<br/>[README.md]"]
  node_ingestion["Search ingestion"]
  node_blob_store[("Azure Blob Storage")]
  node_search_index[("AI Search index<br/>[index.json]")]
end

subgraph group_integrations["Live tools and safety"]
  node_asb_tool["ASB version function<br/>[function_app.py]"]
  node_registry_tool["Registry proxy function<br/>[function_app.py]"]
  node_terraform_registry["Terraform Registry"]
  node_rai_policy["RAI content filters"]
end

subgraph group_operations["Telemetry and evaluation"]
  node_app_insights[("Application Insights")]
  node_golden_set["Golden evaluation set<br/>[golden_set.jsonl]"]
  node_local_eval["Regression evaluation<br/>[run_eval.py]"]
  node_cloud_eval["Foundry evaluation"]
end

subgraph group_platform["Azure platform"]
  node_azure_platform["Azure resources"]
end

node_user(("Assistant user"))

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"sends question"| node_bff
node_bff -->|"submits turn"| node_foundry_agent
node_foundry_agent -->|"returns response"| node_bff
node_bff -->|"formats response"| node_answer
node_answer -->|"renders"| node_chat_ui
node_corpus -->|"uploaded to"| node_blob_store
node_ingestion -->|"reads corpus"| node_blob_store
node_ingestion -->|"chunks and indexes"| node_search_index
node_blob_store -->|"indexer ingests"| node_search_index
node_foundry_agent -->|"retrieves guidance"| node_search_index
node_foundry_agent -->|"calls version tool"| node_asb_tool
node_foundry_agent -->|"calls registry tool"| node_registry_tool
node_registry_tool -->|"fetches versions"| node_terraform_registry
node_foundry_agent -->|"applies guardrails"| node_rai_policy
node_bff -->|"sends OTel"| node_app_insights
node_foundry_agent -->|"emits traces"| node_app_insights
node_golden_set -->|"supplies cases"| node_local_eval
node_local_eval -->|"runs questions"| node_foundry_agent
node_golden_set -->|"supplies dataset"| node_cloud_eval
node_cloud_eval -->|"evaluates agent"| node_foundry_agent
node_azure_platform -.->|"provisions platform"| node_foundry_agent
node_azure_platform -.->|"provisions search"| node_search_index
node_azure_platform -.->|"provisions monitoring"| node_app_insights

click node_chat_ui "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/static/app.js"
click node_bff "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/main.py"
click node_foundry_agent "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/agents/standards-assistant.json"
click node_answer "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/main.py"
click node_corpus "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/corpus/README.md"
click node_ingestion "https://github.com/ecvanlare/cloud-standards-assistant/tree/main/search"
click node_search_index "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/search/index.json"
click node_asb_tool "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/tools/functions/asb_version/function_app.py"
click node_registry_tool "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/tools/functions/terraform_registry/function_app.py"
click node_rai_policy "https://github.com/ecvanlare/cloud-standards-assistant/tree/main/safety"
click node_golden_set "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/golden_set.jsonl"
click node_local_eval "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/scripts/run_eval.py"
click node_cloud_eval "https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/scripts/run-foundry-eval.py"
click node_azure_platform "https://github.com/ecvanlare/cloud-standards-assistant/tree/main/terraform/envs"

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_chat_ui,node_bff,node_foundry_agent,node_answer,node_user toneBlue
class node_corpus,node_ingestion,node_blob_store,node_search_index toneAmber
class node_asb_tool,node_registry_tool,node_terraform_registry,node_rai_policy toneMint
class node_app_insights,node_golden_set,node_local_eval,node_cloud_eval toneRose
class node_azure_platform toneIndigo
```

## Components

### Chat and agent

- [Chat UI](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/static/app.js): `serving/app/static/app.js`
- [Chat BFF](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/main.py): `serving/app/main.py`
- [Foundry agent](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/agents/standards-assistant.json): `agents/standards-assistant.json`
- [Answer and citations](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/serving/app/main.py): `serving/app/main.py`

### Knowledge retrieval

- [Standards corpus](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/corpus/README.md): `corpus/README.md`
- [Search ingestion](https://github.com/ecvanlare/cloud-standards-assistant/tree/main/search): `search`
- **Azure Blob Storage**
- [AI Search index](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/search/index.json): `search/index.json`

### Live tools and safety

- [ASB version function](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/tools/functions/asb_version/function_app.py): `tools/functions/asb_version/function_app.py`
- [Registry proxy function](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/tools/functions/terraform_registry/function_app.py): `tools/functions/terraform_registry/function_app.py`
- **Terraform Registry**
- [RAI content filters](https://github.com/ecvanlare/cloud-standards-assistant/tree/main/safety): `safety`

### Telemetry and evaluation

- **Application Insights**
- [Golden evaluation set](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/golden_set.jsonl): `eval/golden_set.jsonl`
- [Regression evaluation](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/scripts/run_eval.py): `eval/scripts/run_eval.py`
- [Foundry evaluation](https://github.com/ecvanlare/cloud-standards-assistant/blob/main/eval/scripts/run-foundry-eval.py): `eval/scripts/run-foundry-eval.py`

### Azure platform

- [Azure resources](https://github.com/ecvanlare/cloud-standards-assistant/tree/main/terraform/envs): `terraform/envs`

### Other components

- **Assistant user**

## Connections

- Assistant user → Chat UI: asks
- Chat UI → Chat BFF: sends question
- Chat BFF → Foundry agent: submits turn
- Foundry agent → Chat BFF: returns response
- Chat BFF → Answer and citations: formats response
- Answer and citations → Chat UI: renders
- Standards corpus → Azure Blob Storage: uploaded to
- Search ingestion → Azure Blob Storage: reads corpus
- Search ingestion → AI Search index: chunks and indexes
- Azure Blob Storage → AI Search index: indexer ingests
- Foundry agent → AI Search index: retrieves guidance
- Foundry agent → ASB version function: calls version tool
- Foundry agent → Registry proxy function: calls registry tool
- Registry proxy function → Terraform Registry: fetches versions
- Foundry agent → RAI content filters: applies guardrails
- Chat BFF → Application Insights: sends OTel
- Foundry agent → Application Insights: emits traces
- Golden evaluation set → Regression evaluation: supplies cases
- Regression evaluation → Foundry agent: runs questions
- Golden evaluation set → Foundry evaluation: supplies dataset
- Foundry evaluation → Foundry agent: evaluates agent
- Azure resources → Foundry agent: provisions platform
- Azure resources → AI Search index: provisions search
- Azure resources → Application Insights: provisions monitoring