# 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