Add Today dashboard foundation with permission-aware KPI summary API.

Replace hardcoded Today cards with a backend summary endpoint and composable frontend widgets filtered by org type and tab permissions.

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/src/app/[locale]/(dashboard)/today/page.tsx

@@ -3,22 +3,23 @@
 import { useTranslations } from 'next-intl';
 import { Link } from '@/i18n/navigation';
 import { useAuth } from '@/lib/hooks/useAuth';
-import { Card } from '@/components/ui/shared/Card';
+import { TodayKpiGrid } from '@/components/today/TodayKpiGrid';
+import { useTodaySummary } from '@/lib/hooks/useTodaySummary';
+import { formatApiErrorMessage } from '@/components/shared/formatApiError';
 
 export default function TodayPage() {
   const t = useTranslations('today');
   const { currentOrganization } = useAuth();
+  const { data, loading, error } = useTodaySummary(Boolean(currentOrganization?.id));
   const showNoSubscriptionNotice =
     Boolean(currentOrganization?.isOwner) && !currentOrganization?.plan;
 
   return (
-    <div>
-      <h1 className="text-2xl font-semibold mb-6">
-        {t('welcomeBack')}
-      </h1>
+    <div className="space-y-6">
+      <h1 className="text-2xl font-semibold">{t('welcomeBack')}</h1>
 
       {showNoSubscriptionNotice && (
-        <div className="mb-6 rounded-[var(--radius-md)] border border-amber-500/30 bg-amber-500/10 p-4">
+        <div className="rounded-[var(--radius-md)] border border-amber-500/30 bg-amber-500/10 p-4">
           <p className="text-sm text-amber-200">
             {t('noSubscriptionNotice')}{' '}
             <Link href="/settings/subscriptions" className="font-medium underline underline-offset-2">
@@ -29,27 +30,15 @@ export default function TodayPage() {
         </div>
       )}
 
-      <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4">
-        <Card>
-          <p className="text-sm text-card-muted">{t('cardTodaysAppointments')}</p>
-          <p className="text-2xl font-semibold mt-2">12</p>
-          <p className="text-xs text-text-muted mt-1">Monday 2/5/2026</p>
-        </Card>
-        <Card>
-          <p className="text-sm text-card-muted">{t('cardActivePatients')}</p>
-          <p className="text-2xl font-semibold mt-2">675</p>
-        </Card>
-        <Card>
-          <p className="text-sm text-card-muted">{t('cardNewLabCase')}</p>
-          <p className="text-2xl font-semibold mt-2">5</p>
-          <p className="text-xs text-text-muted mt-1">35 ↑</p>
-        </Card>
-        <Card>
-          <p className="text-sm text-card-muted">{t('cardTodayInvoices')}</p>
-          <p className="text-2xl font-semibold mt-2">1200$</p>
-          <p className="text-xs text-text-muted mt-1">21,300 $</p>
-        </Card>
-      </div>
+      {error ? (
+        <div className="rounded-[var(--radius-md)] border border-badge-danger-border bg-badge-danger-bg/40 p-4">
+          <p className="text-sm text-badge-danger-fg">
+            {formatApiErrorMessage(error, t('loadError'))}
+          </p>
+        </div>
+      ) : null}
+
+      <TodayKpiGrid widgets={data?.widgets ?? {}} loading={loading} />
     </div>
   );
 }

frontend/src/components/today/KpiCard.tsx

@@ -0,0 +1,47 @@
+import { Card } from '@/components/ui/shared/Card';
+import type { KpiCardColor } from '@/components/today/widget-registry';
+import type { LucideIcon } from 'lucide-react';
+
+const colorClasses: Record<KpiCardColor, string> = {
+  blue: '!bg-purpose-visit-bg !text-purpose-visit-fg !border-purpose-visit-border',
+  yellow: '!bg-badge-warning-bg !text-badge-warning-fg !border-badge-warning-border',
+  green: '!bg-badge-success-bg !text-badge-success-fg !border-badge-success-border',
+  red: '!bg-badge-danger-bg !text-badge-danger-fg !border-badge-danger-border',
+  purple: '!bg-purpose-consultation-bg !text-purpose-consultation-fg !border-purpose-consultation-border',
+  default: '',
+};
+
+interface KpiCardProps {
+  title: string;
+  value: string;
+  subtitle?: string | null;
+  icon?: LucideIcon;
+  color?: KpiCardColor;
+  loading?: boolean;
+}
+
+export function KpiCard({
+  title,
+  value,
+  subtitle,
+  icon: Icon,
+  color = 'default',
+  loading = false,
+}: KpiCardProps) {
+  return (
+    <Card className={colorClasses[color]}>
+      <div className="flex items-start justify-between gap-3">
+        <p className="text-sm font-medium">{title}</p>
+        {Icon ? <Icon className="h-4 w-4 shrink-0 opacity-80" aria-hidden /> : null}
+      </div>
+      {loading ? (
+        <div className="mt-2 h-8 w-16 animate-pulse rounded bg-current/10" />
+      ) : (
+        <p className="text-2xl font-bold mt-2">{value}</p>
+      )}
+      {subtitle ? (
+        <p className="text-xs opacity-80 mt-1">{subtitle}</p>
+      ) : null}
+    </Card>
+  );
+}

frontend/src/components/today/TodayKpiGrid.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { KpiCard } from '@/components/today/KpiCard';
+import { getEligibleTodayKpis, getVisibleTodayKpis } from '@/components/today/widget-registry';
+import type { TodaySummaryWidgets } from '@/types/today';
+
+interface TodayKpiGridProps {
+  widgets: TodaySummaryWidgets;
+  loading?: boolean;
+}
+
+export function TodayKpiGrid({ widgets, loading = false }: TodayKpiGridProps) {
+  const t = useTranslations('today');
+  const { currentOrganization } = useAuth();
+  const definitions = loading
+    ? getEligibleTodayKpis(currentOrganization)
+    : getVisibleTodayKpis(currentOrganization, widgets);
+
+  if (!loading && definitions.length === 0) {
+    return (
+      <p className="text-sm text-text-muted">{t('noWidgets')}</p>
+    );
+  }
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4">
+      {definitions.map((definition) => {
+        const value = definition.formatValue(widgets) ?? '—';
+        const subtitleKey = definition.formatSubtitle?.(widgets);
+        const subtitle =
+          subtitleKey === 'unlimited'
+            ? t('seatsUnlimited')
+            : definition.formatSubtitle?.(widgets);
+
+        return (
+          <KpiCard
+            key={definition.key}
+            title={t(definition.titleKey)}
+            value={value}
+            subtitle={subtitle}
+            icon={definition.icon}
+            color={definition.color}
+            loading={loading}
+          />
+        );
+      })}
+    </div>
+  );
+}

