Agent skill

Understanding Architecture

by microsoft-foundry in microsoft-foundry/foundry-agent-webapp

Provides architecture overview with state machines, SSE event flow, and file mappings.

MITAuto-check passedDevelopment

Install Understanding Architecture

skills CLI
$ npx skills add microsoft-foundry/foundry-agent-webapp --skill understanding-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install microsoft-foundry/foundry-agent-webapp understanding-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/understanding-architecture .claude/skills/understanding-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
understanding-architecture
GitHub stars
127
Token cost
~2.1k tokens
SKILL.md length
559 words
Files
1
Skills in repo
19
Repo updated
First seen
Licence
MIT

At a glance

Provides architecture overview with state machines, SSE event flow, and file mappings.

  • Works in 3 steps: Check DeepWiki re-indexes (usually… → Verify diagrams match between… → Note: DeepWiki may show older commit -…
  • Understanding system design
  • SKILL.md covers Quick Reference, State Machines, SSE Event Flow and Key Files by Domain, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Understanding Architecture is an agent skill from microsoft-foundry/foundry-agent-webapp. Provides architecture overview with state machines, SSE event flow, and file mappings. Use when understanding system design, debugging state issues, or maintaining ARCHITECTURE-FLOW.md.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. The repository describes itself as: GitHub Copilot enabled repo for building and deploying a web application with Entra ID authentication and integrated with Azure AI Foundry Agents. The licence is MIT.

When your agent uses it

  • Understanding system design
  • Debugging state issues
  • Maintaining ARCHITECTURE-FLOW.md

Example prompts

  • “Use the understanding-architecture skill to provide architecture overview with state machines, SSE event flow, and file mappings”
  • “/understanding-architecture”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Check DeepWiki re-indexes (usually within 24 hours)
  2. Verify diagrams match between ARCHITECTURE-FLOW.md and DeepWiki
  3. Note: DeepWiki may show older commit - check "Last indexed" date

What it can do on your machine

Read from SKILL.md and the folder at commit f6cb362. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are powershell).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • deepwiki.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Understanding Architecture loads about 2.1k tokens when it runs. Until then it costs about 53 tokens; SKILL.md has 559 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~53
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft-foundry/foundry-agent-webapp at commit f6cb362, republished under its MIT licence (© microsoft-foundry). 559 words, ~2,127 tokens.

