slp-modular-cms/aidlc-docs/features/cms-frontend/construction/plans/unit-4-functional-design-plan.md

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

• Step 1: Analyze unit context and existing code patterns
• Step 2: Generate questions, collect answers
• Step 3: Create domain-entities.md
• Step 4: Create business-rules.md
• Step 5: Create business-logic-model.md
• 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

---

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

---

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