Phase 5: docs, README, review checklist, demo script, CI workflow

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        run: cd frontend && npm ci
+
+      - name: Build
+        run: cd frontend && npx ng build
+
+      - name: Lint
+        run: cd frontend && npx ng lint

README.md

@@ -1,34 +1,160 @@
 # PulseFabric Monitor
 
-> GitHub Codespaces + Copilot Demo
+> Enterprise infrastructure monitoring dashboard — GitHub Codespaces + Copilot Demo
 
-Author — Mingchieh Wang, Wei Tien Pang
-Date: March 23, 2026
+**Authors:** Mingchieh Wang, Wei Tien Pang
+**Date:** March 23, 2026
 
-This project rearchitects the B2B Design-to-Code workflow, eliminating complex local environments and high-risk manual handoffs. Our 'AI Design Cloud Sandbox' securely syncs UI, code, and AI editing. By enforcing read-only reviews and strict boundaries, the system absorbs environmental risks, enabling safe, zero-friction PRs.
+---
+
+## What Is This?
+
+PulseFabric Monitor is a live demo showing how **GitHub Codespaces** and **GitHub Copilot** can replace complex local dev setups with zero-friction, AI-assisted development.
+
+The dashboard displays real-time KPI cards, traffic/incident charts, and alert feeds — all backed by a fake REST API. During a demo, presenters use Copilot Chat prompts to add new widgets **live**, proving that AI can follow strict coding rules and produce production-quality code.
+
+### Key Highlights
+
+- **Zero local setup** — open a Codespace and everything runs
+- **AI governance** — 20 production code rules that Copilot must follow
+- **Live coding demos** — 3 ready-to-use prompts for adding widgets on stage
+- **Fallback branch** — `demo-completed` has scenario 2 pre-built as backup
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | Angular 21, Angular Material (Material 3), ngx-echarts |
+| Backend | json-server (fake REST API from `backend/db.json`) |
+| Dev Environment | GitHub Codespaces, Dev Containers (Node.js 20) |
+| AI Governance | copilot-instructions.md, prompt files, agent profiles |
+
+---
+
+## Project Structure
+
+```
+backend/
+  db.json                          ← Fake REST data (KPIs, traffic, incidents, alerts)
+
+frontend/src/app/
+  core/
+    models/api.models.ts           ← All typed DTOs
+    services/dashboard-api.service.ts ← API abstraction layer
+  dashboard/
+    dashboard.ts / .html / .scss   ← Main dashboard page
+    kpi-card/                      ← Generic KPI card (input-driven)
+    chart-widget/                  ← Generic chart widget (input-driven)
+    alert-list/                    ← Alert list component
+    chart-config.factory.ts        ← Pure functions generating ECharts options
+
+.github/
+  copilot-instructions.md          ← 20 production code rules for Copilot
+  prompts/                         ← 3 demo prompt files
+  agents/                          ← Custom agent profile
+  skills/                          ← Optional widget scaffolding skill
+
+docs/
+  demo-script.md                   ← Step-by-step demo script (3 scenarios)
+  review-checklist.md              ← Code review checklist
+  ai-working-rules.md             ← AI working rules summary
+```
 
 ---
 
-## Getting Started with Codespaces
+## Getting Started
+
+### Option A: GitHub Codespaces (Recommended)
 
 1. Click the green **Code** button on the repository page.
 2. Select the **Codespaces** tab.
 3. Click **Create codespace on main**.
-4. Wait for the Dev Container to build — Node.js 20, Angular CLI, and all VS Code extensions will be installed automatically.
-5. Once the terminal is ready, you're good to go.
+4. Wait for the container to build — Node.js 20, Angular CLI, and all VS Code extensions install automatically.
+5. Run the dev servers:
+
+```bash
+npm run dev
+```
+
+6. The Angular app opens at **port 4200** and the API runs at **port 3000**.
+
+### Option B: Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/mwangui/Zero-friction.git
+cd Zero-friction
 
+# Install root dependencies (concurrently, json-server)
+npm install
 
-# Use cases for demo:
-Use these prompts during the live demo. Copy and paste one prompt at a time into Copilot Chat. Do not paste all prompts at once. After each prompt, review the result first. Once the output looks correct, continue to the next use case.
+# Install frontend dependencies
+cd frontend && npm install && cd ..
 
