diff --git a/.planning/phases/01-architecture-foundation/01-CONTEXT.md b/.planning/phases/01-architecture-foundation/01-CONTEXT.md new file mode 100644 index 0000000..809f5c5 --- /dev/null +++ b/.planning/phases/01-architecture-foundation/01-CONTEXT.md @@ -0,0 +1,97 @@ +# 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 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 + + + + +## 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 + + + + +## 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* diff --git a/.planning/phases/01-architecture-foundation/01-DISCUSSION-LOG.md b/.planning/phases/01-architecture-foundation/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..a67bfd9 --- /dev/null +++ b/.planning/phases/01-architecture-foundation/01-DISCUSSION-LOG.md @@ -0,0 +1,111 @@ +# Phase 1: Architecture Foundation - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-03-27 +**Phase:** 01-Architecture Foundation +**Areas discussed:** Solution structure, API communication, Tutorial comments, UI framework + +--- + +## Solution Structure + +### Naming +| Option | Description | Selected | +|--------|-------------|----------| +| ChatAgent.* | ChatAgent.Client, ChatAgent.Api, ChatAgent.Shared — clean namespace | ✓ | +| Custom name | You have a specific name in mind | | +| You decide | Claude picks a sensible naming convention | | + +**User's choice:** ChatAgent.* namespace + +### Location +| Option | Description | Selected | +|--------|-------------|----------| +| Repo root | Solution file at repo root, projects in src/ subfolders | ✓ | +| Nested src/ folder | Everything under src/ — keeps planning/config separate from code | | +| You decide | Claude picks based on .NET conventions | | + +**User's choice:** Repo root with src/ subfolders + +--- + +## API Communication + +### HTTP Client Pattern +| Option | Description | Selected | +|--------|-------------|----------| +| Typed HttpClient | Named/typed HttpClient via DI — ChatApiClient class wraps all API calls | ✓ | +| Raw HttpClient | Inject HttpClient directly into components — simpler but less organized | | +| You decide | Claude picks the best pattern for a tutorial project | | + +**User's choice:** Typed HttpClient (ChatApiClient) + +### API Style +| Option | Description | Selected | +|--------|-------------|----------| +| Minimal API | app.MapGet/MapPost — modern .NET, less boilerplate | | +| Controllers | Traditional MVC controllers — more structure, more files | ✓ | +| You decide | Claude picks based on .NET 9 best practices | | + +**User's choice:** Controllers + +--- + +## Tutorial Comments + +### Comment Depth +| Option | Description | Selected | +|--------|-------------|----------| +| Explain Blazor concepts | Comment on Blazor-specific things, skip basic C# | | +| Full tutorial | Explain everything including basic patterns — treat every file as a teaching moment | ✓ | +| Minimal + README | Light inline comments, but a per-phase README explaining what was built and why | | + +**User's choice:** Full tutorial — explain everything + +### Location +| Option | Description | Selected | +|--------|-------------|----------| +| Inline comments | XML doc comments and // comments right next to the code | ✓ | +| Companion docs | Separate .md file per phase explaining the concepts introduced | | +| Both | Inline comments + companion docs for deeper explanation | | + +**User's choice:** Inline comments only + +--- + +## UI Framework + +### Framework Choice +| Option | Description | Selected | +|--------|-------------|----------| +| MudBlazor now | Install MudBlazor 9.2.0 in Phase 1 — ready for later phases | | +| Plain HTML/CSS first | Start minimal, add MudBlazor later — learn raw Blazor rendering first | ✓ | +| You decide | Claude picks what makes sense for a tutorial progression | | + +**User's choice:** Plain HTML/CSS first + +### Look & Feel +| Option | Description | Selected | +|--------|-------------|----------| +| Dark theme | Dark background, light text — like ChatGPT/Claude | | +| Light theme | Light background, dark text — clean and bright | ✓ | +| System default | Follow OS preference | | +| You decide | Claude picks a sensible default | | + +**User's choice:** Light theme + +--- + +## Claude's Discretion + +- CORS configuration details +- Base URL configuration approach +- .csproj configuration details +- .NET version targeting +- Test project structure + +## Deferred Ideas + +None — discussion stayed within phase scope