# Phase 1: Architecture Foundation - Context

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

<domain>
## 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.

</domain>

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

</decisions>

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

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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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