+# Start both servers
+npm run dev
+```
 
-1. Add a KPI Card
-Add a new KPI card called Active Sessions showing the number 14,200 with a trending up indicator. Put it next to the existing KPI cards. Follow all repo rules in copilot-instructions.md.
+| URL | Service |
+|-----|---------|
+| `http://localhost:4200` | Angular dashboard |
+| `http://localhost:3000` | json-server API |
 
+The Angular dev server proxies `/api/*` requests to json-server automatically.
 
-2. Add a Chart to AI Drop Zone
-Add a CPU Load by Device bar chart to the AI Widget Drop Zone at the bottom of the dashboard. Show 5 devices with fake CPU percentage data. Add the data to db.json first, then create the chart. Follow all repo rules in copilot-instructions.md.
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start both Angular + json-server concurrently |
+| `npm run dev:web` | Start Angular dev server only |
+| `npm run dev:api` | Start json-server only |
+| `npm run build:web` | Production build |
+| `npm run validate` | Build + lint |
+
+---
+
+## How to Demo
+
+See [docs/demo-script.md](docs/demo-script.md) for the full script. Quick summary:
+
+### Demo 1: Add a KPI Card
+
+Open Copilot Chat and paste:
+
+> Add a new KPI card called Active Sessions showing the number 14,200 with a trending up indicator. Put it next to the existing KPI cards. Follow all repo rules in copilot-instructions.md.
+
+### Demo 2: Add a Chart to AI Drop Zone
+
+> Add a CPU Load by Device bar chart to the AI Widget Drop Zone at the bottom of the dashboard. Show 5 devices with fake CPU percentage data. Add the data to db.json first, then create the chart. Follow all repo rules in copilot-instructions.md.
+
+### Demo 3: Add a Brand New Widget
+
+> Add a new AI Security Recommendations widget to the dashboard. It should show 3 recommendations, each with a priority level (High, Medium, Low) and a short description. Add the data to db.json first, then build the component. Follow all repo rules in copilot-instructions.md.
+
+**Fallback:** If any demo fails live, switch to the `demo-completed` branch which has scenario 2 pre-built.
+
+---
+
+## AI Governance
+
+This repo enforces 20 production code rules via `.github/copilot-instructions.md`. Key rules:
+
+- **Implementation order:** db.json → typed model → service → UI (never skip steps)
+- **No `any` type** — all data must be typed with interfaces
+- **No hardcoded data** — everything flows from the API
+- **CSS tokens only** — use `--mat-sys-*` and `--pf-*` variables
+- **Reuse before creating** — extend existing components via inputs
+
+See [docs/ai-working-rules.md](docs/ai-working-rules.md) for the full list.
+
+---
 
+## Branches
 
-3. Add a Brand New Widget
-Add a new AI Security Recommendations widget to the dashboard. It should show 3 recommendations, each with a priority level (High, Medium, Low) and a short description. Add the data to db.json first, then build the component. Follow all repo rules in copilot-instructions.md.
+| Branch | Purpose |
+|--------|---------|
+| `main` | Clean baseline — ready for live demo |
+| `demo-completed` | Scenario 2 (CPU Load chart) pre-built as fallback |

docs/demo-script.md

