FAI Architecture Blueprint

Creates living, commit-tracked architecture blueprints that combine visual diagrams, component responsibility matrices, data flow descriptions, and WAF alignment in a single document. Prevents the gap between "what was designed" and "what was built" by making blueprints pull from the same source of truth as the infrastructure code.

When to Invoke

Workflow

Step 1 — Discover Existing Components

Scan the repository for service definitions, infrastructure files, and API contracts.

# Discover services from Bicep resources
grep -r "resource " infra/ --include="*.bicep" | \
  grep -v "//" | awk '{print $2, $3}' | sort -u

# From docker-compose
grep "^  [a-z]" docker-compose.yml | tr -d ':' | sort

# From solution-play manifest
cat fai-manifest.json | node -e "
  const d = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
  console.log(JSON.stringify(d.infrastructure?.resources ?? [], null, 2));
"

Step 2 — Generate Service Topology Diagram

graph TD
    Client[Browser / Mobile Client]
    APIM[Azure API Management]
    FuncApp[Azure Functions -- AI Gateway]
    AOAI[Azure OpenAI gpt-4o]
    AISearch[Azure AI Search]
    CosmosDB[Cosmos DB -- Conversation History]
    Redis[Redis Cache -- Semantic Cache]
    KeyVault[Azure Key Vault]
    ContentSafety[Azure Content Safety]

    Client -->|HTTPS + Bearer| APIM
    APIM -->|rate-limit + auth| FuncApp
    FuncApp -->|semantic cache check| Redis
    FuncApp -->|moderation| ContentSafety
    FuncApp -->|hybrid search| AISearch
    FuncApp -->|chat completion| AOAI
    FuncApp -->|store turn| CosmosDB
    FuncApp -->|read secrets| KeyVault

Step 3 — Component Responsibility Table

Step 4 — Data Flow Annotation

# data-flows.yaml — machine-readable flow registry
flows:
  - id: user-query
    type: sync
    path: [Client, APIM, FuncApp, ContentSafety, Redis, AISearch, AOAI]
    latency_budget_ms: 3000
    pii: true
    encryption: tls1.3

  - id: history-write
    type: async
    path: [FuncApp, CosmosDB]
    latency_budget_ms: 500
    pii: true
    encryption: at-rest-aes256

Step 5 — WAF Pillar Mapping

Step 6 — Key Design Decisions

Output Files

docs/
  architecture-blueprint.md        <- This document (human-readable)
  data-flows.yaml                   <- Machine-readable flow registry
  architecture-blueprint.mermaid    <- Standalone diagram for tooling

WAF Alignment

Compatible Solution Plays

• Play 02 — AI Landing Zone (infrastructure topology)
• Play 01 — Enterprise RAG (service topology)
• Play 11 — AI Landing Zone Advanced

Blueprint Freshness Check

Run this script in CI to flag components in deployment that are not documented in the blueprint:

#!/usr/bin/env bash
# Check for undocumented resources
DEPLOYED=$(az resource list --resource-group "$RG_NAME" \
  --query "[].name" --output tsv | sort)

DOCUMENTED=$(grep -oP '(?<=\[)[A-Za-z ]+(?=\])' docs/architecture-blueprint.md | \
  tr '[:upper:]' '[:lower:]' | sort)

UNDOCUMENTED=$(comm -23 <(echo "$DEPLOYED") <(echo "$DOCUMENTED"))
if [ -n "$UNDOCUMENTED" ]; then
  echo "WARNING: undocumented resources detected:"
  echo "$UNDOCUMENTED"
  exit 1
fi
echo "Blueprint is up to date with deployed resources."

Notes

• Blueprints are living documents — update the decision log (Step 6) for every significant architecture change
• Use Mermaid for diagrams; they render natively in GitHub, VS Code, and frootai.dev
• data-flows.yaml can be consumed by scripts to auto-generate network security group rules
• Run the freshness check in CI to catch undocumented resources before they become architecture drift