AgenticCode/.planning/phases/01-architecture-foundation/01-CONTEXT.md

Phase 1: Architecture Foundation - Context

Gathered: 2026-03-27 Status: Ready for planning

## Phase Boundary

Two-project solution scaffold with WASM/API split and shared models. Establishes the tutorial commenting convention. The critical boundaries (no API key in WASM, no file I/O in WASM, no direct OpenAI calls from WASM) are architecturally enforced before any feature code is written.

## Implementation Decisions

Solution Structure

• D-01: Solution named ChatAgent.sln at repo root with three projects: ChatAgent.Client (Blazor WASM), ChatAgent.Api (ASP.NET Core backend), ChatAgent.Shared (shared models/DTOs)
• D-02: Projects live in src/ subfolders: src/ChatAgent.Client/, src/ChatAgent.Api/, src/ChatAgent.Shared/
• D-03: Solution file at repo root for easy dotnet build from project root

API Communication

• D-04: Typed HttpClient pattern — a ChatApiClient class in the Client project wraps all backend API calls, registered via DI
• D-05: Backend uses traditional MVC Controllers (not Minimal API) — more structure, familiar pattern for tutorial
• D-06: CORS configured on the API to allow the WASM client origin during development

Tutorial Comments

• D-07: Full tutorial-style inline comments — explain everything including basic patterns, treat every file as a teaching moment
• D-08: Comments go inline (XML doc comments and // comments right next to the code), no separate companion docs
• D-09: Every Blazor concept introduced must have a comment explaining WHAT it is and WHY it's used

UI Framework

• D-10: Start with plain HTML/CSS in Phase 1 — no MudBlazor yet. Learn raw Blazor rendering first, add component library later
• D-11: Light theme as default look and feel

Claude's Discretion

• CORS configuration details (origins, headers, methods)
• Base URL configuration approach (appsettings.json vs environment variables)
• Project file (.csproj) configuration details
• Test project structure (if any placeholder tests needed)
• .NET version targeting (9 vs 10 based on current stability)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Project context

• .planning/PROJECT.md — Project vision, constraints, core value (tutorial-style build)
• .planning/REQUIREMENTS.md — CODE-01 and CODE-02 requirements for this phase
• .planning/ROADMAP.md — Phase 1 success criteria and dependencies

Research

• .planning/research/STACK.md — Recommended .NET 9 stack, OpenAI SDK, Markdig, version compatibility
• .planning/research/ARCHITECTURE.md — WASM/API split architecture, component boundaries, data flow
• .planning/research/PITFALLS.md — Critical pitfalls: streaming transport, API key exposure, DI lifetimes, IL trimming

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• No existing application code — greenfield project

Established Patterns

• No patterns yet — this phase establishes the foundational patterns all subsequent phases will follow

Integration Points

• .planning/ directory exists with research and project docs
• .claude/ directory has GSD workflow tooling (do not modify)
• Git repo already initialized with planning commits

</code_context>

## Specific Ideas

• ChatAgent.* namespace convention for all projects
• Controllers over Minimal API for more structured, tutorial-friendly code
• Plain HTML/CSS first to understand raw Blazor before adding component libraries
• Full verbose comments — this is a learning project, not a production codebase

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 01-architecture-foundation Context gathered: 2026-03-27