AgenticCode/.planning/ROADMAP.md

Roadmap: Chat Agent WebApp

Overview

Five phases take this project from an empty solution to a complete personal AI chat application. Each phase introduces one Blazor concept and delivers something verifiable. The dependency chain is strict: the WASM/API architecture must exist before storage, storage before conversations, conversations before AI, AI before display polish, and display before UI completeness. Streaming is deferred to v2. The result is a working, well-understood chat interface where every line of code is intentional and explained.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Architecture Foundation - Two-project solution scaffold with WASM/API split and shared models; establishes the tutorial commenting convention
• Phase 2: Conversation Storage - JSON file persistence and full conversation CRUD via repository pattern and Minimal API endpoints
• Phase 3: Basic AI Chat - End-to-end chat loop (send message → OpenAI → display response) without streaming
• Phase 4: Message Display - Markdown rendering, syntax-highlighted code blocks, and copy-to-clipboard
• Phase 5: UI Polish - Sidebar layout, chat input area, and responsive design across screen sizes

Phase Details

Phase 1: Architecture Foundation

Goal: The solution structure is locked in and 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 Depends on: Nothing (first phase) Requirements: CODE-01, CODE-02 Success Criteria (what must be TRUE):

1. Running dotnet run on both projects starts WASM client and API server without errors
2. A test HTTP request from the WASM client reaches the API server and returns a response (CORS working)
3. The shared models library is referenced by both projects with no duplication of DTOs
4. Running dotnet publish on the WASM project completes with no IL trim warnings
5. Every file introduced contains inline comments explaining the Blazor concept it demonstrates Plans: 2 plans Plans:

• 01-01-PLAN.md — Solution scaffold: create three projects, wire references, configure ports
• 01-02-PLAN.md — Health check round-trip: shared DTO, API controller with CORS, typed client, home page UI hint: yes

Phase 2: Conversation Storage

Goal: Users can create, switch between, and delete conversations that persist to disk and survive app restarts — with no AI integration yet Depends on: Phase 1 Requirements: CONV-01, CONV-02, CONV-03, CONV-04 Success Criteria (what must be TRUE):

1. User can create a new conversation and see it appear in the conversation list
2. User can click a conversation in the list and switch to it (conversation content loads)
3. User can delete a conversation and see it removed from the list
4. After closing and reopening the browser, all conversations and their messages are still present Plans: TBD

Phase 3: Basic AI Chat

Goal: Users can send a message and receive an AI response in the active conversation, with the full request/response cycle working end-to-end Depends on: Phase 2 Requirements: CHAT-01, CHAT-02 Success Criteria (what must be TRUE):

1. User can type a message, press send, and see their message appear in the chat area
2. User receives an AI response from OpenAI GPT displayed in the chat area
3. The conversation history is preserved across the full exchange and saved to disk
4. The OpenAI API key is never present in any WASM project file or browser network request Plans: TBD

Phase 4: Message Display

Goal: AI responses render as readable, formatted content — not raw markdown strings — with syntax-highlighted code and one-click copy Depends on: Phase 3 Requirements: DISP-01, DISP-02, DISP-03 Success Criteria (what must be TRUE):

1. An AI response containing markdown (headings, lists, bold, links) renders as formatted HTML in the chat area
2. Code blocks in AI responses display with syntax highlighting appropriate to the language
3. User can click a copy button on any message and the text is copied to the clipboard Plans: TBD UI hint: yes

Phase 5: UI Polish

Goal: The app has a complete, usable layout — sidebar with conversation list, chat input area, and a responsive design that works across screen sizes Depends on: Phase 4 Requirements: UI-01, UI-02, UI-03 Success Criteria (what must be TRUE):

1. App displays a sidebar on the left with the conversation list and a main chat area on the right
2. The chat area has a text input field and a send button visible at the bottom of the screen
3. The layout reflows gracefully on a narrow viewport (mobile-width browser window) without horizontal scrolling or clipped content Plans: TBD UI hint: yes

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5

Phase	Plans Complete	Status	Completed
1. Architecture Foundation	0/2	Planning complete	-
2. Conversation Storage	0/TBD	Not started	-
3. Basic AI Chat	0/TBD	Not started	-
4. Message Display	0/TBD	Not started	-
5. UI Polish	0/TBD	Not started	-