Understanding Architecture

Understanding Architecture

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

Quick Reference

System Overview

Data Flow

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

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

Auth States

initializing ──AUTH_INITIALIZED──► authenticated ──AUTH_TOKEN_EXPIRED──► unauthenticated
                                         │                                    │
                                         └───────────AUTH_INITIALIZED──────────┘

SSE Event Flow

Backend → Frontend Mapping

Event Sequence

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

SSE Streaming

AI Integration

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:

Validation Checklist

Before committing architecture doc changes:

□ 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)

Source of Truth Mapping

Quick Sync Commands

# 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)