@@ -0,0 +1,170 @@
+# Demo Script — PulseFabric Monitor
+
+This script contains 3 live demo scenarios. Each scenario is designed to be executed in Copilot Chat during a presentation.
+
+**Prerequisites:**
+- Codespace is running (or local dev with `npm run dev`)
+- Both servers are up: Angular on port 4200, json-server on port 3000
+- Dashboard is visible in the browser at `http://localhost:4200`
+
+---
+
+## Scenario 1: Add a KPI Card — "Active Sessions"
+
+### Story
+
+> "Our operations team wants to see how many users are currently connected. Let's add an Active Sessions KPI card to the dashboard — live, using only a Copilot Chat prompt."
+
+### Copilot Chat Prompt
+
+Copy and paste this into Copilot Chat:
+
+> Add a new KPI card called Active Sessions showing the number 14,200 with a trending up indicator. Put it next to the existing KPI cards. Follow all repo rules in copilot-instructions.md.
+
+### Expected AI Actions
+
+1. **db.json** — Add a new entry to the `kpis` array:
+   ```json
+   {
+     "id": "active-sessions",
+     "title": "Active Sessions",
+     "value": "14,200",
+     "trend": "up",
+     "trendLabel": "+8.3% from last hour",
+     "icon": "group"
+   }
+   ```
+2. **api.models.ts** — No change needed (KpiDto already covers the shape)
+3. **dashboard-api.service.ts** — No change needed (getKpis already returns the array)
+4. **UI** — No change needed (the `@for` loop renders it automatically)
+
+### Expected Result
+
+- A fifth KPI card appears in the grid: "Active Sessions — 14,200 — trending up"
+- The card uses the same `<app-kpi-card>` component as existing cards
+- `ng build` still passes
+
+### What to Point Out
+
+- Only `db.json` was changed — the AI understood the data-first pattern
+- No new component was created — the existing KPI card is input-driven
+- The AI followed the implementation order: db.json → model → service → UI
+
+---
+
+## Scenario 2: Add a CPU Load Chart to AI Drop Zone
+
+### Story
+
+> "We have a drop zone at the bottom of the dashboard reserved for AI-generated widgets. Let's ask Copilot to fill it with a CPU Load by Device bar chart."
+
+### Copilot Chat Prompt
+
+Copy and paste this into Copilot Chat:
+
+> Add a CPU Load by Device bar chart to the AI Widget Drop Zone at the bottom of the dashboard. Show 5 devices with fake CPU percentage data. Add the data to db.json first, then create the chart. Follow all repo rules in copilot-instructions.md.
+
+### Expected AI Actions
+
+1. **db.json** — Add a new `cpuLoad` collection (replacing the empty array):
+   ```json
+   "cpuLoad": [
+     { "device": "Server-A1", "load": 72 },
+     { "device": "Server-B2", "load": 85 },
+     { "device": "Router-C3", "load": 45 },
+     { "device": "Switch-D4", "load": 91 },
+     { "device": "Gateway-E5", "load": 63 }
+   ]
+   ```
+2. **api.models.ts** — Add `CpuLoadDto` interface:
+   ```typescript
+   export interface CpuLoadDto {
+     device: string;
+     load: number;
+   }
+   ```
+3. **dashboard-api.service.ts** — Add `getCpuLoad()` method
+4. **chart-config.factory.ts** — Add `buildCpuLoadOption()` factory function using PALETTE colors
+5. **dashboard.ts** — Add signal + service call in forkJoin
+6. **dashboard.html** — Add `<app-chart-widget>` inside or near `#ai-dropzone`
+
+### Expected Result
+
+- A bar chart titled "CPU Load by Device" appears in the AI Widget Drop Zone area
+- 5 bars showing percentage values for each device
+- Colors come from the PALETTE constant (no raw hex in factory function)
+- `ng build` still passes
+
+### What to Point Out
+
+- The AI followed all 6 steps of the implementation order
+- No new component was created — the existing `ChartWidget` was reused
+- Chart colors use the PALETTE constant, not hardcoded hex values
+- The factory function is pure (no side effects)
+
+### Fallback
+
+If this scenario fails live, switch to the `demo-completed` branch:
+```bash
+git stash && git checkout demo-completed
+```
+Then restart the dev servers with `npm run dev`.
+
+---
+
+## Scenario 3: Add an AI Security Recommendations Widget
+
+### Story
+
+> "The security team wants an AI-powered recommendations panel. This requires a brand new component since it doesn't fit the KPI card or chart widget pattern. Let's see if Copilot can build it from scratch while following all 20 rules."
+
+### Copilot Chat Prompt
+
+Copy and paste this into Copilot Chat:
+
+> Add a new AI Security Recommendations widget to the dashboard. It should show 3 recommendations, each with a priority level (High, Medium, Low) and a short description. Add the data to db.json first, then build the component. Follow all repo rules in copilot-instructions.md.
+
+### Expected AI Actions
+
+1. **db.json** — Add a `securityRecommendations` collection:
+   ```json
+   "securityRecommendations": [
+     { "id": 1, "priority": "high", "description": "Rotate API keys for production cluster — last rotated 90+ days ago" },
+     { "id": 2, "priority": "medium", "description": "Enable MFA for 3 service accounts in US-East region" },
+     { "id": 3, "priority": "low", "description": "Update TLS certificates to use SHA-256 on staging endpoints" }
+   ]
+   ```
+2. **api.models.ts** — Add `SecurityRecommendationDto` interface
+3. **dashboard-api.service.ts** — Add `getSecurityRecommendations()` method
+4. **New component** — Create `security-recommendations/` under `dashboard/`:
+   - `security-recommendations.ts` — standalone, input-driven
+   - `security-recommendations.html` — flat HTML with Material components
+   - `security-recommendations.scss` — uses `--mat-sys-*` and `--pf-*` tokens
+5. **dashboard.ts** — Import component, fetch data, store in signal
+6. **dashboard.html** — Add `<app-security-recommendations>` tag
+
+### Expected Result
+
+- A new card-style widget appears showing 3 security recommendations
+- Each item shows a priority badge (High/Medium/Low) with appropriate color
+- The component uses Material 3 tokens for all styling
+- `ng build` still passes
+
+### What to Point Out
+
+- The AI created a **new component** because the data doesn't fit existing patterns
+- It still followed the strict order: db.json → model → service → UI
+- TS, HTML, SCSS are in separate files (Rule 1)
+- The component is standalone and input-driven (Rules 4, 11)
+- No `any` type anywhere (Rule 3/19)
+
+---
+
+## Tips for Presenters
+
+1. **Keep the terminal visible** — the audience should see file changes in real time
+2. **Show the Source Control diff** — highlight which files Copilot changed
+3. **Run `ng build`** after each scenario to prove the code compiles
+4. **Refresh the browser** after scenario 1 (db.json change may need a server restart)
+5. **Have the `demo-completed` branch ready** as a fallback for scenario 2
+6. **Point out the rules** — open `copilot-instructions.md` to show what the AI is following