frontend/src/components/today/widget-registry.ts

@@ -0,0 +1,219 @@
+import type { LucideIcon } from 'lucide-react';
+import {
+  AlertCircle,
+  CalendarDays,
+  ClipboardList,
+  FlaskConical,
+  Link2,
+  Stethoscope,
+  UserCog,
+  Users,
+} from 'lucide-react';
+import type { Organization } from '@/types/organization';
+import {
+  canAccessAppointmentsSection,
+  canEditStaff,
+  canViewCases,
+  canViewStaff,
+  canViewTasks,
+  canViewTreatment,
+  hasPermission,
+  type OrgTypeName,
+} from '@/components/shared/permissions';
+import type { TodaySummaryWidgets, TodayWidgetKey } from '@/types/today';
+
+export type KpiCardColor = 'blue' | 'yellow' | 'green' | 'red' | 'purple' | 'default';
+
+export interface TodayKpiDefinition {
+  key: TodayWidgetKey;
+  titleKey: string;
+  icon: LucideIcon;
+  color: KpiCardColor;
+  orgTypes: OrgTypeName[];
+  isVisible: (org: Organization | null) => boolean;
+  formatValue: (widgets: TodaySummaryWidgets) => string | null;
+  formatSubtitle?: (widgets: TodaySummaryWidgets) => string | null;
+}
+
+function countWidget(
+  widgets: TodaySummaryWidgets,
+  key: TodayWidgetKey,
+): number | null {
+  const value = widgets[key];
+  if (!value || !('count' in value)) return null;
+  return value.count;
+}
+
+function canManageOrganizations(org: Organization | null): boolean {
+  if (!org) return false;
+  if (org.isOwner) return true;
+  return hasPermission(org, 'TAB_ORGANIZATIONS_EDIT');
+}
+
+function canViewPatients(org: Organization | null): boolean {
+  if (!org) return false;
+  return (
+    hasPermission(org, 'TAB_PATIENTS_READ') ||
+    hasPermission(org, 'TAB_PATIENTS_EDIT')
+  );
+}
+
+export const TODAY_KPI_DEFINITIONS: TodayKpiDefinition[] = [
+  {
+    key: 'appointmentsToday',
+    titleKey: 'widgetAppointmentsToday',
+    icon: CalendarDays,
+    color: 'blue',
+    orgTypes: ['CLINIC'],
+    isVisible: (org) => canAccessAppointmentsSection(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'appointmentsToday');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'patientsToday',
+    titleKey: 'widgetPatientsToday',
+    icon: Users,
+    color: 'green',
+    orgTypes: ['CLINIC'],
+    isVisible: (org) => canViewPatients(org) || canAccessAppointmentsSection(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'patientsToday');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'treatmentsToday',
+    titleKey: 'widgetTreatmentsToday',
+    icon: Stethoscope,
+    color: 'purple',
+    orgTypes: ['CLINIC'],
+    isVisible: (org) => canViewTreatment(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'treatmentsToday');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'draftTreatments',
+    titleKey: 'widgetDraftTreatments',
+    icon: ClipboardList,
+    color: 'yellow',
+    orgTypes: ['CLINIC'],
+    isVisible: (org) => canViewTreatment(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'draftTreatments');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'labCasesPendingSend',
+    titleKey: 'widgetLabCasesPendingSend',
+    icon: FlaskConical,
+    color: 'red',
+    orgTypes: ['CLINIC'],
+    isVisible: (org) => canViewTreatment(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'labCasesPendingSend');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'casesReceivedToday',
+    titleKey: 'widgetCasesReceivedToday',
+    icon: FlaskConical,
+    color: 'blue',
+    orgTypes: ['LAB'],
+    isVisible: (org) => canViewCases(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'casesReceivedToday');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'tasksInProgress',
+    titleKey: 'widgetTasksInProgress',
+    icon: ClipboardList,
+    color: 'yellow',
+    orgTypes: ['LAB'],
+    isVisible: (org) => canViewTasks(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'tasksInProgress');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'importantTasks',
+    titleKey: 'widgetImportantTasks',
+    icon: AlertCircle,
+    color: 'red',
+    orgTypes: ['LAB'],
+    isVisible: (org) => canViewTasks(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'importantTasks');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'pendingConnections',
+    titleKey: 'widgetPendingConnections',
+    icon: Link2,
+    color: 'yellow',
+    orgTypes: ['CLINIC', 'LAB'],
+    isVisible: (org) => canManageOrganizations(org),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'pendingConnections');
+      return count === null ? null : String(count);
+    },
+  },
+  {
+    key: 'seats',
+    titleKey: 'widgetSeats',
+    icon: UserCog,
+    color: 'default',
+    orgTypes: ['CLINIC', 'LAB'],
+    isVisible: (org) => canViewStaff(org),
+    formatValue: (widgets) => {
+      const seats = widgets.seats;
+      if (!seats || !('used' in seats)) return null;
+      if (seats.unlimited) return String(seats.used);
+      return `${seats.used}/${seats.limit ?? 0}`;
+    },
+    formatSubtitle: (widgets) => {
+      const seats = widgets.seats;
+      if (!seats || !('used' in seats)) return null;
+      return seats.unlimited ? 'unlimited' : null;
+    },
+  },
+  {
+    key: 'pendingStaffInvites',
+    titleKey: 'widgetPendingStaffInvites',
+    icon: UserCog,
+    color: 'purple',
+    orgTypes: ['CLINIC', 'LAB'],
+    isVisible: (org) => canEditStaff(org) || Boolean(org?.isOwner),
+    formatValue: (widgets) => {
+      const count = countWidget(widgets, 'pendingStaffInvites');
+      return count === null ? null : String(count);
+    },
+  },
+];
+
+export function getEligibleTodayKpis(org: Organization | null): TodayKpiDefinition[] {
+  if (!org) return [];
+
+  return TODAY_KPI_DEFINITIONS.filter((definition) => {
+    if (!definition.orgTypes.includes(org.type)) return false;
+    return definition.isVisible(org);
+  });
+}
+
+export function getVisibleTodayKpis(
+  org: Organization | null,
+  widgets: TodaySummaryWidgets,
+): TodayKpiDefinition[] {
+  return getEligibleTodayKpis(org).filter(
+    (definition) => definition.formatValue(widgets) !== null,
+  );
+}