Download SKILL.mdSave it as .claude/skills/understanding-architecture/SKILL.md (or your agent's skills folder).
name
understanding-architecture
description
Provides architecture overview with state machines, SSE event flow, and file mappings. Use when understanding system design, debugging state issues, or maintaining ARCHITECTURE-FLOW.md.

Understanding Architecture

Load this skill when: Understanding system design, debugging state transitions, tracing SSE events, or updating architecture documentation.

Quick Reference

System Overview
LayerTechPortEntry Point
FrontendReact 19 + Vite5173frontend/src/App.tsx
BackendASP.NET Core 98080backend/WebApp.Api/Program.cs
AuthMSAL.js → JWT Bearer—frontend/src/config/authConfig.ts
AI SDKAzure.AI.Projects (GA) + Azure.AI.Extensions.OpenAI—backend/.../AgentFrameworkService.cs
Data Flow
text
User → ChatInput → CHAT_SEND_MESSAGE → ChatService.sendMessage()
     → POST /api/chat/stream (JWT) → AgentFrameworkService.StreamMessageAsync()
     → AI Foundry → SSE chunks → parseSseLine() → Reducer actions → UI update

State Machines

Chat States
text
idle ──CHAT_SEND_MESSAGE──► sending ──CHAT_START_STREAM──► streaming
  ▲                            │                              │
  │                            ▼                              ▼
  └──CHAT_CLEAR_ERROR─── error ◄──CHAT_ERROR──────────────────┤
  │                                                           │
  └──CHAT_STREAM_COMPLETE / CHAT_CANCEL_STREAM / CHAT_MCP_APPROVAL_REQUEST
StateInput EnabledstreamingMessageId
idle✅ Yesundefined
sending❌ Noundefined
streaming❌ NoMessage ID
errorIf recoverableundefined
Auth States
text
initializing ──AUTH_INITIALIZED──► authenticated ──AUTH_TOKEN_EXPIRED──► unauthenticated
                                         │                                    │
                                         └───────────AUTH_INITIALIZED──────────┘

SSE Event Flow

Backend → Frontend Mapping
SSE EventBackend MethodFrontend ActionReducer Effect
conversationIdWriteConversationIdEventCHAT_START_STREAMSet conversationId
chunkWriteChunkEventCHAT_STREAM_CHUNKAppend content
annotationsWriteAnnotationsEventCHAT_STREAM_ANNOTATIONSAdd citations
mcpApprovalRequestWriteMcpApprovalRequestEventCHAT_MCP_APPROVAL_REQUESTShow approval UI
usageWriteUsageEventCHAT_STREAM_COMPLETEAdd token counts
doneWriteDoneEventCHAT_STREAM_COMPLETEFinalize
errorWriteErrorEventCHAT_ERRORSet error state
Event Sequence
text
1. conversationId  (always first)
2. chunk           (0-N times)
3. annotations     (0-N times, after item complete)
4. mcpApprovalRequest (0-1 times, pauses stream)
5. usage           (always before done)
6. done            (always last)

Key Files by Domain

State Management
FilePurpose
frontend/src/types/appState.tsState & action type definitions
frontend/src/reducers/appReducer.tsAll state transitions
frontend/src/contexts/AppContext.tsxProvider + dev logging
SSE Streaming
FilePurpose
backend/WebApp.Api/Program.csSSE endpoints + Write*Event helpers
frontend/src/services/chatService.tsSSE client + action dispatch
frontend/src/utils/sseParser.tsLine parsing + event types
AI Integration
FilePurpose
backend/.../AgentFrameworkService.csAgent loading + streaming
backend/.../Models/StreamChunk.csChunk types (text, annotations, MCP)
backend/.../Models/ChatRequest.csRequest payload structure

Full Documentation

For complete diagrams and detailed flows, see:

  • ARCHITECTURE-FLOW.md - Full Mermaid diagrams
  • Part 1: Backend flow (request pipeline, credential resolution, agent loading)
  • Part 2: Frontend state (auth, chat, UI state machines)
  • Part 3: Performance patterns (reducer optimizations)
  • Part 4: Extending the state (adding new actions)
  • Part 5: Backend patterns (validation, error format, async)
  • Part 6: File reference (all key files)

Maintaining ARCHITECTURE-FLOW.md

When to Update

Update the architecture document when:

Change TypeWhat to Update
New SSE event typeSection 1.5 (Backend SSE Event Types), Section 2.8 (SSE → Action Mapping)
New reducer actionSection 2.7 (Action Reference), state machine diagrams
New API endpointSection 1.1 (Request Pipeline flowchart)
New auth stateSection 2.1 (Authentication State Machine)
New chat stateSection 2.2 (Chat State Machine)
File moved/renamedPart 6 (File Reference tables)
Validation rules changedSection 5.1 (Attachment Validation)
Validation Checklist

Before committing architecture doc changes:

text
□ Mermaid Diagrams
  □ All states match code (appState.ts types)
  □ All transitions match reducer (appReducer.ts cases)
  □ Diagram syntax renders without errors

□ Tables
  □ SSE events match Program.cs Write*Event methods
  □ Actions match AppAction type union
  □ File paths are lowercase (case-sensitive filesystems)

□ Code Snippets
  □ Patterns match actual code
  □ Variable names correct
  □ Examples would compile/run

□ File Links
  □ All referenced files exist
  □ Paths use correct case (chatService.ts not ChatService.ts)
Show full SKILL.md (225 more words)Show less
Source of Truth Mapping
Document SectionSource Code
Request Pipeline (1.1)Program.cs middleware + endpoints
Credential Resolution (1.2)AgentFrameworkService.cs constructor
Agent Loading (1.3)AgentFrameworkService.GetAgentAsync()
SSE Events (1.5)Program.cs static Write*Event methods
Auth States (2.1)appState.ts auth.status type
Chat States (2.2)appState.ts chat.status type
Action Reference (2.7)appState.ts AppAction type
SSE → Action (2.8)chatService.ts processStream switch
Attachment Limits (5.1)AgentFrameworkService.cs Max* constants
Quick Sync Commands
powershell
# Find all SSE event types in backend
Select-String -Path "backend/WebApp.Api/Program.cs" -Pattern "type.*="

# Find all reducer actions
Select-String -Path "frontend/src/types/appState.ts" -Pattern "type:"

# Find SSE parsing
Select-String -Path "frontend/src/services/chatService.ts" -Pattern "case '"

# Verify file links exist
Get-ChildItem -Recurse -Include "chatService.ts","appReducer.ts","appState.ts"
Cross-Reference with DeepWiki

DeepWiki (https://deepwiki.com/microsoft-foundry/foundry-agent-webapp) indexes the repo automatically. After major architecture changes:

  1. Check DeepWiki re-indexes (usually within 24 hours)
  2. Verify diagrams match between ARCHITECTURE-FLOW.md and DeepWiki
  3. Note: DeepWiki may show older commit - check "Last indexed" date

Common Architecture Questions

"How does a message flow end-to-end?"

See ARCHITECTURE-FLOW.md#2.3 - End-to-End Message Flow sequence diagram.

"What happens when streaming is cancelled?"
  1. User clicks Stop button or presses Escape
  2. ChatService.cancelStream() sets streamCancelled = true and calls abort()
  3. CHAT_CANCEL_STREAM action dispatched
  4. Reducer sets status: idle, clears streamingMessageId, enables input
"How does MCP tool approval work?"
  1. Backend yields StreamChunk.McpApproval when McpToolCallApprovalRequestItem received
  2. Frontend dispatches CHAT_MCP_APPROVAL_REQUEST with approval details
  3. Reducer adds approval message, sets status to idle (but input stays disabled)
  4. User clicks Approve/Deny
  5. ChatService.sendMcpApproval() resumes with approval response
"Where is the JWT validated?"

Program.cs → AddMicrosoftIdentityWebApi() + RequireAuthorization(ScopePolicyName) on each endpoint.

"How are credentials resolved in production vs development?"
  • Development: ChainedTokenCredential(AzureCliCredential, AzureDeveloperCliCredential)
  • Production: ManagedIdentityCredential(miClientId) (user-assigned MI with MANAGED_IDENTITY_CLIENT_ID)

© microsoft-foundry, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .github/skills/understanding-architecture of microsoft-foundry/foundry-agent-webapp.

Open the folder on GitHubat commit f6cb362

Compare with similar skills

Understanding Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Understanding Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Understanding Architecture this skillmicrosoft-foundry/foundry-agent-webapp127—~2.1kAutomated safety check: PassMIT
Component Refactoringlangflow-ai/langflow156k—~3.5kAutomated safety check: PassMIT
@pierre/diffs Code Renderingpierrecomputer/pierre6.2k2 repos~803Automated safety check: PassApache-2.0
Frontend Code Reviewlanggenius/dify158k—~938Automated safety check: PassCustom licence
Electron DevTools Trace Analysiskeybase/client9.3k—~809Automated safety check: PassBSD-3-Clause
Zodjasonjgardner/blockbench-mcp-plugin4913 repos~1.4kAutomated safety check: PassGPL-3.0

Similar skills

  • Component Refactoring

    langflow-ai/langflow

    Refactor high-complexity React components in Langflow frontend.

    156k GitHub stars~3.5k tokensUpdated today
    DevelopmentAuto-check passed
  • @pierre/diffs Code Rendering

    pierrecomputer/pierre

    Guides an agent through using @pierre/diffs to render syntax-highlighted files and diffs, and to build editing and review surfaces in React or plain JavaScript.

    6.2k GitHub starsUsed in 2 repos~803 tokens
    DevelopmentAuto-check passed
  • Frontend Code Review

    langgenius/dify

    Reviews frontend changes under `web/` or `packages/dify-ui/` for concrete defects and broken project contracts, using routed rule packs and a severity scale for findings.

    158k GitHub stars~938 tokensUpdated today
    DevelopmentAuto-check passed
  • Analyzes Chrome or Electron DevTools Performance trace exports with Python scripts to find where render time actually goes, without opening DevTools.

    9.3k GitHub stars~809 tokensUpdated today
    DevelopmentAuto-check passed
  • Zod

    jasonjgardner/blockbench-mcp-plugin

    Zod schema validation best practices for type safety, parsing, and error handling.

    491 GitHub starsUsed in 3 repos~1.4k tokens
    DevelopmentAuto-check passed
  • Moonbit Docs Maintainer

    moonbitlang/moonbit-docs

    A skill your agent uses when maintaining the moonbitlang/moonbit-docs repository, including Sphinx docs under next/, MoonBit examples under next/sources/, error-code documentation, gettext…

    2.4k GitHub stars~1.1k tokensUpdated 17 days ago
    DevelopmentAuto-check passed

More from microsoft-foundry/foundry-agent-webapp

All 19 skills in this repo
  • Committing Code

    microsoft-foundry/foundry-agent-webapp

    Provides commit message format and workflow for this repository.

    127 GitHub stars~512 tokensUpdated 5 mo ago
    Auto-check passed
  • Implementing Chat Streaming

    microsoft-foundry/foundry-agent-webapp

    Provides SSE streaming patterns for the chat API and frontend.

    127 GitHub stars~1.9k tokensUpdated 5 mo ago
    Auto-check passed
  • Planning Features

    microsoft-foundry/foundry-agent-webapp

    Provides structured plan template for feature implementation.

    127 GitHub stars~548 tokensUpdated 5 mo ago
    Auto-check passed
  • Researching Azure AI SDK

    microsoft-foundry/foundry-agent-webapp

    Provides research patterns for Foundry Agent Service SDK. An agent skill from microsoft-foundry/foundry-agent-webapp.

    127 GitHub stars~4.7k tokensUpdated 5 mo ago
    Auto-check passed
  • Deploying To Azure

    microsoft-foundry/foundry-agent-webapp

    Provides deployment commands and troubleshooting for Azure Container Apps.

    127 GitHub stars~2.2k tokensUpdated 5 mo ago
    Auto-check: warnings
  • Syncing MCP Servers

    microsoft-foundry/foundry-agent-webapp

    Synchronize MCP server configuration between VS Code (.vscode/mcp.json) and Copilot CLI (~/.copilot/mcp-config.json).

    127 GitHub stars~1.3k tokensUpdated 5 mo ago
    Auto-check passed

Questions about Understanding Architecture

What does Understanding Architecture do?

Provides architecture overview with state machines, SSE event flow, and file mappings. Understanding Architecture is an agent skill from microsoft-foundry/foundry-agent-webapp. Provides architecture overview with state machines, SSE event flow, and file mappings.

When should I use Understanding Architecture?

Understanding Architecture fits situations like: understanding system design; debugging state issues; maintaining ARCHITECTURE-FLOW.md.

How do I install Understanding Architecture in Claude Code?

Run `npx skills add microsoft-foundry/foundry-agent-webapp --skill understanding-architecture -a claude-code`. Or copy the skill folder (.github/skills/understanding-architecture in microsoft-foundry/foundry-agent-webapp) into .claude/skills/understanding-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Understanding Architecture in Codex?

Run `npx skills add microsoft-foundry/foundry-agent-webapp --skill understanding-architecture -a codex`. Or copy the skill folder (.github/skills/understanding-architecture in microsoft-foundry/foundry-agent-webapp) into .agents/skills/understanding-architecture in your project. Codex loads it when a task matches its description.

Can I use Understanding Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft-foundry/foundry-agent-webapp --skill understanding-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/understanding-architecture, .gemini/skills/understanding-architecture, .github/skills/understanding-architecture and .opencode/skills/understanding-architecture in your project.

What does Understanding Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: Understanding Architecture is instructions for the agent only.

Does Understanding Architecture access the network?

SKILL.md names 1 domain. As links in the text: deepwiki.com. This is read from the text; nothing was executed.

Is Understanding Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Understanding Architecture use?

Understanding Architecture is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Understanding Architecture use?

About 2.1k tokens (SKILL.md is roughly 8.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Understanding Architecture?

Skills that share tags, products or a category with Understanding Architecture: Component Refactoring (langflow-ai/langflow, 156k stars), @pierre/diffs Code Rendering (pierrecomputer/pierre, 6.2k stars), Frontend Code Review (langgenius/dify, 158k stars) and Electron DevTools Trace Analysis (keybase/client, 9.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Understanding Architecture?

microsoft-foundry (a GitHub organization) maintains it in microsoft-foundry/foundry-agent-webapp, which has 127 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on April 21, 2026.

Source: microsoft-foundry/foundry-agent-webapp on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.