<!-- ref:abstraction-rules-v1 -->

# Diagram Abstraction Rules

Architecture diagrams must show the **primary data flow** clearly. Implementation
details that add visual noise without improving understanding MUST be omitted.

## What to SHOW in the main flow

- **Users/Clients** — entry point on the left
- **Identity service** — authentication gateway (e.g., Entra External ID)
- **Compute resources** — the application tier (App Service, Container Apps, Functions)
- **VNet container** — with data services inside (SQL, Storage, Cosmos DB)
- **External APIs** — consolidated into ONE grouped box (see below)

## What to OMIT from the main flow

- **Private Endpoints** — implied by VNet; do not show as individual icons
- **App Service Plans** — hosting detail, not architecture-relevant
- **NSG / Firewall rules** — configuration detail, not topology
- **Resource Group boundaries** — unnecessary visual clutter
- **Subnet subdivisions** — unless multiple subnets with different security zones

## Cross-cutting services (bottom section)

Place supporting services in a **separate row at the bottom** of the diagram
with a section label ("Supporting & Cross-Cutting Services"). These include:
Key Vault, Application Insights, Log Analytics, Private DNS Zones, Cost Budgets,
Azure Monitor, Entra ID (admin), Defender, Container Registry, Azure Policy.

**CRITICAL**: Do NOT draw edges/lines from any main-flow component to
cross-cutting services. Their presence at the bottom is sufficient.

## External APIs — consolidate into ONE box

When the architecture connects to multiple external services (payment, maps,
email), group them into a **single styled container** with a list of service
names inside. Use a warm fill color (`#fff2cc`, stroke `#d6b656`).
Draw ONE edge labeled "HTTPS" from compute to the external APIs box.

## Diagram title and footer

- **Title** (top-center): `{Project Name} — {Workload} Architecture` as the primary centered heading
- **Subtitle** (below title, centered): region and resilience summary in smaller text
- **Footer** (bottom-right): `Generated by design agent | {date}` plus one short note line in small, quiet text

Do not let the footer compete with the architecture. Keep it aligned to the bottom-right edge of the
outer shell with a smaller font than service labels.

## Box content styling

- Service-box labels must be centered horizontally
- Keep a clear icon zone at the top of each service box and a text zone below it
- Standardize service-box label font sizes across peers; only reduce size for unusually narrow boxes

## Mixed Azure + Fabric diagrams

When a workload contains both Azure platform services and Microsoft Fabric services:

- Use **Fabric icons** for Fabric-native services (Fabric, Data Factory, Lakehouse, Real-Time Intelligence, Power BI)
- Use **Azure icons** for Azure-native services (AKS, App Gateway, PostgreSQL, Event Hubs, Key Vault, Storage, Entra, Monitor, Defender)
- Normalize imported vector icon coordinates before placement so no sub-elements are stranded outside the target box

## Edge routing

Use the fewest arrows necessary to explain the primary flow, but route them deliberately:

- Start and end arrows at box edges, not at arbitrary internal coordinates
- Prefer elbow or single-bend routes for long cross-tier arrows
- Do not run arrows through service labels or icons
- Edge labels should be short protocol/flow annotations only (`HTTPS`, `AMQP / HTTPS`, `DirectLake`, `Capture`)

## Edge labels — primary flow only

Keep edges to the minimum needed to convey the request path:
`Users → (OAuth 2.0) → Identity → (Auth Token) → Compute → (VNet Integration) → VNet`.
From compute to external APIs: one edge labeled "HTTPS".
Do NOT draw edges for telemetry, secrets access, DNS resolution, or image pulls.
