feat: analytics for labs and kpis metrics

Author: rebecamurillo

.github/agents/copilot-instructions.md

@@ -3,6 +3,8 @@
 Auto-generated from all feature plans. Last updated: 2026-02-24
 
 ## Active Technologies
+- TypeScript 5 (strict), Node.js 20, React 18 + Astro 4 (SSR), Prisma Client (MySQL), D3.js v7, `@testing-library/react`, Vitest (002-admin-analytics-dashboard)
+- MySQL (via Prisma) — constitution names PostgreSQL but production schema is MySQL (002-admin-analytics-dashboard)
 
 - **Language**: TypeScript 5.x, strict mode — no `any`, no `@ts-ignore`, no weakening of tsconfig
 - **Frontend framework**: Astro 4 (SSR) + React 18 islands
@@ -62,11 +64,8 @@ tests/
 - Tailwind + Catalyst UI Kit only for styling
 
 ## Recent Changes
-- 001-csv-download: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+- 002-admin-analytics-dashboard: Added Platform Analytics Dashboard with D3.js charts, React components (SSR + client:load), analytics helpers
 
-- 001-kpi-multi-value-input: Replace fixed before/after KPI input with dynamic multi-value list; add DefaultCollectionDate; expose `results: IKpiResult[]` from BFF
-- 001-multi-entry-kpi-charts: Added TypeScript (Astro strict preset) + React 19 islands + Astro 5, React 19, D3 7, Chart.js 4, react-chartjs-2, Tailwind 4
-- 001-mcda-custom-analysis: Added TypeScript 5 (strict mode via `astro/tsconfigs/strict`) + Astro 5 (`@astrojs/node` SSR adapter), React 19, Prisma 6, Tailwind CSS 4, Vitest 4
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

package-lock.json

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Platform Analytics Dashboard
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-03-17  
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- FR-010 and FR-011 reference Astro/SSR and Astro components — these are architectural constraints from the project constitution, not implementation details. They define the "what" (server-rendered, non-interactive) rather than the "how".
+- The Assumptions section documents that the existing ApiClient may need extension for retrieving all KPI results and user counts. This is flagged as a dependency rather than left as a clarification blocker.
+- All items pass validation. Spec is ready for `/speckit.clarify` or `/speckit.plan`.

specs/002-admin-analytics-dashboard/checklists/requirements.md

@@ -0,0 +1,24 @@
+# Contracts: Platform Analytics Dashboard
+
+**No new external API contracts.**
+
+This feature is a read-only SSR Astro page that consumes existing internal API endpoints via `ApiClient`. It does not expose any new endpoints, commands, or public interfaces.
+
+## Consumed Endpoints (existing)
+
+| Endpoint | Method | Used For |
+|----------|--------|----------|
+| `/api/v1/labs?fields=projects,kpiresults,transport_modes` | GET | All living labs with KPI results and measures |
+| `/api/v1/kpidefinitions` | GET | All KPI definitions |
+| `/api/v1/projects` | GET | All measures/projects |
+| `/api/v1/users` | GET | All users (requires new `getUsers()` on ApiClient) |
+
+## New ApiClient Method
+
+One new method added to `ApiClient.ts`:
+
+```typescript
+async getUsers(options?: { status?: string }): Promise<User[] | null>
+```
+
+This method wraps the existing `/api/v1/users` endpoint which already supports status filtering. It follows the same pattern as other ApiClient methods.

specs/002-admin-analytics-dashboard/contracts/README.md

