Transit-project/The-transit-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

──────
Build and Push Docker Images / detect-changes (push) Successful in 11s
Details
Build and Push Docker Images / build-auth-api (push) Successful in 1m0s
Details
Build and Push Docker Images / build-employee-api (push) Successful in 1m2s
Details
Build and Push Docker Images / build-transit-api (push) Successful in 1m1s
Details
Build and Push Docker Images / build-error-log-api (push) Successful in 1m5s
Details
Build and Push Docker Images / build-admin-ui (push) Successful in 1m13s
Details
Build and Push Docker Images / build-monitoring-ui (push) Successful in 1m15s
Details
Build and Push Docker Images / deploy-test-node (push) Successful in 3s
Details

Browse Source 
### Summary of Changes
  1. Documentation Consolidation:
      • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md,
      DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md,
      SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into .
      • Updated document links in README.md.
  2. AI Agent Project Map:
      • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB
      schemas, environment variables, and developer workflows.
      • Added PROJECT_MAP.md to .gitignore.
  3. Monitoring UI & Infrastructure Integration:
      • Added monitoring_ui service to docker-compose.yml (port 5175).
      • Configured Gitea workflow docker-build.yml for monitoring_ui builds.
      • Added CORS middleware headers in index.js.
      • Added nginx.conf copy step in Dockerfile.

  ──────
  ### Recommended Commit Message

    docs: consolidate project documentation into monitoring_ui and add agent project map

    - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/
    - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths
    - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root
    - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore
    - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow
    - Configure CORS handling in employee_api for monitoring dashboard access
    ──────
  ### Alternative Short Commit Message

    refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md
