Skip to content

Commit 479068c

Browse files
workcontrolgitworkcontrolgit
committed
Add AI Enhancement tutorial plan, Series 6 and 7 folder structure
1 parent e481022 commit 479068c

3 files changed

Lines changed: 376 additions & 2 deletions

File tree

‎blogs/AI-ENHANCEMENT-SERIES-PLAN.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# AI Enhancement Tutorial — Series 6 & 7
2+
3+
> Update the checklist below as each article is completed.
4+
5+
## Context
6+
7+
The existing AngularNetTutorial (Series 0–5, 22 articles) covers the full CAT stack (Angular 20 + .NET 10 + Duende IdentityServer) but has zero AI content. Developers need practical, working examples of how to add AI to a real production-style app — not toy demos.
8+
9+
**Decisions:**
10+
* **AI Provider:** Ollama (free, local, no API key required) via Microsoft.Extensions.AI abstraction
11+
* **Series 6** — AI App Features (AI capabilities for end users of the TalentManagement app)
12+
* **Series 7** — Developer Productivity AI (AI tools for building faster)
13+
14+
**Why Ollama + Microsoft.Extensions.AI:**
15+
* Zero cost, no sign-up — tutorial readers can follow without a credit card
16+
* Microsoft.Extensions.AI is provider-agnostic: swap Ollama → Azure OpenAI → Anthropic by changing 1 line in DI registration
17+
* Aligned with .NET 10 ecosystem (official Microsoft abstraction)
18+
19+
---
20+
21+
## Coexistence Strategy: Feature Flags + Graceful Degradation
22+
23+
The original tutorial (Series 0–5) and AI tutorial (Series 6–7) share **one codebase**. AI features default to **off** so developers without Ollama are unaffected.
24+
25+
**`Microsoft.FeatureManagement` is already installed — no new dependencies needed.**
26+
27+
**Backend (.NET) — appsettings.json default (AI off):**
28+
```json
29+
"FeatureManagement": {
30+
"AiEnabled": false
31+
}
32+
```
33+
34+
**Frontend (Angular) — environment.ts default (AI hidden):**
35+
```typescript
36+
export const environment = {
37+
aiEnabled: false,
38+
...
39+
};
40+
```
41+
42+
**Two audiences, one repo:**
43+
* **Original tutorial readers (no Ollama)** — `aiEnabled: false` everywhere, zero broken UI or failed API calls
44+
* **AI enhancement readers (have Ollama)** — follow Series 6 article 6.1: set `"AiEnabled": true`, AI features activate
45+
46+
All Series 6 code merges into `develop` via feature branches. `AiEnabled` defaults to `false` so `develop` is safe for both audiences — no divergent AI branch needed.
47+
48+
---
49+
50+
## Series 6: AI App Features
51+
52+
**Folder:** `blogs/series-6-ai-app-features/`
53+
**Theme:** Add AI capabilities that HR managers and employees actually use
54+
55+
* **6.1** — `6.1-dotnet-ai-foundation.md` — Run a Local LLM in Your .NET 10 API with Ollama
56+
* Code: `IChatClient` DI setup, `POST /api/v1/ai/chat` endpoint, feature flag setup
57+
* **6.2** — `6.2-dotnet-ai-hr-assistant.md` — Build an HR AI Assistant That Knows Your Data
58+
* Code: `GetHrInsightQuery` (MediatR), inject DashboardMetrics context into prompt
59+
* **6.3** — `6.3-angular-ai-chat-widget.md` — Add an AI Chat Widget to Angular with Streaming
60+
* Code: `AiChatComponent`, SSE streaming with RxJS
61+
* **6.4** — `6.4-angular-ai-dashboard-insights.md` — AI-Generated Dashboard Insights in Angular Material
62+
* Code: AI Insights `mat-card` on dashboard, prompt engineering patterns
63+
* **6.5** — `6.5-dotnet-natural-language-search.md` — Natural Language Employee Search with LLM Query Parsing
64+
* Code: `NlSearchQuery` handler (.NET) + NL search bar (Angular)
65+
* **6.6** — `6.6-dotnet-ai-response-caching.md` — Cache Your AI Responses: Save Time and API Costs
66+
* Code: EasyCaching cache-aside in `OllamaAiService`, `X-AI-Cache` response header
67+
68+
---
69+
70+
## Series 7: Developer Productivity AI
71+
72+
**Folder:** `blogs/series-7-developer-productivity-ai/`
73+
**Theme:** AI tools that make the developer faster — applied to this exact codebase
74+
75+
* **7.1** — `7.1-claude-code-workflow.md` — How We Built 22 Articles with Claude Code
76+
* Content: CLAUDE.md patterns, prompting guide, session workflow tips
77+
* **7.2** — `7.2-copilot-clean-architecture.md` — GitHub Copilot for .NET Clean Architecture
78+
* Content: Copilot prompt patterns for CQRS handlers, FluentValidation, Mapster
79+
* **7.3** — `7.3-ai-generated-playwright-tests.md` — Generate Playwright Tests from User Stories with AI
80+
* Content: Prompt-to-test workflow, AI-generated `.spec.ts` files, human review checklist
81+
* **7.4** — `7.4-ai-code-review-github-actions.md` — AI Code Review in GitHub Actions
82+
* Content + Code: GitHub Action YAML using Anthropic API for PR review
83+
84+
---
85+
86+
## Gitflow Branch Strategy
87+
88+
**Branch naming:** `feature/[article-number]-[short-slug]`
89+
**Base branch:** always off `develop`, merge back via PR
90+
91+
### Feature Branch Map
92+
93+
* **6.1** — Parent: `feature/6.1-dotnet-ai-foundation` | ApiResources: `feature/6.1-dotnet-ai-foundation`
94+
* **6.2** — Parent: `feature/6.2-dotnet-ai-hr-assistant` | ApiResources: `feature/6.2-dotnet-ai-hr-assistant`
95+
* **6.3** — Parent: `feature/6.3-angular-ai-chat-widget` | Clients: `feature/6.3-angular-ai-chat-widget`
96+
* **6.4** — Parent: `feature/6.4-angular-ai-dashboard-insights` | Clients: `feature/6.4-angular-ai-dashboard-insights`
97+
* **6.5** — Parent: `feature/6.5-natural-language-search` | ApiResources + Clients: `feature/6.5-natural-language-search`
98+
* **6.6** — Parent: `feature/6.6-ai-response-caching` | ApiResources: `feature/6.6-ai-response-caching`
99+
* **7.1–7.4** — Parent only (blog articles, no submodule code changes)
100+
101+
### Gitflow Steps Per Article (with submodule code)
102+
103+
```bash
104+
# 1. Submodule feature branch (off develop)
105+
cd ApiResources/TalentManagement-API # or Clients/...
106+
git checkout develop && git pull
107+
git checkout -b feature/[N.N]-[slug]
108+
109+
# 2. Parent repo feature branch (off develop)
110+
cd ../..
111+
git checkout develop && git pull
112+
git checkout -b feature/[N.N]-[slug]
113+
114+
# 3. Code in submodule → commit → push
115+
git add . && git commit -m "Add [feature]"
116+
git push --set-upstream origin feature/[N.N]-[slug]
117+
118+
# 4. Blog article + submodule ref in parent → commit → push
119+
git add blogs/series-6-ai-app-features/[N.N]-*.md
120+
git add ApiResources/TalentManagement-API
121+
git commit -m "Add article [N.N] and [feature] implementation"
122+
git push --set-upstream origin feature/[N.N]-[slug]
123+
124+
# 5. Open PRs: submodule feature → develop, then parent feature → develop
125+
```
126+
127+
---
128+
129+
## Implementation Checklist
130+
131+
### Phase 0: Setup
132+
133+
- [x] Ollama running at `http://localhost:11434` ✅
134+
- [x] `blogs/AI-ENHANCEMENT-SERIES-PLAN.md` created ✅
135+
- [ ] Create `blogs/series-6-ai-app-features/` folder
136+
- [ ] Create `blogs/series-7-developer-productivity-ai/` folder
137+
- [ ] Create `docs/images/ai/` folder for screenshots
138+
- [ ] Update `blogs/BLOG-SERIES-PLAN.md` with Series 6 & 7 entries
139+
- [ ] Update `blogs/SERIES-NAVIGATION-TOC.md` to include new series
140+
141+
### Phase 1: Series 6 — Backend Foundation
142+
143+
- [ ] **6.1 — .NET AI Foundation**
144+
- [ ] `git checkout -b feature/6.1-dotnet-ai-foundation` in ApiResources submodule
145+
- [ ] `git checkout -b feature/6.1-dotnet-ai-foundation` in parent repo
146+
- [ ] Write article draft (`6.1-dotnet-ai-foundation.md`)
147+
- [ ] Add to WebApi.csproj: `Microsoft.Extensions.AI`, `Microsoft.Extensions.AI.Ollama`
148+
- [ ] Add `"FeatureManagement": { "AiEnabled": false }` to `appsettings.json`
149+
- [ ] Add `aiEnabled: false` to `environment.ts`
150+
- [ ] Create `Application/Interfaces/IAiChatService.cs`
151+
- [ ] Create `Infrastructure.Shared/Services/OllamaAiService.cs`
152+
- [ ] Create `WebApi/Controllers/v1/AiController.cs` with `[FeatureGate("AiEnabled")]`
153+
- [ ] Screenshot: Swagger AI endpoint → `docs/images/ai/`
154+
- [ ] Commit + push submodule feature branch
155+
- [ ] Commit + push parent feature branch (blog + submodule ref)
156+
- [ ] Open PR: ApiResources `feature/6.1-dotnet-ai-foundation` → `develop`
157+
- [ ] Open PR: Parent `feature/6.1-dotnet-ai-foundation` → `develop`
158+
159+
- [ ] **6.2 — HR AI Assistant (data-aware)**
160+
- [ ] `git checkout -b feature/6.2-dotnet-ai-hr-assistant` in ApiResources submodule
161+
- [ ] `git checkout -b feature/6.2-dotnet-ai-hr-assistant` in parent repo
162+
- [ ] Write article draft (`6.2-dotnet-ai-hr-assistant.md`)
163+
- [ ] Create `Application/Features/AI/Queries/GetHrInsightQuery.cs` (MediatR)
164+
- [ ] Inject DashboardMetrics context into prompt
165+
- [ ] Screenshot: AI answer about employee data → `docs/images/ai/`
166+
- [ ] Commit + push submodule feature branch
167+
- [ ] Commit + push parent feature branch
168+
- [ ] Open PR: ApiResources `feature/6.2-dotnet-ai-hr-assistant` → `develop`
169+
- [ ] Open PR: Parent `feature/6.2-dotnet-ai-hr-assistant` → `develop`
170+
171+
### Phase 2: Series 6 — Angular Frontend
172+
173+
- [ ] **6.3 — Angular AI Chat Widget**
174+
- [ ] `git checkout -b feature/6.3-angular-ai-chat-widget` in Clients submodule
175+
- [ ] `git checkout -b feature/6.3-angular-ai-chat-widget` in parent repo
176+
- [ ] Write article draft (`6.3-angular-ai-chat-widget.md`)
177+
- [ ] Create `src/app/services/api/ai.service.ts`
178+
- [ ] Create `src/app/routes/ai-chat/` (component + template + SCSS)
179+
- [ ] Implement SSE streaming with `HttpClient` + `EventSource`
180+
- [ ] Add to sidebar navigation (guarded by `environment.aiEnabled`)
181+
- [ ] Screenshot: Chat widget in Angular UI → `docs/images/ai/`
182+
- [ ] Commit + push Clients feature branch
183+
- [ ] Commit + push parent feature branch
184+
- [ ] Open PR: Clients `feature/6.3-angular-ai-chat-widget` → `develop`
185+
- [ ] Open PR: Parent `feature/6.3-angular-ai-chat-widget` → `develop`
186+
187+
- [ ] **6.4 — AI Dashboard Insights**
188+
- [ ] `git checkout -b feature/6.4-angular-ai-dashboard-insights` in Clients submodule
189+
- [ ] `git checkout -b feature/6.4-angular-ai-dashboard-insights` in parent repo
190+
- [ ] Write article draft (`6.4-angular-ai-dashboard-insights.md`)
191+
- [ ] Modify `dashboard.ts` — add AI insights call after metrics load
192+
- [ ] Add "AI Insights" `mat-card` to `dashboard.html` (guarded by `aiEnabled`)
193+
- [ ] Screenshot: Dashboard with AI insights card → `docs/images/ai/`
194+
- [ ] Commit + push Clients feature branch
195+
- [ ] Commit + push parent feature branch
196+
- [ ] Open PR: Clients `feature/6.4-angular-ai-dashboard-insights` → `develop`
197+
- [ ] Open PR: Parent `feature/6.4-angular-ai-dashboard-insights` → `develop`
198+
199+
### Phase 3: Series 6 — Advanced
200+
201+
- [ ] **6.5 — Natural Language Search**
202+
- [ ] `git checkout -b feature/6.5-natural-language-search` in ApiResources + Clients + parent
203+
- [ ] Write article draft (`6.5-dotnet-natural-language-search.md`)
204+
- [ ] .NET: Create `NlSearchQuery` MediatR handler (LLM → structured filter)
205+
- [ ] Angular: Add NL search bar above employee table
206+
- [ ] Screenshot: NL query → filtered employee list → `docs/images/ai/`
207+
- [ ] Commit + push all feature branches
208+
- [ ] Open PRs: ApiResources + Clients + Parent → `develop`
209+
210+
- [ ] **6.6 — AI Response Caching**
211+
- [ ] `git checkout -b feature/6.6-ai-response-caching` in ApiResources submodule + parent
212+
- [ ] Write article draft (`6.6-dotnet-ai-response-caching.md`)
213+
- [ ] .NET: Add EasyCaching cache-aside to `OllamaAiService`
214+
- [ ] Add `X-AI-Cache: HIT/MISS` response header
215+
- [ ] Screenshot: Swagger response headers showing cache → `docs/images/ai/`
216+
- [ ] Commit + push feature branches
217+
- [ ] Open PRs: ApiResources + Parent → `develop`
218+
219+
### Phase 4: Series 7 — Developer Productivity (parent repo only)
220+
221+
- [ ] **7.1 — Claude Code Workflow**
222+
- [ ] `git checkout -b feature/7.1-claude-code-workflow` in parent repo
223+
- [ ] Write article: CLAUDE.md patterns, prompting, session workflow
224+
- [ ] Commit + push → Open PR → `develop`
225+
226+
- [ ] **7.2 — Copilot for Clean Architecture**
227+
- [ ] `git checkout -b feature/7.2-copilot-clean-architecture` in parent repo
228+
- [ ] Write article: Copilot prompt patterns for CQRS, FluentValidation
229+
- [ ] Commit + push → Open PR → `develop`
230+
231+
- [ ] **7.3 — AI-Generated Playwright Tests**
232+
- [ ] `git checkout -b feature/7.3-ai-generated-playwright-tests` in parent repo
233+
- [ ] Write article: prompt-to-test workflow, human review checklist
234+
- [ ] Commit + push → Open PR → `develop`
235+
236+
- [ ] **7.4 — AI Code Review in GitHub Actions**
237+
- [ ] `git checkout -b feature/7.4-ai-code-review-ci` in parent repo
238+
- [ ] Write article + GitHub Action YAML using Anthropic API
239+
- [ ] Commit + push → Open PR → `develop`
240+
241+
---
242+
243+
## Writing Order
244+
245+
1. 6.1 — backend AI foundation (everything else depends on this)
246+
2. 6.2 — HR assistant (builds on 6.1)
247+
3. 6.3 — Angular chat widget (needs 6.1 endpoint)
248+
4. 6.4 — dashboard insights (builds on 6.2 + existing dashboard)
249+
5. 6.5 — NL search (builds on 6.1 + existing employee list)
250+
6. 6.6 — AI caching (builds on 6.1 + EasyCaching from article 2.5)
251+
7. 7.1–7.4 — independent, any order
252+
253+
---
254+
255+
## Ollama Setup Reference
256+
257+
```bash
258+
ollama pull llama3.2 # 2GB, fast for tutorials
259+
ollama serve # http://localhost:11434
260+
```
261+
262+
> **✅ Confirmed:** Ollama is running at `http://localhost:11434` in the dev environment.
263+
264+
---
265+
266+
## Verification (each Series 6 article)
267+
268+
1. Start all 3 services + `ollama serve`
269+
2. Set `"AiEnabled": true` in `appsettings.json` and `aiEnabled: true` in `environment.ts`
270+
3. Navigate to the feature in Angular (`http://localhost:4200`)
271+
4. Confirm AI responds correctly
272+
5. Verify Swagger endpoint behavior
273+
6. Reset `AiEnabled` to `false` — confirm original tutorial still works perfectly
274+
7. Run Playwright tests — ensure no regressions

