Add customizable home dashboard with per-user pinned apps

- Users can pin/unpin any available service on their home page via a
  Customize mode; preferences persisted via PATCH /api/users/me/preferences
- Time-aware greeting renders the user's display name through React JSX
  (HTML-escaped by design — no dangerouslySetInnerHTML used)
- Added dashboard_app_ids JSON column to users table (migration c7e8f9a0b1d2)
- /settings now routes to a placeholder page

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/STATUS.md

@@ -25,6 +25,8 @@ JWT signing uses a 4096-bit RSA key pair (`RS256`). Keys are generated by `scrip
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/api/users/me` | Current user info |
+| `GET` | `/api/users/me/preferences` | User's dashboard preferences (`app_ids` list) |
+| `PATCH` | `/api/users/me/preferences` | Update pinned app IDs (max 50; validated as safe slugs) |
 
 ### Profile (`/api/profile`)
 
@@ -84,7 +86,7 @@ All `/api/documents/*` and `/api/documents/categories/*` requests are transparen
 
 | Model | Table | Notes |
 |-------|-------|-------|
-| `User` | `users` | email, hashed_password, role (`user`\|`admin`), is_active |
+| `User` | `users` | email, hashed_password, role (`user`\|`admin`), is_active, dashboard_app_ids (JSON) |
 | `Profile` | `profiles` | one-to-one with User; full_name, phone, etc. |
 | `Group` | `groups` | name (unique), description, created_at |
 | `GroupMembership` | `group_memberships` | group_id + user_id (unique pair); joined_at |

backend/alembic/versions/c7e8f9a0b1d2_add_dashboard_app_ids_to_users.py

