feat(unit-4): Dashboard — availability widget with TanStack Query

- Add @tanstack/react-query 5.101.0; wrap app with QueryClientProvider - Add AvailabilityStatus type and AvailabilityResponse to api/types.ts - Implement useAvailabilityStatus (staleTime 30s, stale-on-error preserved) - Add AvailabilityStatusBadge with green/amber/red states and stale indicator - Replace DashboardPage placeholder card with live availability widget - Add MSW availability handler; update test/utils with QueryClientProvider - 55/55 tests pass (FR-05) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-06-22 13:39:29 +02:00
parent f476e06691
commit 3c6a06028e
23 changed files with 1219 additions and 22 deletions
@@ -5,7 +5,7 @@
 - **Feature Slug**: cms-frontend
 - **Project Type**: Brownfield
 - **Start Date**: 2026-06-16T20:27:00Z
- **Current Stage**: CONSTRUCTION - Unit 3: Functional Design
+- **Current Stage**: CONSTRUCTION - Unit 4: Functional Design
 - **Branch**: unknown

 ## Workspace State
@@ -49,7 +49,7 @@
 - [x] Unit 0 — Backend Prerequisites (CORS + httpOnly cookie) — COMPLETED 2026-06-19T11:45:00Z
 - [x] Unit 1 — Project Scaffold & Infrastructure — COMPLETED 2026-06-20T17:30:00Z
 - [x] Unit 2 — Authentication Pages — COMPLETED 2026-06-22 (29/29 tests pass, build ✅, runtime bugs fixed)
- [ ] Unit 3 — Layout & Navigation
+- [x] Unit 3 — Layout & Navigation — COMPLETED 2026-06-22 (all commits merged, tests pass)
 - [ ] Unit 4 — Dashboard
 - [ ] Unit 5 — User Management
 - [ ] Unit 6 — Profile, Settings & CMS Placeholder
@@ -342,6 +342,66 @@ Total: 24 steps, estimated 600–800 LOC, 4–6 hours development time. All 9 Un

 ---

+## Code Generation (Unit 4) — Plan Approved
+
+**Timestamp**: 2026-06-22T00:13:00Z
+
+**User Input**: "Approve Plan"
+
+**AI Response**: "Plan approved. Starting Part 2 — Code Generation. Executing 13 steps to implement TanStack Query, useAvailabilityStatus, AvailabilityStatusBadge, DashboardPage update, MSW handler, i18n keys, and tests."
+
+**Context**: Construction phase, Unit 4 Code Generation (Part 2 — Generation). Proceeding to implementation.
+
+---
+
+## Code Generation (Unit 4) — Plan Presented
+
+**Timestamp**: 2026-06-22T00:12:00Z
+
+**User Input**: "[plan approval prompt presented to user]"
+
+**AI Response**: "Created unit-4-code-generation-plan.md with 13 steps. Key decisions: TanStack Query install + QueryClientProvider wiring, useAvailabilityStatus with staleTime 30s, AvailabilityStatusBadge with stale/error states, MSW handler, i18n keys, tests. Awaiting user approval."
+
+**Context**: Construction phase, Unit 4 Code Generation (Part 1 — Planning). Plan at aidlc-docs/features/cms-frontend/construction/plans/unit-4-code-generation-plan.md.
+
+---
+
+## Functional Design (Unit 4) — Approved
+
+**Timestamp**: 2026-06-22T00:10:00Z
+
+**User Input**: "Continue to next stage"
+
+**AI Response**: "Functional Design for Unit 4 approved. Transitioning to Code Generation — Part 1 (Planning)."
+
+**Context**: Construction phase, Unit 4. Functional Design complete. Starting Code Generation plan.
+
+---
+
+## Functional Design (Unit 4) — Questions Answered
+
+**Timestamp**: 2026-06-22T00:05:00Z
+
+**User Input**: "ik heb de vragen beantwoord" (answers: Q1=A, Q2=D combination of A+C, Q3=D implement TanStack Query, Q4=A, Q5=A)
+
+**AI Response**: "Generated 4 functional design artifacts for Unit 4: domain-entities.md, business-rules.md, business-logic-model.md, frontend-components.md. Key decisions: TanStack Query added as new dependency; stale data preserved on error with stale indicator + error banner; AvailabilityStatus + AvailabilityResponse added to api/types.ts."
+
+**Context**: Construction phase, Unit 4 Functional Design. All questions answered; design artifacts generated. Awaiting user approval.
+
+---
+
+## Session Resume — Unit 4 Start
+
+**Timestamp**: 2026-06-22T00:00:00Z
+
+**User Input**: "hervat de aidlc workflow en ga verder met de volgende unit (unit 4)"
+
+**AI Response**: "Session resumed. Unit 3 (Layout & Navigation) marked as complete — all commits present in git history. Loaded unit-of-work.md, unit-3 code-generation-plan.md, requirements.md, api-documentation.md, frontend codebase structure. Starting Functional Design for Unit 4 (Dashboard)."
+
+**Context**: Session resumed after Unit 3 completion. aidlc-state.md updated: Unit 3 = COMPLETED, Current Stage = CONSTRUCTION - Unit 4: Functional Design.
+
+---
+
 ## Functional Design (Unit 2) — Questions Answered

 **Timestamp**: 2026-06-20T18:00:00Z