@@ -0,0 +1,210 @@
+# Data Model: Platform Analytics Dashboard
+
+**Phase**: 1 | **Feature**: 002-admin-analytics-dashboard | **Date**: 2026-03-17
+
+---
+
+## Source Entities (read-only — no schema changes)
+
+This feature reads existing data only. No new database tables or Prisma schema changes required.
+
+### Living Labs (`labs`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BigInt (PK) | Used as grouping key |
+| name | String | Display label in tables/charts |
+| country | String? | Display in table |
+| created_at | DateTime? | — |
+| updated_at | DateTime? | — |
+
+**Relationships used**:
+- `kpiresults[]` → via `getLivingLabs()` populated include
+- `living_lab_projects_implementation[]` → via populated include (projects)
+
+### KPI Definitions (`kpidefinitions`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BigInt (PK) | Used for mapping results → definitions |
+| kpi_number | String | Display label (e.g. "1", "2.1") |
+| name | String | Display label |
+| parent_kpi_id | BigInt? (FK → self) | `null` = main/parent KPI |
+| type | Enum (GLOBAL, LOCAL) | Used for type breakdown |
+
+**Main/parent KPI identification**: `parent_kpi_id IS NULL`
+
+### KPI Results (`kpiresults`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BigInt (PK) | — |
+| kpidefinition_id | BigInt (FK → kpidefinitions) | Links result to definition |
+| living_lab_id | BigInt (FK → labs) | Links result to lab |
+| value | Float | The submitted measurement |
+| date | DateTime | Used for timeline aggregation (year extraction) |
+
+**Accessed via**: `ILivingLabPopulated.kpi_results: IKpiResultGroup[]`, where each group has `results: IKpiResult[]`
+
+### Projects/Measures (`projects` + `living_lab_projects_implementation`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| projects.id | BigInt (PK) | — |
+| projects.name | String | Display label |
+| projects.type | String (PUSH, PULL, OTHER) | Used for type breakdown |
+| impl.project_id | BigInt (FK) | Links implementation to project |
+| impl.living_lab_id | BigInt (FK) | Links implementation to lab |
+| impl.start_at | DateTime? | Used for "last updated" computation |
+| impl.updated_at | DateTime? | Used for "last updated" computation |
+
+### Users (`users`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BigInt (PK) | — |
+| name | String | — |
+| email | String | — |
+| status | String (signup, active, disabled) | Used for active vs pending breakdown |
+
+---
+
+## Computed Analytics Data Structures
+
+These are TypeScript interfaces for data computed in `src/lib/helpers/analytics.ts` and passed as props from the Astro page to components.
+
+### MetricCardData
+
+```typescript
+/** Data for a single summary metric card */
+interface MetricCardData {
+  label: string;        // e.g. "Living Labs", "Users (active / pending)"
+  value: string;        // Primary display value, e.g. "12", "45 / 3"
+  icon?: string;        // Optional icon identifier
+  color?: string;       // Tailwind color class, e.g. "text-primary"
+}
+```
+
+### LabKpiTimelineData
+
+```typescript
+/** Data for the D3 line chart — one series per living lab */
+interface LabKpiTimelineSeries {
+  labId: number;
+  labName: string;
+  color: string;
+  dataPoints: { year: number; count: number }[];
+}
+```
+
+### AlertCardData
+
+```typescript
+/** Data for a single analytics alert card */
+interface AlertCardData {
+  label: string;          // e.g. "Labs with no KPI results"
+  value: number;          // Count
+  severity: "warning" | "danger" | "info";
+  items?: string[];       // Optional list of affected entity names
+}
+```
+
+### LivingLabMetricsRow
+
+```typescript
+/** One row in the living lab metrics table */
+interface LivingLabMetricsRow {
+  labId: number;
+  labName: string;
+  totalResultEntries: number;      // All KPI results (including child KPIs)
+  kpisCoveredCount: number;        // Distinct main/parent KPIs with results
+  totalMainKpis: number;           // Total main/parent KPI definitions
+  pushMeasuresCount: number;
+  pullMeasuresCount: number;
+  lastUpdatedAt: string | null;    // ISO date string or null
+}
+```
+
+### KpiCoverageRow
+
+```typescript
+/** One row in the KPI coverage table */
+interface KpiCoverageRow {
+  kpiId: number;
+  kpiNumber: string;            // e.g. "1", "2", "3"
+  kpiName: string;
+  kpiType: "GLOBAL" | "LOCAL";
+  labsWithResultsCount: number; // How many labs have submitted results
+  totalLabs: number;            // Total number of labs as a reference
+}
+```
+
+### LabMeasuresBarData
+
+```typescript
+/** Data for the D3 bar chart — one group per living lab */
+interface LabMeasuresBarData {
+  labName: string;
+  pushCount: number;
+  pullCount: number;
+}
+```
+
+---
+
+## Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────┐
+│  analytics.astro (SSR frontmatter)                  │
+│                                                     │
+│  1. ApiClient.getLivingLabs()  → ILivingLabPopulated[] │
+│  2. ApiClient.getKPIs({})     → IKpi[]              │
+│  3. ApiClient.getMeasures()   → IProject[]          │
+│  4. ApiClient.getUsers()      → User[]              │
+│                                                     │
+│  ┌───────────────────────────────┐                  │
+│  │  analytics.ts helpers         │                  │
+│  │  - computeMetricCards()       │                  │
+│  │  - computeLabKpiTimeline()    │                  │
+│  │  - computeAlerts()            │                  │
+│  │  - computeLabMetricsTable()   │                  │
+│  │  - computeKpiCoverageTable()  │                  │
+│  │  - computeLabMeasuresBar()    │                  │
+│  └───────────────────────────────┘                  │
+│                                                     │
+│  Pass computed data as props ↓                      │
+├─────────────────────────────────────────────────────┤
+│  REACT COMPONENTS (SSR-only, no client:* → zero JS)  │
+│  ┌──────────┐ ┌──────────────┐ ┌────────────────┐  │
+│  │MetricCard│ │AnalyticsAlerts│ │LivingLabMetrics│  │
+│  │ (×4)     │ │              │ │   Table        │  │
+│  └──────────┘ └──────────────┘ └────────────────┘  │
+│  ┌──────────────────┐                               │
+│  │KPICoverageTable  │                               │
+│  └──────────────────┘                               │
+├─────────────────────────────────────────────────────┤
+│  REACT ISLANDS (client:load — D3 requires DOM)       │
+│  ┌───────────────────────┐ ┌──────────────────────┐ │
+│  │D3LineChartLabKPIs     │ │D3BarChartLabMeasures │ │
+│  │  Overtime             │ │                      │ │
+│  └───────────────────────┘ └──────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Mapping: KPI Result → Parent KPI
+
+To determine coverage of main/parent KPIs:
+
+```
+For each IKpiResult in a lab's kpi_results:
+  1. Get kpidefinition_id from the result
+  2. Look up the IKpi definition
+  3. If definition.parent_kpi_id is not null → use parent_kpi_id as the "covered parent"
+  4. If definition.parent_kpi_id is null → this IS a parent KPI, use definition.id
+  5. Add resolved parent ID to the "covered" set for that lab
+```
+
+This ensures a parent KPI is counted as "covered" whether the result was submitted against the parent directly or against any of its children.