@@ -0,0 +1,28 @@
+"""add dashboard_app_ids to users
+
+Revision ID: c7e8f9a0b1d2
+Revises: a3f9c2d14e87
+Create Date: 2026-04-17 14:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = 'c7e8f9a0b1d2'
+down_revision: Union[str, None] = 'a3f9c2d14e87'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        'users',
+        sa.Column('dashboard_app_ids', sa.JSON(), nullable=False, server_default='[]'),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column('users', 'dashboard_app_ids')

backend/app/models/user.py

@@ -1,7 +1,7 @@
 import uuid
 from typing import TYPE_CHECKING
 
-from sqlalchemy import Boolean, String
+from sqlalchemy import Boolean, JSON, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database import Base
@@ -21,6 +21,8 @@ class User(Base):
     # Role flag — True = admin, False = regular user.
     # Never exposed in API responses; set only by direct DB or admin tooling.
     is_superuser: Mapped[bool] = mapped_column(Boolean, default=False)
+    # List of service IDs pinned to the user's home dashboard.
+    dashboard_app_ids: Mapped[list] = mapped_column(JSON, nullable=False, default=list)
 
     profile: Mapped["Profile"] = relationship(
         "Profile", back_populates="user", uselist=False, cascade="all, delete-orphan"

backend/app/routers/users.py

@@ -1,8 +1,10 @@
 from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.database import get_db
 from app.deps import get_current_user
 from app.models.user import User
-from app.schemas.user import UserOut
+from app.schemas.user import DashboardPrefsOut, DashboardPrefsUpdate, UserOut
 
 router = APIRouter()
 
@@ -10,3 +12,20 @@ router = APIRouter()
 @router.get("/me", response_model=UserOut)
 async def get_me(current_user: User = Depends(get_current_user)):
     return current_user
+
+
+@router.get("/me/preferences", response_model=DashboardPrefsOut)
+async def get_preferences(current_user: User = Depends(get_current_user)):
+    return DashboardPrefsOut(app_ids=current_user.dashboard_app_ids or [])
+
+
+@router.patch("/me/preferences", response_model=DashboardPrefsOut)
+async def update_preferences(
+    body: DashboardPrefsUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    current_user.dashboard_app_ids = body.app_ids
+    await db.commit()
+    await db.refresh(current_user)
+    return DashboardPrefsOut(app_ids=current_user.dashboard_app_ids or [])

backend/app/schemas/user.py

@@ -96,3 +96,24 @@ class UserAdminCreate(UserCreate):
 class Token(BaseModel):
     access_token: str
     token_type: str = "bearer"
+
+
+# ── Dashboard preferences ──────────────────────────────────────────────────────
+
+class DashboardPrefsOut(BaseModel):
+    app_ids: list[str]
+
+
+class DashboardPrefsUpdate(BaseModel):
+    app_ids: list[str] = Field(default_factory=list)
+
+    @field_validator("app_ids")
+    @classmethod
+    def validate_app_ids(cls, v: list[str]) -> list[str]:
+        if len(v) > 50:
+            raise ValueError("Cannot pin more than 50 apps")
+        for item in v:
+            # Service IDs are alphanumeric slugs or UUIDs — no HTML/script allowed.
+            if not re.match(r'^[a-zA-Z0-9_\-]{1,64}$', item):
+                raise ValueError(f"Invalid app ID: {item!r}")
+        return v

changelog/2026-04-17_customizable-home-dashboard.md

@@ -0,0 +1,23 @@
+# 2026-04-17 — Customizable home dashboard and settings placeholder
+
+**Timestamp:** 2026-04-17T14:00:00+00:00
+
+## Summary
+
+Replaced the static dashboard page with a per-user customizable home screen. Each user can pin and unpin apps from the available services list. A time-aware greeting shows the user's display name (XSS-safe via React JSX text rendering). The Settings navigation item now routes to a placeholder page.
+
+## Files Added / Modified / Deleted
+
+### Added
+- `backend/alembic/versions/c7e8f9a0b1d2_add_dashboard_app_ids_to_users.py` — Migration adding `dashboard_app_ids` JSON column to `users` table (default `[]`; non-nullable)
+- `frontend/src/pages/SettingsPage.tsx` — Placeholder settings page at `/settings`
+
+### Modified
+- `backend/app/models/user.py` — Added `dashboard_app_ids: Mapped[list]` JSON column
+- `backend/app/schemas/user.py` — Added `DashboardPrefsOut` and `DashboardPrefsUpdate` schemas; `app_ids` validated as safe slugs (regex, max 50, max 64 chars each)
+- `backend/app/routers/users.py` — Added `GET /api/users/me/preferences` and `PATCH /api/users/me/preferences` endpoints
+- `frontend/src/api/client.ts` — Added `DashboardPrefs` interface, `getDashboardPrefs()`, `updateDashboardPrefs()`
+- `frontend/src/pages/DashboardPage.tsx` — Full rewrite: greeting, pinned app cards grid, customize/edit mode with add/remove toggles, save via TanStack Query mutation
+- `frontend/src/App.tsx` — Imported `SettingsPage`, registered `/settings` route
+- `backend/STATUS.md` — Updated Users endpoints table and models table
+- `frontend/STATUS.md` — Added home dashboard section, added `/settings` to routes table

frontend/STATUS.md

@@ -22,6 +22,7 @@ All API calls go through `src/api/client.ts` (single Axios instance, JWT injecte
 | `/admin/users` | `AdminUsersPage` | Admin only |
 | `/admin/groups` | `AdminGroupsPage` | Admin only |
 | `/profile` | `ProfilePage` | Required |
+| `/settings` | `SettingsPage` (placeholder) | Required |
 
 `PrivateRoute` redirects to `/login` when no token. `AdminRoute` redirects to `/` when not admin.
 
@@ -35,6 +36,14 @@ All API calls go through `src/api/client.ts` (single Axios instance, JWT injecte
 - Logout clears token and redirects to `/login`
 - `GET /api/users/me` verifies token on protected routes
 
+### Home dashboard (`/`)
+
+Personalised landing page per user:
+- Time-aware greeting with the user's display name (`full_name` or email). React JSX text rendering HTML-escapes all values — no `dangerouslySetInnerHTML` is used anywhere on this page.
+- Grid of **pinned app cards** drawn from `GET /api/services`, filtered to the user's saved list.
+- **Customize mode** (pencil button): shows all services; `+` / `−` toggle buttons on each card; changes committed with **Save** via `PATCH /api/users/me/preferences`.
+- Empty-state prompt when no apps are pinned.
+
 ### Apps page (`/apps`)
 
 Cards are rendered dynamically from `GET /api/services` (polled every 30 s via TanStack Query):

frontend/src/App.tsx

@@ -13,6 +13,7 @@ import AdminGroupsPage from "./pages/AdminGroupsPage";
 import DocumentsPage from "./pages/DocumentsPage";
 import DocumentAdminSettingsPage from "./pages/DocumentAdminSettingsPage";
 import AIAdminSettingsPage from "./pages/AIAdminSettingsPage";
+import SettingsPage from "./pages/SettingsPage";
 
 function PrivateRoute({ children }: { children: React.ReactNode }) {
   const { token } = useAuth();
@@ -52,6 +53,7 @@ export default function App() {
         element={<AdminRoute><AIAdminSettingsPage /></AdminRoute>}
       />
       <Route path="/profile" element={<PrivateRoute><ProfilePage /></PrivateRoute>} />
+      <Route path="/settings" element={<PrivateRoute><SettingsPage /></PrivateRoute>} />
       <Route path="/admin" element={<AdminRoute><AdminPage /></AdminRoute>} />
       <Route path="/admin/users" element={<AdminRoute><AdminUsersPage /></AdminRoute>} />
       <Route path="/admin/groups" element={<AdminRoute><AdminGroupsPage /></AdminRoute>} />

frontend/src/api/client.ts

@@ -30,6 +30,16 @@ export interface UserData {
 
 export const getMe = () => api.get<UserData>("/users/me").then((r) => r.data);
 
+export interface DashboardPrefs {
+  app_ids: string[];
+}
+
+export const getDashboardPrefs = () =>
+  api.get<DashboardPrefs>("/users/me/preferences").then((r) => r.data);
+
+export const updateDashboardPrefs = (app_ids: string[]) =>
+  api.patch<DashboardPrefs>("/users/me/preferences", { app_ids }).then((r) => r.data);
+
 // --- Admin ---
 export interface AdminUserCreate {
   email: string;

frontend/src/pages/DashboardPage.tsx

@@ -1,13 +1,239 @@
-import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
-import { getMe } from "../api/client";
+import { Link } from "react-router-dom";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { Pencil, Check, X, Plus, Minus, ExternalLink } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import {
+  getMe,
+  getServices,
+  getDashboardPrefs,
+  updateDashboardPrefs,
+  type ServiceStatus,
+} from "../api/client";
 
 export default function DashboardPage() {
+  const queryClient = useQueryClient();
+  const [editing, setEditing] = useState(false);
+  // Tracks pending changes while in edit mode — only committed on Save.
+  const [pendingIds, setPendingIds] = useState<string[]>([]);
+
   const { data: user } = useQuery({ queryKey: ["me"], queryFn: getMe });
+  const { data: services = [] } = useQuery({
+    queryKey: ["services"],
+    queryFn: getServices,
+    refetchInterval: 30_000,
+    refetchIntervalInBackground: true,
+  });
+  const { data: prefs } = useQuery({
+    queryKey: ["dashboard-prefs"],
+    queryFn: getDashboardPrefs,
+    enabled: !!user,
+  });
+
+  const savePrefs = useMutation({
+    mutationFn: updateDashboardPrefs,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["dashboard-prefs"] });
+      setEditing(false);
+    },
+  });
+
+  const pinnedIds: string[] = editing ? pendingIds : (prefs?.app_ids ?? []);
+  const pinnedServices = services.filter((s) => pinnedIds.includes(s.id));
+  const unpinnedServices = services.filter((s) => !pinnedIds.includes(s.id));
+
+  function startEditing() {
+    setPendingIds(prefs?.app_ids ?? []);
+    setEditing(true);
+  }
+
+  function cancelEditing() {
+    setEditing(false);
+    setPendingIds([]);
+  }
+
+  function toggleApp(id: string) {
+    setPendingIds((prev) =>
+      prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id]
+    );
+  }
+
+  function handleSave() {
+    savePrefs.mutate(pendingIds);
+  }
+
+  // Determine greeting: safe because React JSX text nodes are HTML-escaped by
+  // the renderer — no dangerouslySetInnerHTML is used anywhere here.
+  const displayName = user?.full_name?.trim() || user?.email || "there";
+  const hour = new Date().getHours();
+  const greeting =
+    hour < 12 ? "Good morning" : hour < 18 ? "Good afternoon" : "Good evening";
 
   return (
-    <div>
+    <div className="p-8 max-w-4xl mx-auto">
-      <h1 className="text-2xl font-semibold text-foreground mb-2">Dashboard</h1>
+      {/* Welcome header */}
-      {user && <p className="text-muted">Welcome, {user.full_name ?? user.email}</p>}
+      <div className="mb-8">
+        <h1 className="text-3xl font-semibold text-foreground">
+          {greeting}, {displayName}!
+        </h1>
+        <p className="text-muted mt-1 text-sm">
+          Here are your pinned apps. Customize your dashboard below.
+        </p>
+      </div>
+
+      {/* Toolbar */}
+      <div className="flex items-center justify-between mb-4">
+        <h2 className="text-base font-medium text-foreground">My Apps</h2>
+        {editing ? (
+          <div className="flex gap-2">
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={cancelEditing}
+              disabled={savePrefs.isPending}
+            >
+              <X className="h-4 w-4 mr-1" />
+              Cancel
+            </Button>
+            <Button
+              size="sm"
+              onClick={handleSave}
+              disabled={savePrefs.isPending}
+            >
+              <Check className="h-4 w-4 mr-1" />
+              {savePrefs.isPending ? "Saving…" : "Save"}
+            </Button>
+          </div>
+        ) : (
+          <Button size="sm" variant="outline" onClick={startEditing}>
+            <Pencil className="h-4 w-4 mr-1" />
+            Customize
+          </Button>
+        )}
+      </div>
+
+      {/* Pinned apps grid */}
+      {!editing && pinnedServices.length === 0 && (
+        <div className="text-center py-16 text-muted border border-dashed border-border rounded-xl">
+          <p className="text-sm">No apps pinned yet.</p>
+          <Button
+            size="sm"
+            variant="outline"
+            className="mt-3"
+            onClick={startEditing}
+          >
+            <Plus className="h-4 w-4 mr-1" />
+            Add apps
+          </Button>
+        </div>
+      )}
+
+      {pinnedServices.length > 0 && (
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 mb-8">
+          {pinnedServices.map((svc) => (
+            <AppCard
+              key={svc.id}
+              svc={svc}
+              editing={editing}
+              pinned
+              onToggle={toggleApp}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Edit mode — available apps to add */}
+      {editing && unpinnedServices.length > 0 && (
+        <>
+          <h2 className="text-base font-medium text-foreground mb-3 mt-6">
+            Available Apps
+          </h2>
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+            {unpinnedServices.map((svc) => (
+              <AppCard
+                key={svc.id}
+                svc={svc}
+                editing
+                pinned={false}
+                onToggle={toggleApp}
+              />
+            ))}
+          </div>
+        </>
+      )}
+
+      {savePrefs.isError && (
+        <p className="text-sm text-red-500 mt-4">
+          Failed to save preferences. Please try again.
+        </p>
+      )}
+    </div>
+  );
+}
+
+interface AppCardProps {
+  svc: ServiceStatus;
+  editing: boolean;
+  pinned: boolean;
+  onToggle: (id: string) => void;
+}
+
+function AppCard({ svc, editing, pinned, onToggle }: AppCardProps) {
+  const canOpen = svc.healthy && !!svc.app_path;
+
+  return (
+    <div
+      className={cn(
+        "relative rounded-xl border border-border bg-surface p-5 flex flex-col gap-2 transition-opacity",
+        !svc.healthy && "opacity-60"
+      )}
+    >
+      {/* Edit overlay button */}
+      {editing && (
+        <button
+          onClick={() => onToggle(svc.id)}
+          className={cn(
+            "absolute top-3 right-3 rounded-full p-1 transition-colors",
+            pinned
+              ? "bg-red-100 text-red-600 hover:bg-red-200"
+              : "bg-green-100 text-green-700 hover:bg-green-200"
+          )}
+          title={pinned ? "Remove from dashboard" : "Add to dashboard"}
+        >
+          {pinned ? (
+            <Minus className="h-4 w-4" />
+          ) : (
+            <Plus className="h-4 w-4" />
+          )}
+        </button>
+      )}
+
+      <div className="flex items-center justify-between pr-6">
+        <h3 className="text-sm font-semibold text-foreground">{svc.name}</h3>
+        <span
+          className={cn(
+            "text-xs font-medium",
+            svc.healthy ? "text-emerald-600" : "text-red-500"
+          )}
+        >
+          {svc.healthy ? "Available" : "Unavailable"}
+        </span>
+      </div>
+
+      <p className="text-xs text-muted leading-relaxed">{svc.description}</p>
+
+      {!editing && canOpen && (
+        <div className="mt-auto pt-2">
+          <Link
+            to={svc.app_path}
+            className="inline-flex items-center gap-1 text-xs text-primary hover:underline font-medium"
+          >
+            Open
+            <ExternalLink className="h-3 w-3" />
+          </Link>
+        </div>
+      )}
     </div>
   );
 }

frontend/src/pages/SettingsPage.tsx

@@ -0,0 +1,15 @@
+import { Settings } from "lucide-react";
+
+export default function SettingsPage() {
+  return (
+    <div className="p-8 max-w-2xl mx-auto">
+      <div className="flex items-center gap-3 mb-2">
+        <Settings className="h-6 w-6 text-muted" />
+        <h1 className="text-2xl font-semibold text-foreground">Settings</h1>
+      </div>
+      <p className="text-muted text-sm">
+        User and application settings will be available here in a future update.
+      </p>
+    </div>
+  );
+}