frontend/src/lib/api/today.ts

@@ -0,0 +1,14 @@
+import { apiClient } from './client';
+import type { TodaySummaryResponse } from '@/types/today';
+
+export interface TodaySummaryParams {
+  from: string;
+  to: string;
+}
+
+export const todayApi = {
+  summary: async (params: TodaySummaryParams): Promise<TodaySummaryResponse> => {
+    const response = await apiClient.get('/today/summary', { params });
+    return response.data;
+  },
+};

frontend/src/lib/hooks/useTodaySummary.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { getLocalDayIsoRange } from '@/components/appointments/appointmentTime';
+import { todayApi } from '@/lib/api/today';
+import type { TodaySummaryData } from '@/types/today';
+import type { ApiError } from '@/types/api';
+
+interface UseTodaySummaryResult {
+  data: TodaySummaryData | null;
+  loading: boolean;
+  error: ApiError | null;
+  reload: () => Promise<void>;
+}
+
+export function useTodaySummary(enabled = true): UseTodaySummaryResult {
+  const [data, setData] = useState<TodaySummaryData | null>(null);
+  const [loading, setLoading] = useState(enabled);
+  const [error, setError] = useState<ApiError | null>(null);
+
+  const reload = useCallback(async () => {
+    if (!enabled) {
+      setData(null);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const range = getLocalDayIsoRange(new Date());
+      const response = await todayApi.summary(range);
+      setData(response.data);
+    } catch (err) {
+      setData(null);
+      setError(err as ApiError);
+    } finally {
+      setLoading(false);
+    }
+  }, [enabled]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  return { data, loading, error, reload };
+}

frontend/src/types/today.ts

@@ -0,0 +1,32 @@
+export type TodayWidgetKey =
+  | 'appointmentsToday'
+  | 'patientsToday'
+  | 'treatmentsToday'
+  | 'draftTreatments'
+  | 'labCasesPendingSend'
+  | 'casesReceivedToday'
+  | 'tasksInProgress'
+  | 'importantTasks'
+  | 'pendingConnections'
+  | 'seats'
+  | 'pendingStaffInvites';
+
+export type TodaySummaryWidgets = Partial<
+  Record<
+    TodayWidgetKey,
+    | { count: number }
+    | { used: number; limit: number | null; unlimited: boolean }
+  >
+>;
+
+export interface TodaySummaryData {
+  generatedAt: string;
+  orgType: 'CLINIC' | 'LAB';
+  range: { from: string; to: string };
+  widgets: TodaySummaryWidgets;
+}
+
+export interface TodaySummaryResponse {
+  success: boolean;
+  data: TodaySummaryData;
+}