‎blogs/BLOG-SERIES-PLAN.md‎

Lines changed: 80 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -177,12 +177,90 @@
177177

178178
---
179179

180+
## 🤖 Series 6: AI App Features
181+
182+
- [ ] **Article 6.1 — .NET AI Foundation**
183+
- **Title:** Run a Local LLM in Your .NET 10 API with Ollama
184+
- **Subtitle:** How Microsoft.Extensions.AI Makes Your API AI-Ready Without Locking You Into One Provider
185+
- **File:** `blogs/series-6-ai-app-features/6.1-dotnet-ai-foundation.md`
186+
- **Branch:** `feature/6.1-dotnet-ai-foundation`
187+
- **Notes:** Not started.
188+
189+
- [ ] **Article 6.2 — HR AI Assistant**
190+
- **Title:** Build an HR AI Assistant That Knows Your Data
191+
- **Subtitle:** Feed Real Employee Metrics Into a Local LLM and Get Meaningful Insights Back
192+
- **File:** `blogs/series-6-ai-app-features/6.2-dotnet-ai-hr-assistant.md`
193+
- **Branch:** `feature/6.2-dotnet-ai-hr-assistant`
194+
- **Notes:** Not started.
195+
196+
- [ ] **Article 6.3 — Angular AI Chat Widget**
197+
- **Title:** Add an AI Chat Widget to Angular with Streaming
198+
- **Subtitle:** Build a Real-Time Chat UI with SSE Streaming, Angular Signals, and Angular Material
199+
- **File:** `blogs/series-6-ai-app-features/6.3-angular-ai-chat-widget.md`
200+
- **Branch:** `feature/6.3-angular-ai-chat-widget`
201+
- **Notes:** Not started.
202+
203+
- [ ] **Article 6.4 — AI Dashboard Insights**
204+
- **Title:** AI-Generated Dashboard Insights in Angular Material
205+
- **Subtitle:** How to Prompt an LLM With Live Metrics and Display Smart Summaries on the Dashboard
206+
- **File:** `blogs/series-6-ai-app-features/6.4-angular-ai-dashboard-insights.md`
207+
- **Branch:** `feature/6.4-angular-ai-dashboard-insights`
208+
- **Notes:** Not started.
209+
210+
- [ ] **Article 6.5 — Natural Language Search**
211+
- **Title:** Natural Language Employee Search with LLM Query Parsing
212+
- **Subtitle:** Replace Keyword Filters With Plain-English Queries — The LLM Translates Intent Into API Parameters
213+
- **File:** `blogs/series-6-ai-app-features/6.5-dotnet-natural-language-search.md`
214+
- **Branch:** `feature/6.5-natural-language-search`
215+
- **Notes:** Not started.
216+
217+
- [ ] **Article 6.6 — AI Response Caching**
218+
- **Title:** Cache Your AI Responses: Save Time and API Costs
219+
- **Subtitle:** How EasyCaching Cache-Aside Eliminates Duplicate LLM Calls and Adds Cache Observability Headers
220+
- **File:** `blogs/series-6-ai-app-features/6.6-dotnet-ai-response-caching.md`
221+
- **Branch:** `feature/6.6-ai-response-caching`
222+
- **Notes:** Not started.
223+
224+
---
225+
226+
## 🛠️ Series 7: Developer Productivity AI
227+
228+
- [ ] **Article 7.1 — Claude Code Workflow**
229+
- **Title:** How We Built 22 Articles with Claude Code
230+
- **Subtitle:** The Prompting Patterns, CLAUDE.md Conventions, and Session Workflows That Made It Possible
231+
- **File:** `blogs/series-7-developer-productivity-ai/7.1-claude-code-workflow.md`
232+
- **Branch:** `feature/7.1-claude-code-workflow`
233+
- **Notes:** Not started.
234+
235+
- [ ] **Article 7.2 — Copilot for Clean Architecture**
236+
- **Title:** GitHub Copilot for .NET Clean Architecture
237+
- **Subtitle:** Prompt Patterns for Generating CQRS Handlers, FluentValidation Rules, and Mapster Mappings
238+
- **File:** `blogs/series-7-developer-productivity-ai/7.2-copilot-clean-architecture.md`
239+
- **Branch:** `feature/7.2-copilot-clean-architecture`
240+
- **Notes:** Not started.
241+
242+
- [ ] **Article 7.3 — AI-Generated Playwright Tests**
243+
- **Title:** Generate Playwright Tests from User Stories with AI
244+
- **Subtitle:** From Requirements to Running Tests — How to Prompt Your Way to a Full E2E Test Suite
245+
- **File:** `blogs/series-7-developer-productivity-ai/7.3-ai-generated-playwright-tests.md`
246+
- **Branch:** `feature/7.3-ai-generated-playwright-tests`
247+
- **Notes:** Not started.
248+
249+
- [ ] **Article 7.4 — AI Code Review in GitHub Actions**
250+
- **Title:** AI Code Review in GitHub Actions
251+
- **Subtitle:** Add an Automated AI Reviewer to Every Pull Request Using the Anthropic API
252+
- **File:** `blogs/series-7-developer-productivity-ai/7.4-ai-code-review-github-actions.md`
253+
- **Branch:** `feature/7.4-ai-code-review-ci`
254+
- **Notes:** Not started.
255+
256+
---
257+
180258
## 📊 Publication Tracker
181259