@@ -0,0 +1,169 @@
+# Code Generation Plan — Unit 4: Dashboard
+
+**Status**: ✅ Complete
+
+## Unit Context
+
+**Unit**: Unit 4 — Dashboard
+**Type**: Frontend (React/TypeScript)
+**Depends on**: Unit 3 (AppLayout, AuthContext) — complete
+**Stories Covered**: FR-05 (availability widget on dashboard)
+
+**Key Design Decisions** (from functional design):
+- `@tanstack/react-query` added as new dependency; `QueryClientProvider` wraps the app in `main.tsx`
+- `useAvailabilityStatus` uses `useQuery` with `staleTime: 30_000` ms
+- Error + stale data: show last known status with stale indicator + error banner with Retry
+- `AvailabilityStatus` type and `AvailabilityResponse` interface added to `api/types.ts`
+- MSW mock handler created for tests
+
+**Files to Modify**:
+- `frontend/package.json` — add `@tanstack/react-query`
+- `frontend/src/main.tsx` — wrap with `QueryClientProvider`
+- `frontend/src/api/types.ts` — add `AvailabilityStatus`, `AvailabilityResponse`
+- `frontend/src/mocks/index.ts` — register availability handlers
+- `frontend/src/pages/DashboardPage.tsx` — replace placeholder with availability widget
+- `frontend/src/i18n/locales/en/translation.json` — add `availability.*` keys
+- `frontend/src/i18n/locales/nl/translation.json` — add `availability.*` keys
+
+**Files to Create**:
+- `frontend/src/api/useAvailability.ts`
+- `frontend/src/components/shared/AvailabilityStatusBadge.tsx`
+- `frontend/src/mocks/availability/handlers.ts`
+- `frontend/src/api/useAvailability.test.ts`
+- `frontend/src/components/shared/AvailabilityStatusBadge.test.tsx`
+- `aidlc-docs/features/cms-frontend/construction/unit-4/code/code-generation-summary.md`
+
+---
+
+## Code Generation Steps
+
+### Step 1: Install `@tanstack/react-query`
+- [x] Run `pnpm add @tanstack/react-query` in `frontend/`
+- [x] Verify `package.json` updated with `@tanstack/react-query`
+
+### Step 2: Add `AvailabilityStatus` and `AvailabilityResponse` to `api/types.ts`
+- [x] Append to `frontend/src/api/types.ts`:
+  ```ts
+  export type AvailabilityStatus = 'Available' | 'Maintenance' | 'Unavailable';
+
+  export interface AvailabilityResponse {
+      status: AvailabilityStatus;
+      checkedAt: string; // ISO 8601
+      message: string;
+  }
+  ```
+
+### Step 3: Wrap app with `QueryClientProvider` in `main.tsx`
+- [x] Import `QueryClient`, `QueryClientProvider` from `@tanstack/react-query`
+- [x] Create `queryClient` instance with `defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: true } }`
+- [x] Wrap `<AuthProvider>` with `<QueryClientProvider client={queryClient}>`
+
+### Step 4: Create `useAvailability.ts`
+- [x] Create `frontend/src/api/useAvailability.ts`
+- [x] Implement `useAvailabilityStatus()` using `useQuery`:
+  - `queryKey: ['availability', 'status']`
+  - `queryFn`: `api.get<AvailabilityResponse>('/api/v1/Availability/status')`
+  - `staleTime: 30_000`
+- [x] Return full TanStack Query result (`data`, `error`, `isLoading`, `isError`, `isFetching`, `refetch`)
+
+### Step 5: Create `AvailabilityStatusBadge.tsx`
+- [x] Create `frontend/src/components/shared/AvailabilityStatusBadge.tsx`
+- [x] Props: `status: AvailabilityStatus`, `message?: string`, `stale?: boolean`
+- [x] Status → color/icon mapping:
+  - `Available` → `bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200` + `CheckCircle` icon
+  - `Maintenance` → `bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-200` + `AlertTriangle` icon
+  - `Unavailable` → `bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200` + `XCircle` icon
+- [x] Show `message` as subtitle paragraph when non-empty (`data-testid="availability-message"`)
+- [x] When `stale={true}`: amber dashed border + `Clock` icon + `t('availability.staleLabel')` label (`data-testid="availability-stale-indicator"`)
+- [x] Test IDs: `availability-badge` (wrapper), `availability-status-label`
+
+### Step 6: Update `DashboardPage.tsx`
+- [x] Import `useAvailabilityStatus`, `AvailabilityStatusBadge` and `Card*` components
+- [x] Replace generic placeholder `Card` with the availability widget:
+  - Card title: `t('availability.title')`
+  - `isLoading` → skeleton placeholder (`data-testid="availability-skeleton"`)
+  - `data` present → `<AvailabilityStatusBadge status={data.status} message={data.message} stale={isError} />`
+  - `isError && !data` → error-only state: `t('availability.errorTitle')` + Retry button
+  - `isError` (any) → error banner below/above badge with Retry button (`data-testid="availability-error"`, `data-testid="availability-retry"`)
+- [x] Keep welcome header section unchanged
+
+### Step 7: Add i18n keys
+- [x] Add to `frontend/src/i18n/locales/en/translation.json`:
+  ```json
+  "availability": {
+    "title": "System Status",
+    "available": "Available",
+    "maintenance": "Maintenance",
+    "unavailable": "Unavailable",
+    "errorTitle": "Could not load status",
+    "staleLabel": "Last known status",
+    "retry": "Retry"
+  }
+  ```
+- [x] Add to `frontend/src/i18n/locales/nl/translation.json`:
+  ```json
+  "availability": {
+    "title": "Systeemstatus",
+    "available": "Beschikbaar",
+    "maintenance": "Onderhoud",
+    "unavailable": "Niet beschikbaar",
+    "errorTitle": "Status kon niet worden geladen",
+    "staleLabel": "Laatste bekende status",
+    "retry": "Opnieuw proberen"
+  }
+  ```
+
+### Step 8: Create MSW availability handler
+- [x] Create `frontend/src/mocks/availability/handlers.ts`:
+  ```ts
+  import { http, HttpResponse } from 'msw';
+  export const availabilityHandlers = [
+      http.get('*/Availability/status', () =>
+          HttpResponse.json({
+              status: 'Available',
+              checkedAt: new Date().toISOString(),
+              message: '',
+          })
+      ),
+  ];
+  ```
+- [x] Modify `frontend/src/mocks/index.ts`:
+  - Import `availabilityHandlers`
+  - Spread into `handlers` array
+  - Re-export `availabilityHandlers`
+
+### Step 9: Tests — `useAvailabilityStatus`
+- [x] Create `frontend/src/api/useAvailability.test.ts`
+- [x] Test cases (using MSW + `renderHook` with `QueryClientProvider` wrapper):
+  - Returns `isLoading=true` initially
+  - Returns `data` on successful fetch (using default MSW handler)
+  - Returns `isError=true` + preserves stale `data` on refetch failure (override handler to return 500)
+  - `refetch()` triggers a new fetch
+
+### Step 10: Tests — `AvailabilityStatusBadge`
+- [x] Create `frontend/src/components/shared/AvailabilityStatusBadge.test.tsx`
+- [x] Test cases:
+  - `Available` → green badge, `t('availability.available')` label
+  - `Maintenance` → amber badge, `t('availability.maintenance')` label
+  - `Unavailable` → red badge, `t('availability.unavailable')` label
+  - `message` prop: renders subtitle when non-empty, hidden when empty
+  - `stale={true}`: renders stale indicator
+  - `stale={false}` (default): no stale indicator
+
+### Step 11: Final verification
+- [x] `pnpm build` — no TypeScript or Vite errors
+- [x] `pnpm lint` — no ESLint errors
+- [x] `pnpm test` — all tests pass (existing + new)
+- [x] Dev server: verify availability widget renders on dashboard, skeleton visible on load, Retry button functional
+
+### Step 12: Write code generation summary
+- [x] Create `aidlc-docs/features/cms-frontend/construction/unit-4/code/code-generation-summary.md`
+- [x] List all created/modified files with paths
+- [x] Record test results
+
+### Step 13: Commit
+- [x] Commit with message referencing Unit 4 / FR-05
+
+---
+
+## Total Steps: 13
@@ -0,0 +1,105 @@
+# Functional Design Plan — Unit 4: Dashboard
+
+**Status**: 🚧 In Progress
+
+## Unit Context
+
+**Unit**: Unit 4 — Dashboard
+**Type**: Frontend (React/TypeScript)
+**Depends on**: Unit 3 (AppLayout, AuthContext)
+**Stories Covered**: US-05 (FR-05 — Dashboard with availability widget)
+
+**Key Deliverables**:
+- `frontend/src/api/useAvailability.ts` — `useAvailabilityStatus` hook with auto-refresh
+- `frontend/src/components/shared/AvailabilityStatusBadge.tsx` — colored status badge
+- Update `frontend/src/pages/DashboardPage.tsx` — replace placeholder with availability widget
+- `frontend/src/mocks/availability/handlers.ts` — MSW mock for tests
+- i18n keys for availability widget (en + nl)
+- Unit tests
+
+**API Endpoint**:
+- `GET /api/v1/Availability/status` → `{ status: "Available" | "Maintenance" | "Unavailable", checkedAt: string, message: string }`
+
+**Note**: `routes/index.tsx` from unit-of-work.md maps to `pages/DashboardPage.tsx` in the actual project structure (code-based router, not file-based).
+
+---
+
+## Functional Design Steps
+
+- [x] Step 1: Analyze unit context and existing code patterns
+- [x] Step 2: Generate questions, collect answers
+- [x] Step 3: Create `domain-entities.md`
+- [x] Step 4: Create `business-rules.md`
+- [x] Step 5: Create `business-logic-model.md`
+- [x] Step 6: Create `frontend-components.md`
+- [ ] Step 7: Present completion message and await approval
+
+---
+
+## Questions
+
+Please fill in the letter after each `[Answer]:` tag.
+
+---
+
+### Question 1: Availability message display
+
+The API returns a `message` field alongside the status. When/how should this message be shown?
+
+A) Display the message as a subtitle below the status badge — always visible when non-empty (recommended — informative without cluttering the UI)
+B) Show the message as a tooltip on hover/focus over the badge — only visible on interaction
+C) Do not display the `message` field — show status text only
+D) Other
+
+[Answer]: A
+
+---
+
+### Question 2: Error state when availability fetch fails
+
+If `GET /availability/status` returns an error or the network is unreachable, what should the dashboard show?
+
+A) An error card with a generic "Could not load availability status" message + Retry button (recommended — communicates the issue without crashing; consistent with global error pattern)
+B) Hide the availability widget silently — show nothing in its place
+C) Show the last successfully fetched status with a "stale" indicator (clock icon or "last updated X ago")
+D) Other
+
+[Answer]: D, A combination of A and C. Show the error message with a retry button, but also tell the user the last fetched status for clarity
+
+---
+
+### Question 3: Auto-refresh interval
+
+The unit-of-work specifies "staleTime: 30s". Since there is no TanStack Query, this will be implemented as `setInterval`. Should the hook auto-refresh while the component is mounted?
+
+A) Yes — poll every 30 seconds while mounted (recommended — keeps dashboard current without manual refresh)
+B) Yes — but use a longer interval: 60 seconds
+C) No — fetch once on mount only; no auto-refresh (user can refresh the page)
+D) Other
+
+[Answer]: D, try again to implement tanstack Query
+
+---
+
+### Question 4: AvailabilityStatus type location
+
+Where should the `AvailabilityStatus` type and `AvailabilityResponse` interface be defined?
+
+A) Add to `frontend/src/api/types.ts` — the shared types file (recommended — consistent with existing `User`, `AuthResponse`, `SetupStatus` types)
+B) Define inline in `useAvailability.ts` only — no shared types needed for this unit
+C) Other
+
+[Answer]: A
+
+---
+
+### Question 5: Unit test scope
+
+Which parts of Unit 4 should have unit tests?
+
+A) `useAvailabilityStatus` hook (fetch, polling, error handling) + `AvailabilityStatusBadge` (renders correct colors/labels for each status) (recommended — covers all logic and UI variants)
+B) Only `AvailabilityStatusBadge` — skip hook tests (hook logic is simple enough to trust without tests)
+C) Full integration test: DashboardPage renders with availability widget (using MSW mock)
+D) Other
+
+[Answer]: A
@@ -0,0 +1,39 @@
+# Code Generation Summary — Unit 4: Dashboard
+
+**Status**: ✅ Complete
+**Stories**: FR-05 (Dashboard with system availability widget)
+
+## Files Created
+
+| File | Purpose |
+|---|---|
+| `frontend/src/api/useAvailability.ts` | `useAvailabilityStatus` hook (TanStack Query, staleTime 30s) |
+| `frontend/src/components/shared/AvailabilityStatusBadge.tsx` | Colored status badge with stale indicator |
+| `frontend/src/mocks/availability/handlers.ts` | MSW handler for `GET /Availability/status` |
+| `frontend/src/api/useAvailability.test.ts` | 4 hook tests (loading, success, error, refetch) |
+| `frontend/src/components/shared/AvailabilityStatusBadge.test.tsx` | 8 badge tests (all statuses, message, stale indicator) |
+| `aidlc-docs/features/cms-frontend/construction/unit-4/code/code-generation-summary.md` | This file |
+
+## Files Modified
+
+| File | Change |
+|---|---|
+| `frontend/package.json` | Added `@tanstack/react-query` 5.101.0 |
+| `frontend/src/main.tsx` | Wrapped app with `QueryClientProvider` |
+| `frontend/src/api/types.ts` | Added `AvailabilityStatus`, `AvailabilityResponse` |
+| `frontend/src/pages/DashboardPage.tsx` | Replaced placeholder card with availability widget |
+| `frontend/src/i18n/locales/en/translation.json` | Added `availability.*` keys |
+| `frontend/src/i18n/locales/nl/translation.json` | Added `availability.*` keys |
+| `frontend/src/mocks/index.ts` | Registered `availabilityHandlers` |
+| `frontend/src/test/utils.tsx` | Added `QueryClientProvider` to `renderWithProviders` and `renderApp` |
+
+## Test Results
+
+- **Total tests**: 55 / 55 passed
+- **Build**: ✅ clean (no TS errors)
+- **Lint**: ✅ clean
+
+## Key Decisions Made During Generation
+
+- `test/utils.tsx` updated to include `QueryClientProvider` — required by the 3 existing integration tests that render `DashboardPage` (RouteGuard.test.tsx, LoginPage.test.tsx)
+- `error` destructured field removed from `DashboardPage` (unused variable TS6133) — `isError` is sufficient
@@ -0,0 +1,114 @@
+# Business Logic Model — Unit 4: Dashboard
+
+## Process Overview
+
+Unit 4 introduces TanStack Query as a shared data-fetching layer and implements the Dashboard page with a live availability widget. The logic splits into three concerns: query infrastructure setup, the availability hook, and the dashboard UI composition.
+
+---
+
+## TanStack Query Setup
+
+A `QueryClient` is created once at app startup and provided via `QueryClientProvider` wrapping the `RouterProvider` in `main.tsx`. This is a one-time global change that enables all future units to use `useQuery` / `useMutation`.
+
+```ts
+// Recommended default options for the QueryClient
+const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: {
+            retry: 1,
+            refetchOnWindowFocus: true,
+        },
+    },
+});
+```
+
+---
+
+## useAvailabilityStatus Hook
+
+**Location**: `frontend/src/api/useAvailability.ts`
+
+**Query key**: `['availability', 'status']`
+
+**Fetch function**: Calls `GET /api/v1/Availability/status` via the shared `api` client.
+
+**staleTime**: `30_000` ms — TanStack Query refetches automatically in the background once data is 30 seconds old.
+
+**Return shape**:
+
+```ts
+{
+    data: AvailabilityResponse | undefined;   // undefined until first successful fetch
+    error: Error | null;
+    isLoading: boolean;                        // true only during initial fetch with no data
+    isFetching: boolean;                       // true during any in-flight refetch
+    isError: boolean;
+    refetch: () => void;                       // exposed for Retry button
+}
+```
+
+**Stale-with-error state**: When a background refetch fails, TanStack Query preserves the previous `data` value while setting `isError = true`. This enables the dashboard to display the last known status alongside the error state (BR-U4-11).
+
+---
+
+## DashboardPage Composition
+
+The DashboardPage composes existing layout primitives with the new availability widget. No routing changes are needed — `DashboardPage` is already registered as the `/dashboard` route component in `router.tsx`.
+
+**Sections**:
+1. **Header** — welcome message with user name (already implemented; retained as-is)
+2. **Availability Widget** — replaces the generic placeholder card
+
+---
+
+## Availability Widget Logic Flow
+
+```mermaid
+sequenceDiagram
+    box rgba(99,179,237,0.4) Component Layer
+        participant DP as DashboardPage
+        participant Badge as AvailabilityStatusBadge
+    end
+    box rgba(154,230,180,0.4) Query Layer
+        participant Q as useAvailabilityStatus
+    end
+    box rgba(233,213,255,0.4) External
+        participant API as GET /availability/status
+    end
+
+    DP->>Q: mount — useAvailabilityStatus()
+    Q->>API: fetch on mount
+    API-->>Q: 200 AvailabilityResponse
+    Q-->>DP: data + isLoading=false
+    DP->>Badge: render with status and message
+    Note over Q: staleTime 30s elapses
+    Q->>API: background refetch
+    alt Refetch succeeds
+        API-->>Q: 200 AvailabilityResponse
+        Q-->>DP: updated data
+        DP->>Badge: re-render with fresh data
+    else Refetch fails
+        API-->>Q: network error or 5xx
+        Q-->>DP: isError=true data=stale
+        DP->>Badge: render stale badge with stale indicator
+        DP->>DP: show error banner with Retry button
+    end
+```
+
+Sequence showing initial fetch, badge render, background refetch on staleTime expiry, and error handling with stale data preservation.
+
+---
+
+## i18n Keys (additions)
+
+New translation keys needed for the availability widget:
+
+| Key | English | Dutch |
+|---|---|---|
+| `availability.title` | System Status | Systeemstatus |
+| `availability.available` | Available | Beschikbaar |
+| `availability.maintenance` | Maintenance | Onderhoud |
+| `availability.unavailable` | Unavailable | Niet beschikbaar |
+| `availability.errorTitle` | Could not load status | Status kon niet worden geladen |
+| `availability.staleLabel` | Last known status | Laatste bekende status |
+| `availability.retry` | Retry | Opnieuw proberen |
@@ -0,0 +1,77 @@
+# Business Rules — Unit 4: Dashboard
+
+## Access Rules
+
+| ID | Rule |
+|---|---|
+| BR-U4-01 | The Dashboard is accessible to all authenticated users regardless of role |
+| BR-U4-02 | Unauthenticated users are redirected to `/login` by the existing `authenticatedRoute` guard |
+
+## Data Fetching Rules
+
+| ID | Rule |
+|---|---|
+| BR-U4-03 | Availability status is fetched via `GET /api/v1/Availability/status` on component mount |
+| BR-U4-04 | The query uses TanStack Query with `staleTime: 30_000` (30 seconds) — background refetch triggers automatically when data is stale |
+| BR-U4-05 | The endpoint is public (anonymous) — no Bearer token required; the API client still sends credentials for cookie consistency |
+
+## Display Rules
+
+| ID | Rule |
+|---|---|
+| BR-U4-06 | Status `Available` renders with a **green** visual indicator |
+| BR-U4-07 | Status `Maintenance` renders with an **amber/yellow** visual indicator |
+| BR-U4-08 | Status `Unavailable` renders with a **red** visual indicator |
+| BR-U4-09 | The `message` field is displayed as a subtitle below the status badge when it is a non-empty string |
+
+## Error Handling Rules
+
+| ID | Rule |
+|---|---|
+| BR-U4-10 | If the initial fetch fails (no cached data): display an error card with a generic message and a **Retry** button |
+| BR-U4-11 | If a background refetch fails but cached (stale) data exists: display the stale status badge with a visual "stale" indicator (e.g. amber border, clock icon) AND an error banner with a **Retry** button |
+| BR-U4-12 | Clicking the Retry button triggers an immediate refetch via TanStack Query's `refetch()` |
+| BR-U4-13 | Network errors and API errors are treated identically from a UI perspective — no internal error details are exposed to the user |
+
+## Loading Rules
+
+| ID | Rule |
+|---|---|
+| BR-U4-14 | While the initial fetch is in-flight (no cached data): display a skeleton/loading placeholder in the availability widget |
+| BR-U4-15 | Background refetches (when cached data exists) do not trigger a loading skeleton — the existing status remains visible |
+
+## Decision Flowchart
+
+```mermaid
+graph TD
+    Mount["Component Mounts"]
+    HasCache{Cached data exists?}
+    Loading["Show skeleton loading state"]
+    FetchSuccess{Fetch successful?}
+    ShowStatus["Show AvailabilityStatusBadge\n+ message subtitle"]
+    BackgroundRefetch{Background refetch error?}
+    ShowStale["Show stale badge\n+ stale indicator\n+ error banner + Retry"]
+    ShowError["Show error card\n+ Retry button"]
+
+    Mount --> HasCache
+    HasCache -- No --> Loading
+    HasCache -- Yes --> ShowStatus
+    Loading --> FetchSuccess
+    FetchSuccess -- Yes --> ShowStatus
+    FetchSuccess -- No --> ShowError
+    ShowStatus --> BackgroundRefetch
+    BackgroundRefetch -- Yes --> ShowStale
+    BackgroundRefetch -- No --> ShowStatus
+
+    classDef decision fill:#FF9800,stroke:#e65100,color:#000
+    classDef action fill:#2196F3,stroke:#0d47a1,color:#000
+    classDef error fill:#F44336,stroke:#b71c1c,color:#000
+    classDef start fill:#4CAF50,stroke:#2E7D32,color:#000
+
+    class Mount start
+    class HasCache,FetchSuccess,BackgroundRefetch decision
+    class Loading,ShowStatus action
+    class ShowError,ShowStale error
+```
+
+Flowchart showing dashboard fetch states: skeleton on first load, badge on success, error card (no data) or stale badge + error banner (with data) on failure.
@@ -0,0 +1,62 @@
+# Domain Entities — Unit 4: Dashboard
+
+## Entities
+
+### AvailabilityStatus (enumeration)
+
+A union type representing the three possible system states returned by the API.
+
+| Value | Meaning |
+|---|---|
+| `Available` | System is fully operational |
+| `Maintenance` | System is in planned maintenance mode |
+| `Unavailable` | System is not accessible |
+
+---
+
+### AvailabilityResponse (API response shape)
+
+Returned by `GET /api/v1/Availability/status`.
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | `AvailabilityStatus` | Current system status |
+| `checkedAt` | `string` (ISO 8601) | Timestamp when status was last evaluated |
+| `message` | `string` | Optional human-readable reason or note (may be empty string) |
+
+---
+
+## Entity Relationship Diagram
+
+```mermaid
+classDiagram
+    class AvailabilityResponse {
+        +status: AvailabilityStatus
+        +checkedAt: string
+        +message: string
+    }
+    class AvailabilityStatus {
+        <<enumeration>>
+        Available
+        Maintenance
+        Unavailable
+    }
+    AvailabilityResponse --> AvailabilityStatus : status
+
+    style AvailabilityResponse fill:#4CAF50,stroke:#2E7D32,color:#000
+    style AvailabilityStatus fill:#2196F3,stroke:#0D47A1,color:#000
+```
+
+AvailabilityResponse holds a status (one of three enumeration values) plus a timestamp and message.
+
+---
+
+## Type Placement
+
+Both `AvailabilityStatus` and `AvailabilityResponse` are added to `frontend/src/api/types.ts` — the shared domain types file, consistent with `User`, `AuthResponse`, and `SetupStatus`.
+
+---
+
+## TanStack Query Dependency
+
+`@tanstack/react-query` is added as a new production dependency. A shared `QueryClient` is configured in `main.tsx` and provided via `QueryClientProvider`. This enables `staleTime`, background refetching, and persistent cached data across error states.
@@ -0,0 +1,231 @@
+# Frontend Components — Unit 4: Dashboard
+
+## Component Hierarchy
+
+```mermaid
+graph TD
+    Main["main.tsx\n(App Entry)"]
+    QCP["QueryClientProvider\n(TanStack Query root)"]
+    AuthProv["AuthProvider"]
+    RouterProv["RouterProvider"]
+    DP["DashboardPage\n(/dashboard route)"]
+    Hook["useAvailabilityStatus\n(useQuery hook)"]
+    Welcome["Welcome Header\n(existing — unchanged)"]
+    Widget["Availability Widget\nsection"]
+    Badge["AvailabilityStatusBadge"]
+    Skeleton["Skeleton loading\n(isLoading)"]
+    ErrorBanner["Error Banner + Retry\n(isError)"]
+    StaleIndicator["Stale Indicator\n(isError + data)"]
+
+    Main --> QCP
+    QCP --> AuthProv
+    AuthProv --> RouterProv
+    RouterProv --> DP
+    DP --> Hook
+    DP --> Welcome
+    DP --> Widget
+    Widget --> Skeleton
+    Widget --> Badge
+    Widget --> ErrorBanner
+    Badge --> StaleIndicator
+
+    classDef infra fill:#4CAF50,stroke:#2E7D32,color:#000
+    classDef page fill:#2196F3,stroke:#0D47A1,color:#000
+    classDef hook fill:#9C27B0,stroke:#4A148C,color:#000
+    classDef ui fill:#FF9800,stroke:#E65100,color:#000
+    classDef error fill:#F44336,stroke:#B71C1C,color:#000
+
+    class Main,QCP,AuthProv,RouterProv infra
+    class DP page
+    class Hook hook
+    class Welcome,Widget,Badge,Skeleton,StaleIndicator ui
+    class ErrorBanner error
+```
+
+Component hierarchy: main.tsx wraps app with QueryClientProvider; DashboardPage consumes availability hook and renders welcome header + availability widget with conditional states.
+
+---
+
+## New / Modified Files
+
+### 1. `frontend/src/main.tsx` (modify)
+
+Add `QueryClientProvider` wrapping above `AuthProvider`. No other changes.
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: { retry: 1, refetchOnWindowFocus: true },
+    },
+});
+
+// Wrap existing tree:
+<QueryClientProvider client={queryClient}>
+    <AuthProvider>
+        <RouterProvider router={router} context={{ auth }} />
+    </AuthProvider>
+</QueryClientProvider>
+```
+
+---
+
+### 2. `frontend/src/api/types.ts` (modify)
+
+Add two new types at the end of the file:
+
+```ts
+export type AvailabilityStatus = 'Available' | 'Maintenance' | 'Unavailable';
+
+export interface AvailabilityResponse {
+    status: AvailabilityStatus;
+    checkedAt: string; // ISO 8601
+    message: string;
+}
+```
+
+---
+
+### 3. `frontend/src/api/useAvailability.ts` (new)
+
+```ts
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api-client';
+import type { AvailabilityResponse } from './types';
+
+export function useAvailabilityStatus() {
+    return useQuery<AvailabilityResponse>({
+        queryKey: ['availability', 'status'],
+        queryFn: () => api.get<AvailabilityResponse>('/api/v1/Availability/status'),
+        staleTime: 30_000,
+    });
+}
+```
+
+**Return**: standard TanStack Query result (`data`, `error`, `isLoading`, `isError`, `isFetching`, `refetch`).
+
+---
+
+### 4. `frontend/src/components/shared/AvailabilityStatusBadge.tsx` (new)
+
+**Props**:
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `status` | `AvailabilityStatus` | Yes | Current status value |
+| `message` | `string` | No | Subtitle text below badge (only shown when non-empty) |
+| `stale` | `boolean` | No | When true, renders a stale-data visual indicator (amber border, clock icon) |
+
+**Status → color mapping**:
+
+| Status | Badge color class | Icon |
+|---|---|---|
+| `Available` | `bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200` | `CheckCircle` |
+| `Maintenance` | `bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-200` | `AlertTriangle` |
+| `Unavailable` | `bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200` | `XCircle` |
+
+**`stale` prop behavior**: When `stale={true}`, the badge wrapper gets an amber dashed border and a `Clock` icon + `t('availability.staleLabel')` label is rendered below the badge.
+
+**Test IDs**:
+
+| Element | `data-testid` |
+|---|---|
+| Badge wrapper | `availability-badge` |
+| Status label | `availability-status-label` |
+| Message subtitle | `availability-message` |
+| Stale indicator | `availability-stale-indicator` |
+
+---
+
+### 5. `frontend/src/pages/DashboardPage.tsx` (modify)
+
+Replace the generic placeholder `Card` with the availability widget section.
+
+**Conditional rendering logic**:
+
+```
+if (isLoading)   → show Skeleton in widget area
+if (isError && !data)  → show error card with Retry (no status to show)
+if (data)        → show AvailabilityStatusBadge
+    if (isError) → also show stale indicator on badge + error banner with Retry
+```
+
+**Layout sketch** (inside existing `space-y-6` wrapper):
+```
+[Welcome header — unchanged]
+[Card: title = t('availability.title')]
+  [if isLoading]  → skeleton placeholder
+  [if !isLoading && data] → AvailabilityStatusBadge status={data.status} message={data.message} stale={isError}
+  [if isError]    → error banner (below badge if stale, full-card if no data) + Retry button
+```
+
+---
+
+### 6. `frontend/src/mocks/availability/handlers.ts` (new)
+
+MSW handler for tests:
+
+```ts
+import { http, HttpResponse } from 'msw';
+
+export const availabilityHandlers = [
+    http.get('*/Availability/status', () =>
+        HttpResponse.json({
+            status: 'Available',
+            checkedAt: new Date().toISOString(),
+            message: '',
+        })
+    ),
+];
+```
+
+Register in `frontend/src/mocks/browser.ts` and `frontend/src/mocks/server.ts`.
+
+---
+
+## i18n Additions
+
+**`en/translation.json`**:
+```json
+{
+  "availability": {
+    "title": "System Status",
+    "available": "Available",
+    "maintenance": "Maintenance",
+    "unavailable": "Unavailable",
+    "errorTitle": "Could not load status",
+    "staleLabel": "Last known status",
+    "retry": "Retry"
+  }
+}
+```
+
+**`nl/translation.json`**:
+```json
+{
+  "availability": {
+    "title": "Systeemstatus",
+    "available": "Beschikbaar",
+    "maintenance": "Onderhoud",
+    "unavailable": "Niet beschikbaar",
+    "errorTitle": "Status kon niet worden geladen",
+    "staleLabel": "Laatste bekende status",
+    "retry": "Opnieuw proberen"
+  }
+}
+```
+
+---
+
+## Test IDs Summary
+
+| Element | `data-testid` |
+|---|---|
+| Availability badge wrapper | `availability-badge` |
+| Status label text | `availability-status-label` |
+| Message subtitle | `availability-message` |
+| Stale indicator | `availability-stale-indicator` |
+| Error banner | `availability-error` |
+| Retry button | `availability-retry` |
+| Widget skeleton | `availability-skeleton` |