docs(01): capture phase context
This commit is contained in:
local
97
.planning/phases/01-architecture-foundation/01-CONTEXT.md
Normal file
97
.planning/phases/01-architecture-foundation/01-CONTEXT.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# 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*
|
||||
111
.planning/phases/01-architecture-foundation/01-DISCUSSION-LOG.md
Normal file
111
.planning/phases/01-architecture-foundation/01-DISCUSSION-LOG.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user