182-
**Total articles planned:** 21
260+
**Total articles planned:** 31
183261
**Published:** 1
184262
**Draft ready:** 22
185-
**Not started:** 0
263+
**Not started:** 10 (Series 6 & 7)
186264

187265
---
188266

‎blogs/SERIES-NAVIGATION-TOC.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,4 +60,26 @@
6060

6161
---
6262

63+
---
64+
65+
## 🤖 Series 6: AI App Features
66+
67+
* [6.1 — Run a Local LLM in Your .NET 10 API with Ollama](series-6-ai-app-features/6.1-dotnet-ai-foundation.md) — .NET AI Foundation
68+
* [6.2 — Build an HR AI Assistant That Knows Your Data](series-6-ai-app-features/6.2-dotnet-ai-hr-assistant.md) — HR AI Assistant
69+
* [6.3 — Add an AI Chat Widget to Angular with Streaming](series-6-ai-app-features/6.3-angular-ai-chat-widget.md) — Angular Chat Widget
70+
* [6.4 — AI-Generated Dashboard Insights in Angular Material](series-6-ai-app-features/6.4-angular-ai-dashboard-insights.md) — Dashboard Insights
71+
* [6.5 — Natural Language Employee Search with LLM Query Parsing](series-6-ai-app-features/6.5-dotnet-natural-language-search.md) — Natural Language Search
72+
* [6.6 — Cache Your AI Responses: Save Time and API Costs](series-6-ai-app-features/6.6-dotnet-ai-response-caching.md) — AI Response Caching
73+
74+
---
75+
76+
## 🛠️ Series 7: Developer Productivity AI
77+
78+
* [7.1 — How We Built 22 Articles with Claude Code](series-7-developer-productivity-ai/7.1-claude-code-workflow.md) — Claude Code Workflow
79+
* [7.2 — GitHub Copilot for .NET Clean Architecture](series-7-developer-productivity-ai/7.2-copilot-clean-architecture.md) — Copilot for Clean Architecture
80+
* [7.3 — Generate Playwright Tests from User Stories with AI](series-7-developer-productivity-ai/7.3-ai-generated-playwright-tests.md) — AI-Generated Tests
81+
* [7.4 — AI Code Review in GitHub Actions](series-7-developer-productivity-ai/7.4-ai-code-review-github-actions.md) — AI Code Review in CI/CD
82+
83+
---
84+
6385
*Articles without links are not yet written. Links will be updated to Medium URLs when published.*

0 commit comments

Comments
 (0)