This commit is contained in:
Sven laptop
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/agents/azure-project-scaffold/references/frontend-preview-steps.md
+130
View File
@@ -0,0 +1,130 @@
<!-- azure-cor-disclaimer -->
> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
# Frontend Steps
> Detailed sub-steps for generating the standalone frontend. Read during **Step 1** (Frontend).
> **Companion contract**: Before writing any JSX, also read [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md). It defines the load-bearing contract between the plan's Section 5 (Design System & UI) and the JSX you ship — per-library region-token → primitive mapping, theming via the library's brand ramp, real icons, and the four-state coverage gate. The sub-steps below cover *how* to generate and build the frontend (working directory, build, verify); the quality bar covers *what* the frontend must contain. Design approval already happened during planning via `.azure/.preview-temp/` — Step 1 does **not** re-prompt the user for UX approval.
---
## ⚠️ ️ WORKING DIRECTORY — READ BEFORE RUNNING ANY COMMAND
**Every frontend command (scaffolder, `npm install`, `npx vite build`, `npm run build`, etc.) MUST be invoked with `cwd` set to the frontend project folder — the directory that contains the frontend's `package.json` and `index.html` (typically `services/web/`). Running these commands from the workspace root is the #1 cause of build failures.**
| ✅ Correct | ❌ Wrong |
|----------|---------|
| `run_in_terminal` with `cwd: "services/web"` and command `npx vite build` | `run_in_terminal` from workspace root running `npx vite build` |
| `run_in_terminal` with `cwd: "services/web"` and command `npm install` | `cd services/web && npx vite build` chained from another shell that was launched at root, then forgotten on the next command |
| Pass the folder explicitly every time (don't rely on a previous `cd`) | Assume the terminal is still in `services/web/` from an earlier command — the agent runs each command in a fresh shell |
**Rules:**
1. **Prefer a working-directory-independent command** for the frontend's own npm scripts: `npm --prefix <frontend-folder> run <script>` (e.g. `npm --prefix services/web run build`). `--prefix` loads the frontend's `package.json` from that folder no matter where the shell starts, so it cannot accidentally run from the workspace root.
2. When you must use a tool/binary directly (e.g. `npx vite build`), pass the frontend folder via the `cwd` parameter of `run_in_terminal` on the **same** call. Do **not** rely on a previous `cd` — each terminal invocation may start at the workspace root.
3. If the tool doesn't take a `cwd` parameter, prefix every command with `cd <frontend-folder> &&` and put it on the *same* shell call as the build command. Never split `cd` and `npx vite build` across two separate `run_in_terminal` calls.
4. The frontend folder is whatever the plan specifies — usually `services/web/`. Confirm by checking that the folder contains both `package.json` and `index.html` (or `vite.config.*`).
---
## ⚠️ Preview compatibility — the "Approve UI" iframe MUST be able to load your dev server
After scaffolding, the flow opens an **Approve UI** preview (the `open_frontend_preview_view` tool). That tool **starts your frontend's dev server for you** and renders it inside a **VS Code webview iframe**; the user clicks **Approve UI** there to continue to integration. If that iframe can't load the running app, the user is **stuck** — the app can be "live" in a normal browser window yet the preview shows a blank surface or never leaves "Starting…", and **Approve UI never enables**. Scaffold the frontend so the preview can always load it:
- **Make the dev server embeddable + reachable.** In `vite.config` set `server: { host: true, allowedHosts: true, strictPort: false }` (Angular: `ng serve --host 0.0.0.0 --disable-host-check`; Next.js: `next dev -H 0.0.0.0`). `host: true` lets the webview / forwarded port (remote, Codespaces, Dev Container, SSH) reach it; `allowedHosts: true` stops the dev server 403-blocking the forwarded/webview origin; `strictPort: false` lets the preview bind a free port instead of erroring when the default is taken. See [architecture.md](.github/agents/shared-references/architecture.md) → Frontend Dev Server Configuration.
- **Keep the `dev`/`start` script a real server.** It must launch a server that prints `http://localhost:<port>/` (plain `vite`, `next dev`, `ng serve`) — never `vite build --watch` or a build-only script. The preview waits for that URL before it enables **Approve UI**; a script that never serves leaves it on "Starting…" until it times out.
- **Never frame-bust the dev server.** No `X-Frame-Options` header from the dev server and no `<meta http-equiv="Content-Security-Policy" content="… frame-ancestors …">` in `index.html`. Those let a top-level browser tab load the app but block embedding in the webview iframe — the exact "works in my browser, blank in the preview" trap.
- **Do not run a competing dev server.** The `open_frontend_preview_view` tool owns the single dev server; the scaffold only *builds* (`npm run build`, per F4). Do **not** start your own `npm run dev`, and do **not** scaffold a VS Code task that auto-starts the dev server on folder open — a second server contends for the port, so the preview's own server can fail to bind and error out while the other server is what shows "live" in the browser.
---
## Sub-step F1: Initialize Frontend Project
| Task | Details |
|------|---------|
| Initialize frontend project | React + Vite / Vue + Vite / Angular / Svelte (per plan) |
| **Make the dev server preview-embeddable** | In `vite.config` set `server: { host: true, allowedHosts: true, strictPort: false }` (Angular: `ng serve --host 0.0.0.0 --disable-host-check`; Next.js: `next dev -H 0.0.0.0`). Keep the `dev` script a plain server (`vite`), and keep `X-Frame-Options` / `frame-ancestors` CSP out of `index.html`. This is what lets the **Approve UI** preview load your app in its webview iframe (the `/api` proxy is added later by the integrate agent). See the **Preview compatibility** callout above. |
| Create the frontend folder | Use the path the plan specifies (e.g. `services/web/`); follow the user's existing structure when one exists. Standard structure matching plan's frontend framework |
| Create local type definitions | Define entity types locally in the frontend's types folder (e.g. `services/web/src/types/`) — standalone mock types for now |
| **Define the `ApiClient` interface** | In the seam folder `services/web/src/api/types.ts`, declare an `ApiClient` interface with **one method per endpoint in the plan's API route inventory (Section 7)**, named and typed from the route contract (e.g. `listItems(): Promise<Item[]>`, `getItem(id: string): Promise<Item>`, `createItem(input: CreateItemRequest): Promise<Item>`). **Then add a method for every *other* entity any page, component, or provider renders, even when the plan has no route for it** — assignee/author lookups, the signed-in user, category or status reference lists (e.g. `listUsers(): Promise<User[]>`, `getCurrentUser(): Promise<User>`). When `API Login` is `Yes`, include the auth methods the UI needs, including `createAccount(input)`, even though the plan omits auth routes. Reference data still goes through the seam; the mock backs it at scaffold time and the integrate agent maps it to a real route or a static list later. **The interface must cover everything the UI renders** — a page that needs data the interface does not expose has no legal way to get it and will be forced to reach around the seam. This interface is the **stable seam** both the mock and the future live client implement — it is what makes integration a one-file swap. |
---
## Sub-step F2: Create the Mock Data Layer Behind the `src/api/` Seam
> **Load-bearing seam rule.** **No file outside `services/web/src/api/` imports the mock** — not pages, not hooks, not shared components, not the auth provider. They all import a single `api` object from `services/web/src/api/` (the seam). At scaffold time that `api` is backed by the mock implementation; at integrate time the integrate agent swaps **one file** (`src/api/index.ts`) to point at the live client and deletes the mock impl — **with no edits anywhere outside `src/api/`**. Anything that imported `src/mocks/` directly stops compiling the moment the mock is deleted, which is exactly what turns the one-file swap into a rewrite.
>
> **If a file needs data the `ApiClient` interface does not expose — including reference data the plan has no route for — add a method to the interface (F1) and back it with the mock. Never import the fixture.** This case is not an exemption from the rule and it is not a judgement call: extend the seam. Wire the seam exactly as below so the swap stays a single-file edit.
| Task | Details |
|------|---------|
| Create mock data files | `services/web/src/mocks/data.ts` — realistic sample data matching plan entities. **Any entity field that represents an image — `image`/`photo`/`avatar`/`cover`/`thumbnail`/`banner`/`url` on a media entity — MUST be populated with a real, loadable image URL**, never left blank, `null`, or pointing at a solid-color placeholder. Use `https://picsum.photos/seed/<stable-id>/<w>/<h>` for generic media, curated `https://images.unsplash.com/...` URLs for domain-specific imagery, and `https://i.pravatar.cc/<size>?u=<id>` for avatars. Empty media surfaces render as flat color blocks and fail the quality bar. |
| Create the mock client (an `ApiClient` impl) | `services/web/src/api/mockClient.ts` — `export const mockClient: ApiClient = { … }` implementing **every** method of the `ApiClient` interface from F1 (including the reference-data methods), returning data from `src/mocks/data.ts` with small simulated delays. It MUST satisfy the interface so it is type-interchangeable with the future live client. **Declare the mock as `ApiClient`; never derive the interface from the mock.** `export type ApiClient = typeof mockClient` inverts the seam — integrate deletes the mock, which deletes the interface with it and leaves the live client nothing to implement. |
| **Create the seam entry (the one file that swaps)** | `services/web/src/api/index.ts` — the single swap point. It contains exactly:<br>`import type { ApiClient } from './types';`<br>`import { mockClient } from './mockClient';`<br>`export const api: ApiClient = mockClient;`<br>`export type { ApiClient } from './types';`<br>At integrate time only this file changes (mock → live). Keep it this small — no logic, just the wiring line. |
| **Auto-seed auth state** | When the plan says `API Login: Yes`, the local auth state MUST auto-login with local credentials on first load (no token in storage). Preview boots directly into the main authenticated view, not a login page. Login/logout MUST still work if the user manually logs out. **Get the signed-in user from the seam (`api.getCurrentUser()`, added to the interface in F1). The auth provider follows the seam rule exactly like a page, so `import { currentUser } from '../mocks/data'` is a violation.** When `API Login: No`, do not scaffold auth state or login UI. |
| **Build the Mock State Switcher (STANDARD — always)** | Create `services/web/src/api/previewState.ts` exposing the forced `PreviewDataState` (`'data' \| 'loading' \| 'empty' \| 'error'`), initialized from the `?previewState=` query param → `localStorage['previewState']` → `'data'`. The **mock client must honor it on every method**: `loading` → never/slowly resolves; `error` → rejects with a realistic `Error`; `empty` → returns `[]` / `null`; `data` → normal fixtures. Render a small fixed-corner Data/Loading/Empty/Error switcher gated by `import.meta.env.DEV` (forced to `'data'`, no UI, in PROD). This is a fixed contract — scaffold it the same way every time. See the Mock State Switcher standard in [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md). |
| Handle all 4 data states | Loading (skeleton/spinner), Error (retry button), Empty (call-to-action), Data (populated) — all four reachable live via the Mock State Switcher above |
---
## Sub-step F3: Create Pages & Components
| Task | Details |
|------|---------|
| Create pages | One page per major feature, wired to the `api` object from the seam — `import { api } from '@/api'` (or the relative `../api`). **Never import from `src/mocks/` or `src/api/mockClient.ts` in ANY file outside `src/api/`** — not a page, not a hook, not a shared component, not the auth provider. Need an assignee name, the signed-in user, or any other reference data? Add an `ApiClient` method for it (F1) and call it through the seam. This is what keeps integration a one-file swap. |
| Create shared components | Reusable UI components (layout, nav, forms, cards) |
| Error handling in hooks | Every async hook catches errors, handles loading/error states |
| Destructive action confirmations | Delete and irreversible actions require user confirmation |
| Auth context auto-login | When `API Login` is `Yes`, AuthProvider/auth context MUST auto-login on mount when no token exists, so preview opens to main authenticated content |
| Account creation | When `API Login` is `Yes`, the login page MUST show a visible **Create account** button that routes to a dedicated create-account page. The page calls `api.createAccount(...)` through the seam and displays validation, duplicate-account, loading, and success states. This is required even though local auto-login makes the main authenticated content the initial preview. |
| Use correct file extensions | `.tsx` for JSX, `.ts` for pure TypeScript |
---
## Sub-step F4: Build & Verify the Frontend
> ⚠️ **PARALLEL STEP**: Frontend generation + build (F1–F4, sub-agent) runs **concurrently** with Phase A (Contracts) and Phase B (Backend). Backend derives from **plan's route definitions and entity types**, not the frontend — independent work streams. Phase A and Phase B may begin immediately after Step 0 (plan validation) while the Frontend sub-agent generates and builds `services/web/`.
>
> The Frontend sub-agent only needs to **generate and build** `services/web/` with mock data — it does **not** wire to the real backend. The verify agent, in a later session, swaps the seam (`src/api/index.ts`) from the mock client to the live client and replaces the local mock types with shared imports — a one-file swap at the seam, no page or hook edits.
>
> **Why safe**: Entity types, route definitions, service interfaces all come from approved plan. Frontend uses standalone mock types (`services/web/src/types/`) independent of `services/shared/`, behind the `ApiClient` seam (`src/api/`). Frontend UI changes (layout, styling, components) don't affect backend contracts. The verify agent merges both streams later by repointing the seam at the live client and replacing mock types with shared imports.
> ⚠️ ️ **WORKING DIRECTORY** (see also the top of this file): every `npx vite build`, `npm run build`, `npm install`, etc. **MUST run against the frontend folder** (e.g. `services/web/`), never the workspace root. **Prefer the working-directory-independent form `npm --prefix services/web run <script>`** (e.g. `npm --prefix services/web run build`) — it loads the frontend's `package.json` regardless of where the shell starts. When invoking a binary directly (`npx vite build`), pass `cwd: services/web` on the same terminal call; do **not** assume a previous `cd` carried over.
> ⚠️ **NO UX APPROVAL PROMPT.** The user already approved the design during planning via the HTML/CSS mock-up at `.azure/.preview-temp/`. **Do NOT call `ask_user` for "do you approve this UI?"** during scaffolding. The only legitimate user prompt during Step 1 is a hard build failure that requires their input to resolve.
### Procedure
1. **Frontend builds with zero errors.** Build with a **working-directory-independent** command so it can't accidentally run from the workspace root: `npm --prefix <frontend-folder> run build` (e.g. `npm --prefix services/web run build`). `--prefix` resolves the frontend's `package.json` regardless of where the shell starts, so it's immune to the root-launch bug. Only fall back to `npx vite build` with `cwd: <frontend-folder>` if there is no `build` script. **Never run a bare `npx vite build` from the project root.**
2. No `any` types in `.ts`/`.tsx` files.
3. When `API Login` is `Yes`, local identity state is seeded so the app lands on main content, not a login page, on first load. Logging out exposes a login page with a visible **Create account** button and a working dedicated create-account page. When it is `No`, the frontend contains no auth UI or state.
4. **Briefly note** that the frontend was generated and builds cleanly, and that backend work continues in parallel — one short sentence. **Then keep working** — no approval question, no waiting loop.
> **CRITICAL**: Do NOT prompt "Would you like to preview?" or "Do you approve this UI?" during scaffolding — design approval already happened during planning via the HTML mock-up.
### Translating the planning mock-up into real framework code
The `.azure/.preview-temp/*.html` files are a **layout + tonal reference**, not source code to ship. For each page:
- The plan's Pages table tells you which **regions** belong on the page (`header + hero + grid + footer` etc.).
- The HTML mock-up shows the **approved arrangement, density, and palette** of those regions.
- Your job in Step 1 is to reproduce that visual feel using the **real `Component Library:` primitives** from Section 6 (see [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md) for the per-library token → primitive mapping).
Do not import the HTML mock-up, embed it via `<iframe>`, or copy CSS class names from it into your JSX — the mock-up is throwaway and `.azure/.preview-temp/` is deleted in Step 11. Only the visual intent (regions, palette, density) carries forward into real components.
---
## Frontend Quality Bar
Even before it's wired to the backend, the frontend MUST meet these standards. The full per-library contract lives in [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md) — read it before writing any JSX. Baseline rules enforced here:
- No `any` types (use local type definitions in `services/web/src/types/`)
- Hooks catch errors and handle loading/error states
- Destructive actions (delete, etc.) require `window.confirm()` before executing
- `.tsx` for files containing JSX, `.ts` for pure TypeScript
- All 4 data states handled: loading, error, empty, data (see quality-bar's State Coverage Contract for per-library primitives — `<Skeleton>` / `<MessageBar intent="error">` / empty illustration + CTA / real data), and all four reachable live via the **Mock State Switcher** (dev-only `?previewState=` override — see quality-bar's Mock State Switcher standard)
- **Auto-authenticated preview**: When `API Login` is `Yes`, local auth state MUST auto-login on first load so the user sees main content immediately, not a login page
- **Render layout tokens with real library primitives** — never raw `<div className="card">` placeholders. See [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md) for the region-token → primitive mapping per library.
- **Wrap the app shell in the library's theme provider** with a brand ramp derived from plan Section 6's `primary` color. See [frontend-quality-bar.md](.github/agents/azure-project-scaffold/references/frontend-quality-bar.md) → Theming contract.
- **Use real icons** from the library's icon set (Fluent: `@fluentui/react-icons` Regular variants; Vuetify: `mdi-*`; Material: `<mat-icon>` real names; Skeleton/Pico: Lucide/Tabler). No emoji, no SVG placeholders.
.github/agents/azure-project-scaffold/references/frontend-quality-bar.md
+344
View File
@@ -0,0 +1,344 @@
<!-- azure-cor-disclaimer -->
> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
# Frontend Quality Bar — Render Layout Tokens with Real Library Primitives
> **Load this BEFORE writing any frontend page or component.** Read during **Step 1** (Frontend). This is the contract between the plan's Section 5 (Design System & UI) and the scaffolded JSX.
> **Read first:** the fidelity-agnostic **Shared design-quality principles** in [`../shared-references/frontend-quality-bar.md`](.github/agents/shared-references/frontend-quality-bar.md) — the single design contract shared by the planning preview and this scaffold. This file adds the **framework rendering layer** (per-library primitive mapping, theming, motion, dark mode) on top of those principles.
---
## Core principle
> **Layout tokens are layout INTENT, not implementation.** When the plan's Section 6 says a page's layout is `header + hero + grid + footer`, that does NOT mean produce four `<div>`s with placeholder text. It means **render the equivalent of those regions using the real `Component Library` named in Section 6, themed by the Section 6 Color Palette.**
If you ever emit JSX like this:
```tsx
// ❌ ZERO-EFFORT WIREFRAME REPRODUCTION — DO NOT SHIP
<div className="header">Header</div>
<div className="hero">Hero</div>
<div className="grid">
<div className="card">Card 1</div>
<div className="card">Card 2</div>
</div>
```
…you have failed the quality bar. That output **looks worse than the presentation-quality plan preview** the user already approved, because it strips the theme, the icons, the elevation, and the state coverage the preview shipped. The preview is a promise; this contract is how you keep it.
---
## Section 6 inputs you MUST consume
| Field in plan §5 | What it controls |
|--------------------------|--------------------------------------------------------------------------|
| `Component Library:` | Which library's primitives you import and render (mandatory). |
| `Style Direction:` | Density, corner radius, elevation, list-vs-hero bias. |
| `Typography:` | Font family applied at the app shell level. |
| Color Palette table | Brand ramp / theme tokens — wire through the library's theme provider. |
| Pages table (`Layout`) | Which **library primitives** to compose per page (see mapping below). |
| `.azure/.preview-temp/*.html` + `theme.css` | The **presentation-quality static HTML/CSS preview** the user approved during planning. It is a faithful visual spec: page regions and order, the themed palette, real inline-SVG icons, populated content, and all four data states. What it deliberately omits (raw-static limits): real webfonts, motion, working dark mode, and real photos. **Reproduce it faithfully with real library primitives and add only those production-only capabilities** (see "Polish floor" below) — never regress below it. Do not import, embed, or `<iframe>` it. Folder is deleted in Step 11. |
> If Section 6 is missing or `Component Library:` is blank, **STOP**. The plan is incomplete — re-run `azure-project-plan` instead of guessing.
---
## Per-library region-token → primitive mapping
Pick the row that matches the plan's `Component Library:` value. Every region token below MUST resolve to a real, themed library primitive — not a bare `<div>`. Compound tokens (`split(a|b)`, `two-column(a+b)`) compose two of these in a CSS Grid.
### Fluent UI v9 (`@fluentui/react-components`) — React default
| Region token | Primitive(s) to render |
|--------------|---------------------------------------------------------------------------------------------------------------------|
| `header` | `<Toolbar>` + `<Subtitle1>` (app title) + `<Link>`s + `<Avatar name=… />` on the right |
| `nav` | Horizontal `<TabList>` + `<Tab icon={<HomeRegular />}>` per route |
| `sidebar` | Vertical `<TabList vertical>` + `<Tab icon=…>` per route, with `<Divider>` between groups |
| `hero` | `<Card appearance="filled-alternative">` + `<Title3>` + `<Body1>` + `<Button appearance="primary">` |
| `main` | `<Card>` wrapper with `<CardHeader>` + body content driven by page intent |
| `list` | List of `<Card>` rows with `<CardHeader image={<Avatar />} header=… description=… />` |
| `card-list` | CSS Grid of `<Card>`s with `<CardPreview>` + `<CardHeader>` + `<CardFooter>` (real ratings / metadata, not lorem) |
| `grid` | Same as `card-list` but tighter (e.g. `repeat(auto-fill, minmax(220px, 1fr))`) |
| `form` | `<Field label=… validationState=…>` wrapping `<Input>` / `<Textarea>` / `<Combobox>` / `<Switch>` — at least one field shows `validationState="warning"` with a `validationMessage` so the four-state contract is visible |
| `table` | `<Table>` + `<TableHeader>` + `<TableHeaderCell>`s + `<TableBody>` + `<TableRow>` / `<TableCell>` (real columns) |
| `tabs` | `<TabList>` + `<Tab>`s with the first tab `selected`, second tab content as the visible body |
| `actions` / `action-bar` | `<Toolbar>` + `<ToolbarButton icon=…>`s; primary action uses `appearance="primary"` |
| `modal` | Inline `<Card>` mock (do NOT mount a real `<Dialog>` in the preview — it steals focus and breaks the screenshot) |
| `footer` | `<Divider>` + horizontal `<Caption1>` row with copyright + links |
| unknown | `<MessageBar intent="info">` saying `Unknown layout token "{token}" — will be rendered with {Component Library} in scaffold` |
**Theming**: Wrap the app shell in `<FluentProvider theme={appTheme}>` where `appTheme = createLightTheme(brandRamp)` and `brandRamp` is a 16-step `BrandVariants` derived from Section 6's `primary` color. Body font comes from Section 6's `Typography`.
**Icons**: Use real icons from `@fluentui/react-icons` (Regular variants) — never emoji and never inline SVG hand-drawn placeholders. Reasonable defaults: `HomeRegular`, `SearchRegular`, `SettingsRegular`, `PersonRegular`, `GridRegular`, `DocumentRegular`, `BookmarkRegular`, `MailRegular`, `CalendarRegular`, `ChevronDownRegular`, `AppsRegular`, `TableSimpleRegular`.
### Vuetify 3 — Vue default
| Region token | Primitive(s) to render |
|--------------|--------------------------------------------------------------------------------------------------|
| `header` | `<v-app-bar>` + `<v-app-bar-title>` + `<v-spacer>` + `<v-avatar>` |
| `nav` | `<v-tabs>` + `<v-tab prepend-icon="…">` |
| `sidebar` | `<v-navigation-drawer permanent>` + `<v-list>` + `<v-list-item prepend-icon=…>` |
| `hero` | `<v-card variant="tonal">` + `<v-card-title>` + `<v-card-text>` + `<v-btn color="primary">` |
| `main` | `<v-card>` + `<v-card-title>` + body slot |
| `list` | `<v-list>` of `<v-list-item>` with `prepend-avatar` + `title` + `subtitle` |
| `card-list` / `grid` | `<v-row>` of `<v-col cols="12" sm="6" md="4">` wrapping `<v-card>`s with `<v-img>` + `<v-card-title>` + `<v-card-actions>` |
| `form` | `<v-form>` + `<v-text-field>` / `<v-textarea>` / `<v-select>` / `<v-switch>` (at least one with `:error-messages` set) |
| `table` | `<v-data-table>` with real `headers` + `items` |
| `tabs` | `<v-tabs>` + `<v-tab>` + `<v-window>` + `<v-window-item>` |
| `actions` | `<v-toolbar density="compact">` + `<v-btn color="primary">` |
| `modal` | Inline `<v-card>` (NOT `<v-dialog>` in preview) |
| `footer` | `<v-divider />` + `<v-footer>` row |
| unknown | `<v-alert type="info">Unknown layout token "{token}"</v-alert>` |
**Theming**: Configure `vuetify({ theme: { themes: { light: { colors: { primary: '…', surface: '…', … } } } } })` from Section 6's palette.
### Angular Material — Angular default
| Region token | Primitive(s) to render |
|--------------|------------------------------------------------------------------------------|
| `header` | `<mat-toolbar color="primary">` + title + spacer + `mat-icon-button` |
| `nav` / `sidebar` | `<mat-sidenav-container>` + `<mat-sidenav mode="side" opened>` + `<mat-nav-list>` |
| `hero` | `<mat-card appearance="outlined">` + `<mat-card-title>` + `<button mat-raised-button color="primary">` |
| `list` | `<mat-list>` + `<mat-list-item>` with `<mat-icon matListItemIcon>` |
| `card-list` / `grid` | `<mat-grid-list cols="3">` + `<mat-grid-tile>` + `<mat-card>` |
| `form` | `<mat-form-field appearance="outline">` + `<input matInput>` / `<mat-select>` / `<mat-slide-toggle>` (at least one with `<mat-error>`) |
| `table` | `<table mat-table [dataSource]=…>` with `<th mat-header-cell>` + `<td mat-cell>` |
| `tabs` | `<mat-tab-group>` + `<mat-tab label=…>` |
| `actions` | `<mat-toolbar>` + `<button mat-raised-button color="primary">` |
| `modal` | Inline `<mat-card>` (NOT `<mat-dialog>` in preview) |
| `footer` | `<mat-divider>` + footer row |
| unknown | `<mat-card>` with warning icon + `Unknown layout token "{token}"` |
**Theming**: Define a Material 3 theme via `mat.define-theme(...)` using Section 6's primary as the seed color.
### Skeleton UI (Svelte default)
| Region token | Primitive(s) to render |
|--------------|--------------------------------------------------------------------------------------------------|
| `header` | `<AppBar>` with `lead`, `headline`, `trail` slots |
| `nav` | `<TabGroup>` + `<Tab>`s with `<svelte:fragment slot="lead">` icon |
| `sidebar` | `<AppRail>` + `<AppRailTile>`s, or `<AppShell sidebarLeft>` + `<nav>` + `<a class="list-item">` |
| `hero` | `<div class="card variant-glass-primary p-8">` + `<h2 class="h2">` + `<button class="btn variant-filled-primary">` |
| `list` | `<ul class="list">` + `<li>` with avatar `<Avatar>` + title + subtitle |
| `card-list` / `grid` | CSS Grid of `<div class="card">` blocks with `<header class="card-header">` + body + footer |
| `form` | `<label class="label">` + `<input class="input">` / `<textarea class="textarea">` / `<select class="select">` / `<SlideToggle>` (at least one with `input-error`) |
| `table` | `<Table source={…} />` (Skeleton) or `<table class="table table-hover">` |
| `tabs` | `<TabGroup>` + `<Tab>`s |
| `actions` | `<div class="card-footer">` + `<button class="btn variant-filled-primary">` |
| `modal` | Inline `<div class="card">` (NOT `<Modal>` in preview) |
| `footer` | `<hr class="hr">` + footer `<div>` |
| unknown | `<aside class="alert variant-ghost-surface">Unknown layout token "{token}"</aside>` |
**Theming**: Build a Skeleton theme module from Section 6's palette and set `data-theme="…"` on the root.
### Pico.css / plain HTML
| Region token | Primitive(s) to render |
|--------------|------------------------------------------------------------------------------|
| `header` | `<header><nav><ul>…</ul></nav></header>` (Pico styles `<nav>` automatically) |
| `nav` | `<nav><ul>` of `<li><a>` |
| `sidebar` | `<aside><nav>` of `<li><a>` |
| `hero` | `<article>` + `<hgroup>` + `<button>` |
| `list` / `card-list` / `grid` | `<div class="grid">` of `<article>` cards with `<hgroup>` |
| `form` | `<form>` + `<label>` + `<input>` / `<select>` / `<textarea>` (one with `aria-invalid="true"`) |
| `table` | `<figure><table>` + `<thead>` / `<tbody>` |
| `tabs` | `<nav>` of `<a role="button">` (Pico has no native tabs — flatten to nav) |
| `actions` | `<footer><button class="primary">` |
| `modal` | Inline `<dialog open>` (rendered, not toggled) |
| `footer` | `<footer>` with small text |
| unknown | `<mark>Unknown layout token "{token}"</mark>` |
**Theming**: Set CSS custom properties (`--pico-primary`, `--pico-background-color`, `--pico-color`, `--pico-muted-color`) from Section 6's palette on `:root` or `[data-theme=light]`.
---
## State coverage contract (every data-bearing page)
Every page that displays data MUST cover all four states with real library primitives — not text-only fallbacks:
| State | Fluent UI v9 | Vuetify 3 | Angular Material | Skeleton | Pico |
|----------|-----------------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------------------------|------------------------------------|
| loading | `<Skeleton>` + `<SkeletonItem>` rows | `<v-skeleton-loader type="card">` | `<ngx-skeleton-loader>` or `<mat-progress-bar>` | `<div class="placeholder animate-pulse">` | `<progress indeterminate>` |
| error | `<MessageBar intent="error">` + retry `<Button>` | `<v-alert type="error">` + retry `<v-btn>` | `<mat-card>` + `<mat-icon>error</mat-icon>` + retry button | `<aside class="alert variant-filled-error">` + retry | `<article><mark>` + retry `<button>` |
| empty | `<Card>` with illustration + `<Body1>` + primary `<Button>` CTA | `<v-empty-state>` or `<v-card>` with `<v-icon>` + `<v-btn>` CTA | `<mat-card>` + `<mat-icon>` + primary action | `<div class="card">` + icon + primary CTA `<button>` | `<article>` + `<p>` + primary `<button>` |
| data | Real list/grid/table from mock fixtures | Real list/grid/table | Real list/grid/table | Real list/grid/table | Real list/grid/table |
> The four states MUST be reachable in the running app — wire a small dev-only toggle (URL hash, query param, or a corner button gated by `import.meta.env.DEV`) so `loading`, `error`, `empty`, and `data` can each be exercised. The toggle is the verification path for the four-state contract.
---
## Theming contract
1. **Build a brand ramp from Section 6's `primary`** and pass it to the library's theme provider — do **not** ship the library's default brand color.
- Fluent UI v9: `createLightTheme(brandRamp)` where `brandRamp: BrandVariants` is a 16-step ramp from HSL lightening/darkening of `primary`.
- Vuetify: `theme.themes.light.colors.primary`.
- Angular Material: `mat.define-theme({ color: { primary: $palette } })`.
- Skeleton: custom theme module with `--color-primary-*` CSS variables.
- Pico: `--pico-primary` CSS variable.
2. **Map `surface` / `text` / `muted` / `border`** onto the library's neutral tokens — do not hard-code colors in component JSX. Semantic states (success / warning / error) come from the library's built-in semantic tokens, not from the plan palette.
3. **Apply `Typography`** at the app shell level (Fluent: `FluentProvider` style override; Vuetify: `<v-app>` font-family; Angular: `--mat-sys-body-large-font`; Skeleton: theme module; Pico: `:root { font-family: … }`).
4. The plan-preview webview renders a sandboxed **HTML/CSS** preview — purely presentational, no JavaScript, no real component library involved. Each page lives at `.azure/.preview-temp/<slug>.html` and shares a single `.azure/.preview-temp/theme.css`. Treat those files as a **presentation-quality visual spec** — approved regions, themed palette, real icons, populated content, and all four states. Reproduce that look with real library primitives and **add the production-only capabilities the static files could not include**: real webfont, motion, dark mode, and real imagery. Do not import, embed, or `<iframe>` the preview. `.azure/.preview-temp/` is deleted in Step 11.
---
## Quality gate (run this checklist before claiming the preview is ready)
- [ ] Every page imports primitives from the library named in Section 6 — **zero raw `<div className="card">` / `<div className="header">` placeholders** outside the layout grid wrappers.
- [ ] App shell is wrapped in the library's theme provider; brand ramp is derived from Section 6 `primary`.
- [ ] Every icon is a real library icon (Fluent: `*Regular` from `@fluentui/react-icons`; Material: `<mat-icon>name</mat-icon>` with real names; Vuetify: `mdi-*`; Skeleton/Pico: native SVG icons via a real icon set such as Lucide or Tabler). **No emoji, no `<svg viewBox="0 0 1 1">` placeholders.**
- [ ] Every `form` region has at least one field with a visible validation state (warning/error) and an inline message.
- [ ] Every data-bearing page exposes all four states (loading / error / empty / data) via a dev-only toggle.
- [ ] `Style Direction:` is reflected in density and corner radius (e.g. "data-dense" → compact toolbars, tight list rows; "calm and spacious" → generous padding, larger cards).
- [ ] No `any` types; the four-state contract still holds; locally seeded identity works when `API Login` is `Yes`, and no auth UI exists when it is `No`.
- [ ] When `API Login` is `Yes`, logging out reveals a visible **Create account** button on the login page, and that button opens a complete create-account page with validation and error states.
- [ ] The scaffolded UI **reproduces the approved preview at `.azure/.preview-temp/<slug>.html` and adds the production-only layer** — same regions, same brand color, same density and populated content, now with real library primitives, real webfont, motion, dark mode, and real imagery the static preview could not include. If a generated page looks **less** polished than the preview, the page has failed the bar.
---
## Polish floor — every scaffolded app, regardless of library
These eight requirements are **non-negotiable**. They are the gap between "the sketch with components swapped in" and "an app the user wants to ship". A page that misses any of them fails the bar.
### 1. Hero treatment (every landing / dashboard / list-index page)
A flat colored panel is **not** a hero. Every hero region MUST have:
- A **brand-gradient card** (linear or radial) using two stops from Section 6's palette (typically `primary` → `accent`, or `primary` → a 12-step-lighter `primary`).
- An **eyebrow line** above the headline: uppercased, letter-spaced ~0.12em, ~11–12px, with a 6px dot prefix — distinct from the headline.
- A **headline** at the library's `display`/`Title1`/`h1` token, max-width ~24ch, line-height ~1.1, sub-tight letter-spacing.
- A **subtitle** at the body token, max-width ~60ch, opacity 0.85–0.95.
- **Two CTAs**: a primary library button (named action, see microcopy below) + a secondary/ghost variant.
- An **ambient SVG mesh backdrop** layered behind the gradient. Concrete pattern:
```tsx
<svg className="hero-mesh" aria-hidden="true" viewBox="0 0 800 400" preserveAspectRatio="none">
<defs>
<radialGradient id="m1" cx="0%" cy="0%" r="80%">
<stop offset="0%" stopColor="var(--brand-accent)" stopOpacity="0.55" />
<stop offset="100%" stopColor="var(--brand-accent)" stopOpacity="0" />
</radialGradient>
<radialGradient id="m2" cx="100%" cy="100%" r="80%">
<stop offset="0%" stopColor="var(--brand-primary)" stopOpacity="0.55" />
<stop offset="100%" stopColor="var(--brand-primary)" stopOpacity="0" />
</radialGradient>
</defs>
<rect width="800" height="400" fill="url(#m1)" />
<rect width="800" height="400" fill="url(#m2)" />
</svg>
```
Position the SVG `position: absolute; inset: 0; pointer-events: none; opacity: 0.7;`. Layer the gradient panel above it. The `aria-hidden` is required.
### 2. Real icons — everywhere (no exceptions)
Every navigation item, sidebar item, KPI tile, empty state, primary CTA, and section title row MUST carry a real, named icon from the library's official icon set:
| Library | Icon source | Concrete sample imports |
|------------------|-----------------------------------|--------------------------------------------------------------------------------------------------|
| Fluent UI v9 | `@fluentui/react-icons` Regular | `HomeRegular`, `SearchRegular`, `SettingsRegular`, `PersonRegular`, `GridRegular`, `BookmarkRegular`, `ChevronRightRegular`, `AddRegular`, `DocumentRegular`, `InboxRegular`, `CalendarRegular`, `ChartMultipleRegular` |
| Vuetify 3 | Material Design Icons (`mdi-*`) | `mdi-home`, `mdi-magnify`, `mdi-cog`, `mdi-account`, `mdi-view-dashboard`, `mdi-bookmark`, `mdi-chevron-right`, `mdi-plus`, `mdi-file-document`, `mdi-inbox`, `mdi-calendar`, `mdi-chart-line` |
| Angular Material | Material Symbols / `mat-icon` | `home`, `search`, `settings`, `person`, `dashboard`, `bookmark`, `chevron_right`, `add`, `description`, `inbox`, `calendar_today`, `show_chart` |
| Skeleton (Svelte)| Lucide-Svelte | `Home`, `Search`, `Settings`, `User`, `LayoutGrid`, `Bookmark`, `ChevronRight`, `Plus`, `FileText`, `Inbox`, `Calendar`, `LineChart` |
| Pico | Lucide (`lucide-static` or `lucide` web) | Same Lucide names above; render via inline SVG or `<i data-lucide="home">` |
**Hard fail**: emoji (🏠, 📊), Unicode glyphs (▲, ★), or hand-drawn `<svg>` shapes used as nav/section/CTA iconography.
### 3. Motion (lightweight, library-aligned)
Every app MUST add motion in three places, with `prefers-reduced-motion` respected:
| Library | Motion tool | Where it must appear |
|------------------|---------------------------------------|-------------------------------------------------------------------------------|
| Fluent UI v9 | `framer-motion` or `motion/react` | Route change (fade+12px slide), card hover (1–2px lift), dialog/popover open |
| Vuetify 3 | `@vueuse/motion` or built-in `<v-fade-transition>` / `<v-slide-y-transition>` | Route change, card hover, dialog open |
| Angular Material | Angular Animations (`@angular/animations`) | Route change (`fadeInUp`), card hover, dialog open |
| Skeleton | Svelte built-in `transition:fade` / `crossfade` | Route change, card hover, drawer open |
Duration: 150–300ms. Easing: `cubic-bezier(0.4, 0, 0.2, 1)` or library default. Wrap all motion in a `prefers-reduced-motion: reduce` media query / `useReducedMotion()` hook — no exceptions.
### 4. All four states — visibly, with library illustrations
The state contract in the table above is the **minimum**. Every empty state MUST also include a real visual element (library illustration component, Lucide/Tabler icon at 64–96px, or a domain-specific SVG), not just text:
- Fluent: empty card with a 64px `*Regular` icon centered above the `<Title3>` + body + primary CTA.
- Vuetify: `<v-empty-state>` (built-in, has illustration slot) or `<v-card>` with `<v-icon size="64">`.
- Angular Material: `<mat-card>` with a `<mat-icon style="font-size: 64px; width: 64px; height: 64px;">`.
- Skeleton: `<div class="card">` with `<Inbox size={64} />` (Lucide) above text.
### 5. Density + radius derived from Style Direction
Translate the `Style Direction:` literal from Section 6 into concrete library tokens:
| Style Direction keyword | Density / radius / weight choices |
|---------------------------------|--------------------------------------------------------------------------------|
| `playful`, `friendly`, `consumer` | Large radii (12–20px on cards, full-pill on buttons), comfortable padding, heavier headlines (700+), saturated palette |
| `professional`, `enterprise`, `serious` | Small radii (4–8px), compact padding, semibold headlines (600), muted palette |
| `editorial`, `magazine`, `content-led` | Mixed radii (cards 4px, hero 0–4px), generous whitespace, large display type, serif option for headings |
| `minimal`, `calm`, `data-dense` | Tight radii (2–6px), compressed padding, regular weight body, restrained palette, hairline 1px borders |
Wire these through the library's density/spacing/radius tokens (Fluent: `tokens.borderRadiusMedium`; Vuetify: `density="compact"` + theme `defaults`; Material: M3 density CSS vars; Skeleton: theme module radius variables).
### 6. Dark mode (required, with persistence)
Every app ships with light + dark themes from day one:
- A theme toggle in the header (uses the library's icon button).
- Persistence via `localStorage` key `app-theme` (`'light' | 'dark' | 'system'`).
- Initial value reads `prefers-color-scheme` when key is missing or set to `'system'`.
- Live update on `matchMedia('(prefers-color-scheme: dark)').addEventListener('change', …)` while in `'system'` mode.
- Both themes derive from the **same** Section 6 brand palette — only neutrals and surfaces flip.
### 7. Real webfont, mapped from Style Direction
Apply a webfont via the `<head>` (CSS `@import` or `<link>`) and wire it through the library's font token. Choose by Style Direction:
| Style Direction keyword | Webfont |
|---------------------------------|------------------------------------|
| `playful`, `friendly` | `Inter` (variable) or `Geist Sans` |
| `professional`, `enterprise` | `Inter` or `IBM Plex Sans` |
| `editorial`, `magazine` | `Source Sans 3` body + `Source Serif 4` headings |
| `minimal`, `calm`, `data-dense` | `Geist Sans` or `IBM Plex Sans` |
Load via `<link rel="preconnect">` + `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=…">` or self-host. Fall back to `system-ui, -apple-system, "Segoe UI", sans-serif`.
### 8. Microcopy — primary CTAs name the action
Primary buttons MUST name the action being committed. **Hard fail**: generic verbs.
| ❌ Generic (fails) | ✅ Named (passes) |
|----------------------|-------------------------------------------------------------------|
| `Submit` | `Save changes`, `Create project`, `Send invite`, `Publish post` |
| `OK` | `Got it`, `Acknowledge`, `Mark as read` |
| `Continue` | `Continue to billing`, `Review and confirm` |
| `Delete` | `Delete project permanently`, `Remove from team` |
Secondary/ghost buttons may be generic (`Cancel`, `Back`). Modal confirm buttons follow the same rule (`Delete 3 items` not `Confirm`).
### 9. Imagery & art direction (domain fit beats stock chrome)
A page can pass items 1–8 and still look templated if it renders empty media surfaces and identical generic cards for every app. Every app MUST:
- **Render real images for every media-bearing entity.** Bind the mock data's image URL (see Sub-step F2) into a real `<img>` / Fluent `<CardPreview image>` / Vuetify `<v-img>` / Angular `mat-card-image` / Skeleton-Pico `<img>` — **never** an empty tinted `<CardPreview>` or a solid-color `<div>` standing in for a photo. A media card with no visible photo is a hard fail.
- **Match the domain's visual idiom.** A photo-sharing app reads as a gallery (edge-to-edge imagery, scrapbook/polaroid framing, captions), a finance app as data-dense tables, an editorial app as a magazine, a chat app as message bubbles. Do not flatten every app into the same generic SaaS card grid.
- **Use bespoke, domain-specific component treatments** — tilted polaroid frames, ticket stubs, chat bubbles, kanban cards, gallery tiles, etc. — **layered on top of** the library primitives from the region-token mapping. This is encouraged, not forbidden (see self-review item 12). The ban is only on empty placeholder `<div>`s that re-skin the wireframe, never on art direction that fits the domain.
---
## Polish self-review checklist (per page, before marking complete)
Run through this 12-item yes/no list for **each page** generated. A "no" on any item means the page is not done. Do not move on.
1. Does the hero use a brand gradient (not flat color) with eyebrow + headline + subtitle + 2 CTAs + ambient SVG mesh backdrop?
2. Does every nav/sidebar item carry a real named icon from the library's icon set (not emoji, not glyph)?
3. Does every KPI tile / section-title row / empty state / primary CTA carry a real icon?
4. Is there at least one motion: route change, card hover, OR dialog/popover open, wired through the library's motion tool, with `prefers-reduced-motion` respected?
5. For data-bearing pages: are all four states (loading / error / empty / data) reachable via a dev toggle, and does the empty state include a 64–96px icon or illustration (not just text)?
6. Is dark mode wired through a header toggle, persisted in `localStorage`, with a `prefers-color-scheme` initial read?
7. Is a real webfont loaded via `<link>` / `@import` and applied through the library's font token?
8. Do density + corner radius tokens reflect Section 6's `Style Direction:` (playful → larger radii; professional → tighter)?
9. Do all primary CTAs name the action (`Save changes`, `Create project`) — no generic `Submit` / `OK` / `Continue`?
10. Is the brand ramp derived from Section 6's `primary` (16-step / theme-provider-driven), with both themes sharing it?
11. Does the page **match or exceed** the approved static preview — same regions and content, now with real library elevation, motion, real webfont, and real imagery — so a reviewer comparing them would say "yes, this is the preview, brought to life" (never "this looks worse than the mock")?
12. Does every region **resolve to a real library primitive** (no zero-effort `<div className="card">Card 1</div>` wireframe stubs)? Bespoke, domain-styled components (polaroid frames, ticket stubs, gallery tiles, chat bubbles) are **encouraged** as long as they wrap or extend a real library primitive and carry real content + imagery — the ban is on empty placeholder `<div>`s that merely re-skin the wireframe, not on domain art direction.
13. Does every media-bearing entity render a **real image** (from the mock data's image URL), not an empty tinted surface or solid-color block?
.github/agents/azure-project-scaffold/references/sub-agent-strategy.md
+87
View File
@@ -0,0 +1,87 @@
<!-- azure-cor-disclaimer -->
> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
# Sub-Agent Strategy for Backend Scaffolding
> Parallelization strategy for backend scaffold execution. Read when transitioning from **Step 1** to backend implementation.
---
## Execution Model
> ⚠️ **PIPELINING**: The **Frontend sub-agent** (Step 1) and the backend track both begin **immediately after Step 0** (plan validation) and run **concurrently**. Phase A (Contracts) and Phase B (Backend) derive from the plan, not the frontend, so neither track blocks the other. For API-only projects (no frontend), the Frontend sub-agent is skipped and backend scaffolding proceeds immediately after Step 0.
>
> **Execution timeline for SPA + API projects:**
> ```
> Step 0 (Plan Validated)
> ├── Frontend Sub-Agent (F1–F4: generate + build) ──> returns ──────────────────────────┐
> └── Phase A: Contracts (sequential) ──> Phase B: Backend Sub-Agent ────────────────────┤
> ▼
> Step 11: Wrap Up
> ```
>
> The Frontend sub-agent generates + builds + verifies `services/web/` (F1–F4) and hands back.
---
## Frontend Sub-Agent (parallel with backend)
Launched right after Step 0 (concurrently with Phase A/B). Owns frontend generation and build.
| Sub-Agent | Responsibility | Scope |
|-----------|---------------|-------|
| **Frontend Agent** (general-purpose) | Generate `services/web/`: the `ApiClient` seam (`src/api/` — interface + mock impl + one-line `index.ts` swap point) backed by a mock data layer with real images (F1–F2), pages + shared components that import only the seam `api` object (F3), login UI plus locally seeded identity when `API Login` is `Yes`, and all four data states. Login-enabled frontends MUST include a visible **Create account** button on the login page and a dedicated create-account page wired through `api.createAccount(...)`. When `API Login` is `No`, generate no auth UI or state. **The `ApiClient` interface must cover every entity the UI renders, including reference data the plan has no route for (assignee lookups, the signed-in user) — nothing outside `src/api/` may import `src/mocks/`.** Apply the Rule 13 quality bar + Polish floor. Run the frontend build gate (`npm --prefix services/web run build`, zero errors, no `any`) (F4). | Step 1 sub-steps **F1–F4** |
**Brief handed to the sub-agent** (full context it receives):
- The approved plan, especially **Section 6 (Design System & UI)**: `Component Library:`, `Style Direction:`, `Typography:`, Color Palette, Pages table.
- The approved HTML preview under `.azure/.preview-temp/` (manifest + per-page `<slug>.html` + `theme.css`) as the presentation-quality visual spec.
- The three frontend reference docs: `frontend-quality-bar.md`, `frontend-patterns.md`, `frontend-preview-steps.md`.
**Hand-back contract** (what the sub-agent returns):
- `services/web/` generated and **building cleanly** (it ran the F1–F4 checkpoints: build passes, no `any`, API Login behavior matches the plan, login-enabled apps have the required create-account button and page, four states present, Rule 13 satisfied).
- A short report listing the pages generated and any caveats.
- It MUST NOT call `ask_user` for UX approval — the design was already approved during planning.
---
## Phase A: Contracts First (BLOCKING — Sequential, No Parallelism)
Create sequentially — dependencies for everything else:
1. Shared types (`services/shared/types/`)
2. Validation schemas (`services/shared/schemas/`)
3. Service interfaces (`services/functions/src/services/interfaces/`)
4. Error types (`services/functions/src/errors/`)
5. Config module (`services/functions/src/services/config.ts`)
Build shared package to produce `dist/`. Verify cross-workspace imports resolve.
---
## Phase B: Parallel Implementation via Sub-Agents
Once contracts exist on disk, launch backend sub-agent:
| Sub-Agent | Responsibility | Scope |
|-----------|---------------|-------|
| **Backend API Agent** (general-purpose) | Concrete service implementations, service registry, function handlers, OpenAPI spec, structured logging | Steps 3–10 implementation files |
> **NOTE**: Testing is NOT part of the scaffold phase. Test infrastructure, mocks, fixtures, and unit tests are out of scope — the scaffold produces correct, buildable production code only. Keeping tests out of scaffold ensures the production code stays focused and is not buried under test scaffolding.
---
## Coordination Rules
- The **Frontend Agent** and the backend track (Phase A → Phase B) launch together after Step 0 and run concurrently.
- The **Backend API Agent** receives the full project plan and the contracts created in Phase A as context.
- After the Backend agent completes, run the final build gate (`npm run build` in all workspaces).
- The scaffold does **not** start a dev server or open Simple Browser — the frontend is generated and built only; running it locally is out of scope for scaffolding.
- **Completion gate**: Step 11 (Wrap Up) writes the hand-off artifact only after BOTH: (a) frontend generated and building cleanly — the Frontend sub-agent returned — AND (b) Phase B backend agent completed. If one track finishes first, wait for the other.
- Then proceed to Step 11 (Wrap Up)
---
## Key Contract Rules
- Agent MUST use same `AppConfig` shape (flat structure — see [../../shared-references/service-abstraction.md](.github/agents/shared-references/service-abstraction.md))
- Agent MUST use same collection names (`'user'`, `'couple'`, etc.) mapping to SQL table names
- Agent MUST use same validation schema names exported from `services/shared/schemas/validation.ts`
.github/agents/azure-project-scaffold/references/testing.md
+576
View File
@@ -0,0 +1,576 @@
<!-- azure-cor-disclaimer -->
> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
# Testing Patterns
> Core reference for self-testable north star. Every module ships with tests. Every phase has test gate.
---
## Core Principle
**Project is not done until tests say it is.**
Agent runs tests after every module. If tests fail, agent iterates until they pass. No module complete until tests green. Not a suggestion — it's workflow.
---
## Test Pyramid
```
┌─────────────┐
│ E2E / │ ← Full request-response cycle
│ Integration │ with real/mock services
├──────────────┤
│ │
│ Unit │ ← Fast, isolated, mocked deps
│ │
└──────────────┘
```
| Layer | What It Tests | Dependencies | Speed | When |
|-------|---------------|-------------|-------|------|
| **Unit** | Single function/class in isolation | All deps mocked | Fast (ms) | Every module, always |
| **Integration** | Request → handler → service → response cycle | Mock services injected | Fast (ms) | Every route, always |
| **E2E** | Full stack with real emulators | Running emulators (via azure-debug-plan) | Slower (s) | When emulators are available |
### What Each Layer Covers
**Unit Tests** (mandatory for every module):
- Service abstraction methods (with mock storage/DB/cache)
- Config loading (env vars present, missing, defaults)
- Validation schemas (valid input, invalid input, edge cases)
- Error types and error handler (mapping to HTTP status codes)
- Individual function handler logic (with injected mock services)
- Utility functions and helpers
**Integration Tests** (mandatory for every route):
- HTTP request → function handler → mock service → HTTP response
- Correct status codes (200, 201, 400, 404, 422, 500)
- Correct response body shapes
- Request validation (bad input rejected)
- Error handling (service failures produce correct error responses)
**E2E Tests** (when emulators available via azure-debug-plan):
- Full DB round-trip (create → read → verify data)
- File upload → storage → retrieval
- Cache set → get → verify
- Health check with live services
---
## Test Runner Quick Reference
### Node.js (TypeScript)
| Runner | Setup | Config File | Test Command | Mock Library | Assertion Library |
|--------|-------|-------------|-------------|-------------|------------------|
| **vitest** | `npm i -D vitest` | `vitest.config.ts` | `npx vitest run` | Built-in `vi.mock()` | Built-in `expect` |
| **jest** | `npm i -D jest ts-jest @types/jest` | `jest.config.ts` | `npx jest` | Built-in `jest.mock()` | Built-in `expect` |
| **mocha+chai+sinon** | `npm i -D mocha chai sinon @types/mocha @types/chai @types/sinon tsx` | `.mocharc.yml` | `npx mocha` | sinon | chai `expect` |
#### vitest config example
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true,
environment: 'node',
include: ['tests/**/*.test.ts'],
coverage: {
provider: 'v8',
include: ['src/**/*.ts'],
exclude: ['src/**/interfaces/**']
}
}
});
```
#### jest config example
```typescript
// jest.config.ts
export default {
preset: 'ts-jest',
testEnvironment: 'node',
roots: ['<rootDir>/tests'],
testMatch: ['**/*.test.ts'],
collectCoverageFrom: ['src/**/*.ts', '!src/**/interfaces/**']
};
```
#### mocha config example
```yaml
# .mocharc.yml
require:
- tsx
spec: 'tests/**/*.test.ts'
recursive: true
timeout: 5000
```
### .NET
| Runner | Setup | Config | Test Command | Mock Library | Assertion |
|--------|-------|--------|-------------|-------------|-----------|
| **xUnit** | NuGet: `xunit`, `xunit.runner.visualstudio`, `Microsoft.NET.Test.Sdk` | `.csproj` | `dotnet test` | Moq or NSubstitute | xUnit `Assert` or FluentAssertions |
| **NUnit** | NuGet: `NUnit`, `NUnit3TestAdapter`, `Microsoft.NET.Test.Sdk` | `.csproj` | `dotnet test` | Moq or NSubstitute | NUnit `Assert` or FluentAssertions |
---
## Mock Data Patterns
### Fixture Files (JSON)
Store realistic mock data in `tests/fixtures/`:
```json
// tests/fixtures/items.json
{
"validItems": [
{
"id": "item-001",
"name": "Widget Alpha",
"description": "A high-quality widget for testing",
"price": 29.99,
"category": "widgets",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
},
{
"id": "item-002",
"name": "Gadget Beta",
"description": "An innovative gadget",
"price": 49.99,
"category": "gadgets",
"createdAt": "2026-02-20T14:00:00.000Z",
"updatedAt": "2026-03-01T09:15:00.000Z"
}
],
"invalidItems": [
{ "name": "", "description": "Missing name" },
{ "name": "X", "price": -5, "description": "Invalid price" },
{ "description": "No name field at all" }
],
"createItemRequest": {
"name": "New Widget",
"description": "A brand new widget",
"price": 19.99,
"category": "widgets"
}
}
```
### Factory Functions
For dynamic mock data, use factory functions:
```typescript
// tests/fixtures/itemFactory.ts
import { Item, CreateItemRequest } from '../../services/shared/types/entities';
let counter = 0;
export function createMockItem(overrides?: Partial<Item>): Item {
counter++;
return {
id: `item-${counter.toString().padStart(3, '0')}`,
name: `Test Item ${counter}`,
description: `Description for test item ${counter}`,
price: 9.99 + counter,
category: 'test',
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
...overrides
};
}
export function createMockCreateRequest(overrides?: Partial<CreateItemRequest>): CreateItemRequest {
counter++;
return {
name: `New Item ${counter}`,
description: `New item description ${counter}`,
price: 19.99,
category: 'test',
...overrides
};
}
```
### C# Fixtures
```csharp
// Fixtures/ItemFixtures.cs
public static class ItemFixtures
{
public static Item CreateValidItem(string? id = null) => new()
{
Id = id ?? Guid.NewGuid().ToString(),
Name = "Test Widget",
Description = "A test widget",
Price = 29.99m,
Category = "widgets",
CreatedAt = DateTime.UtcNow,
UpdatedAt = DateTime.UtcNow
};
public static CreateItemRequest CreateValidRequest() => new()
{
Name = "New Widget",
Description = "A brand new widget",
Price = 19.99m,
Category = "widgets"
};
public static List<Item> CreateItemList(int count = 5) =>
Enumerable.Range(1, count)
.Select(i => CreateValidItem($"item-{i:D3}"))
.ToList();
}
```
---
## Service Mocking Patterns
### TypeScript — vitest
```typescript
// tests/mocks/mockDatabase.ts
import { IDatabaseService } from '../../src/services/interfaces/IDatabaseService';
import { Item } from '../../services/shared/types/entities';
export function createMockDatabase(initialData: Item[] = []): IDatabaseService {
const store = new Map<string, Item>();
initialData.forEach(item => store.set(item.id, item));
return {
findAll: async () => Array.from(store.values()),
findById: async (id: string) => store.get(id) ?? null,
create: async (item: Item) => { store.set(item.id, item); return item; },
update: async (id: string, data: Partial<Item>) => {
const existing = store.get(id);
if (!existing) return null;
const updated = { ...existing, ...data, updatedAt: new Date().toISOString() };
store.set(id, updated);
return updated;
},
delete: async (id: string) => { return store.delete(id); },
healthCheck: async () => true
};
}
```
```typescript
// tests/functions/getItems.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createMockDatabase } from '../mocks/mockDatabase';
import { createMockItem } from '../fixtures/itemFactory';
describe('getItems', () => {
let mockDb: IDatabaseService;
const testItems = [createMockItem(), createMockItem()];
beforeEach(() => {
mockDb = createMockDatabase(testItems);
});
it('should return all items', async () => {
const items = await mockDb.findAll();
expect(items).toHaveLength(2);
});
it('should return empty array when no items', async () => {
mockDb = createMockDatabase([]);
const items = await mockDb.findAll();
expect(items).toEqual([]);
});
});
```
### TypeScript — mocha + chai + sinon
```typescript
// tests/functions/getItems.test.ts
import { expect } from 'chai';
import sinon from 'sinon';
import { createMockDatabase } from '../mocks/mockDatabase';
import { createMockItem } from '../fixtures/itemFactory';
describe('getItems', () => {
let mockDb: IDatabaseService;
const testItems = [createMockItem(), createMockItem()];
beforeEach(() => {
mockDb = createMockDatabase(testItems);
});
afterEach(() => {
sinon.restore();
});
it('should return all items', async () => {
const items = await mockDb.findAll();
expect(items).to.have.lengthOf(2);
});
it('should return empty array when no items', async () => {
mockDb = createMockDatabase([]);
const items = await mockDb.findAll();
expect(items).to.deep.equal([]);
});
});
```
### C# — xUnit + Moq
```csharp
// Functions/GetItemsTests.cs
public class GetItemsTests
{
private readonly Mock<IDatabaseService> _mockDb;
public GetItemsTests()
{
_mockDb = new Mock<IDatabaseService>();
}
[Fact]
public async Task GetItems_ReturnsAllItems()
{
var items = ItemFixtures.CreateItemList(3);
_mockDb.Setup(db => db.FindAllAsync()).ReturnsAsync(items);
var result = await _mockDb.Object.FindAllAsync();
Assert.Equal(3, result.Count);
}
[Fact]
public async Task GetItems_ReturnsEmptyList()
{
_mockDb.Setup(db => db.FindAllAsync()).ReturnsAsync(new List<Item>());
var result = await _mockDb.Object.FindAllAsync();
Assert.Empty(result);
}
}
```
---
## Test Gate Enforcement
Agent MUST follow this workflow at every test gate:
### 1. Run Tests
```bash
# TypeScript
npm test
# or: npx vitest run
# or: npx jest
# or: npx mocha
# .NET
dotnet test
```
### 2. Parse Output
Look for:
- **Pass**: All tests passed, zero failures → proceed to next phase
- **Fail**: One or more tests failed → DO NOT proceed
### 3. If Tests Fail
1. Read failure output — identify which test failed and why
2. Determine if issue is in **code** or **test**
3. Fix issue
4. Re-run tests
5. Repeat until ALL tests pass
### 4. If Tests Pass
1. Update the plan's `Status:` field in `.azure/project-plan.md` if the phase advances it
2. Proceed to next phase
### Decision Tree
```
Run tests
│
├── ALL PASS ──→ Mark phase complete → Proceed to next phase
│
└── ANY FAIL ──→ Read failure output
│
├── Code bug ──→ Fix code → Re-run tests
│
├── Test bug ──→ Fix test → Re-run tests
│
└── Missing dep ──→ Install dep → Re-run tests
```
> **NEVER skip a test gate.** If you cannot get tests to pass after reasonable effort, report failure to user rather than silently proceeding.
---
## Coverage Guidance
**Do not set hard coverage thresholds.** Instead, ensure:
- Every function handler has at least one happy-path test and one error-path test
- Every service method is tested via mock implementations
- Every validation schema has valid/invalid input tests
- Every error type is tested for correct HTTP status mapping
- Edge cases are covered (empty arrays, null values, boundary numbers, special characters)
The goal is **meaningful coverage**, not a percentage target.
---
## Test Naming Conventions
Use descriptive test names that document behavior:
```
✅ "should return 200 with list of items when items exist"
✅ "should return 404 when item ID does not exist"
✅ "should return 422 when name is empty string"
✅ "should return 500 when database connection fails"
❌ "test1"
❌ "getItems test"
❌ "works"
```
### Convention by Runtime
| Runtime | Pattern | Example |
|---------|---------|---------|
| TypeScript | `it('should {behavior} when {condition}')` | `it('should return 404 when item not found')` |
| C# | `{Method}_{Condition}_{Expected}` | `GetItemById_ItemNotFound_Returns404()` |
---
## Frontend Testing
> The frontend has its own build gate at Step 1 (F4). These patterns ensure the frontend is tested as rigorously as the backend.
### Minimum Test Coverage
Every frontend generated by this skill must include tests for:
| Category | What to Test | Why |
|----------|-------------|-----|
| **Auth flow** | Login success, login failure, logout, token expiry redirect | Auth is the security boundary |
| **Protected routes** | Unauthenticated user redirected to /login | Ensures route protection works |
| **Data display** | List renders items from mock API data | Core feature verification |
| **Error states** | Error message shown when API returns error | Users must see failures |
| **Form validation** | Invalid input shows feedback before submit | UX quality |
| **Destructive actions** | Delete shows confirmation before executing | Data safety |
### Test Setup Pattern (React + Vitest)
```typescript
// tests/setup.ts
import '@testing-library/jest-dom';
import { vi } from 'vitest';
// Mock fetch globally for all frontend tests
global.fetch = vi.fn();
// Helper to mock a successful API response
export function mockFetchSuccess(body: unknown, status = 200) {
(global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
ok: true,
status,
json: async () => body,
});
}
// Helper to mock an API error response
export function mockFetchError(status: number, error: { code: string; message: string }) {
(global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
ok: false,
status,
json: async () => ({ error: { ...error, details: null } }),
});
}
```
### Component Test Pattern
```typescript
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter } from 'react-router-dom';
import { mockFetchSuccess, mockFetchError } from '../setup';
describe('ItemListPage', () => {
it('renders items from API', async () => {
const mockItems = [
{ id: '1', name: 'Widget', price: 9.99 },
{ id: '2', name: 'Gadget', price: 19.99 },
];
mockFetchSuccess({ items: mockItems, total: 2 });
render(<MemoryRouter><ItemListPage /></MemoryRouter>);
await waitFor(() => {
expect(screen.getByText('Widget')).toBeInTheDocument();
expect(screen.getByText('Gadget')).toBeInTheDocument();
});
});
it('shows error when API fails', async () => {
mockFetchError(500, { code: 'INTERNAL_ERROR', message: 'Server error' });
render(<MemoryRouter><ItemListPage /></MemoryRouter>);
await waitFor(() => {
expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
});
});
it('shows empty state when no items', async () => {
mockFetchSuccess({ items: [], total: 0 });
render(<MemoryRouter><ItemListPage /></MemoryRouter>);
await waitFor(() => {
expect(screen.getByText(/no items/i)).toBeInTheDocument();
});
});
});
```
### Auth Flow Test Pattern
```typescript
describe('useAuth', () => {
it('sets token and user on successful login', async () => {
const mockUser = { id: '1', email: 'test@example.com', displayName: 'Test' };
mockFetchSuccess({ user: mockUser, token: 'jwt-token-123' });
// Render hook and trigger login
// Assert token stored and user state updated
});
it('clears state on logout', () => {
// Set initial auth state
// Call logout
// Assert token removed and user null
});
it('redirects to login when token expires', async () => {
mockFetchError(401, { code: 'UNAUTHORIZED', message: 'Token expired' });
// Trigger authenticated request
// Assert redirect to /login
});
});
```
### Reference
See [frontend-patterns.md](.github/agents/shared-references/frontend-patterns.md) for complete frontend architecture guidance.