docs/review-checklist.md

@@ -0,0 +1,72 @@
+# Code Review Checklist — PulseFabric Monitor
+
+Use this checklist after any AI-generated or human code change. Every item must pass before merging.
+
+---
+
+## Implementation Order
+
+- [ ] Data added to `backend/db.json` **before** any frontend code
+- [ ] DTO interface added/updated in `core/models/api.models.ts`
+- [ ] Service method added in `core/services/dashboard-api.service.ts`
+- [ ] UI component consumes data through the service (never directly)
+
+## TypeScript
+
+- [ ] No `any` type — parameters, return types, variables, generics, assertions
+- [ ] All data structures have typed interfaces
+- [ ] No `console.log`, `console.warn`, or `console.error`
+- [ ] No commented-out code blocks
+- [ ] Every import is used — no orphan imports
+- [ ] One component/service/model group per file
+- [ ] Signals used for reactive state (`signal()`, `input()`, `computed()`)
+- [ ] `inject()` used instead of constructor injection
+
+## HTML Templates
+
+- [ ] Flat structure — no unnecessary `<div>` wrappers
+- [ ] No hardcoded data in templates
+- [ ] No logic beyond simple bindings and control flow (`@if`, `@for`)
+- [ ] Material components used where appropriate (`mat-card`, `mat-icon`, etc.)
+
+## SCSS Styles
+
+- [ ] All colors use tokens: `--mat-sys-*`, `--pf-*`, or SCSS variables
+- [ ] No raw hex values (e.g., `#ff0000`)
+- [ ] No raw px/rem values — use spacing tokens (`--pf-spacing-*`)
+- [ ] Nesting depth ≤ 3 levels
+- [ ] `:host { display: block; }` present on components
+
+## File Organization
+
+- [ ] TS, HTML, SCSS in separate files (no inline templates/styles)
+- [ ] Files use `kebab-case` naming
+- [ ] Classes use `PascalCase`, variables use `camelCase`
+- [ ] Standalone component (no NgModule)
+
+## Component Design
+
+- [ ] Input-driven — data passed via `input()` signals
+- [ ] No data fetching inside the component
+- [ ] Reuses existing components where possible (KpiCard, ChartWidget, AlertList)
+- [ ] Adding a new instance requires only different inputs, not a new file
+
+## Material 3 Compliance
+
+- [ ] Uses Material 3 components from `@angular/material`
+- [ ] Follows M3 spacing and typography guidelines
+- [ ] Uses system variables for theming (`--mat-sys-*`)
+- [ ] Card components use `appearance="outlined"`
+
+## Validation
+
+- [ ] `ng build` passes with zero errors
+- [ ] No new budget warnings (echarts warning is pre-existing and acceptable)
+- [ ] App loads correctly in browser at `http://localhost:4200`
+- [ ] New feature is visible and functional
+
+## Constants & Configuration
+
+- [ ] No magic numbers — all values in named constants or enums
+- [ ] Chart colors use `PALETTE` from `chart-config.factory.ts`
+- [ ] API base URL comes from `environment.ts` (not hardcoded)