feat: add per-patient Local folder in Documents page backed by Cloud Storage

- Documents page shows a "Local Folder" card for each selected patient
  with an "Open in Cloud Storage" button that deep-links to their folder
- Cloud Storage page reads ?folderId URL param on mount and auto-opens
  the folder panel for seamless navigation from Documents
- Backend: GET /api/cloud-storage/patient-folder/:patientId endpoint
  that idempotently gets or creates a top-level CloudFolder per patient
- CloudFolder schema gains optional patientId field linked to Patient
- Disk directories for cloud storage folders now use the folder's name
  (e.g. "Xiaohui Wang/") instead of the opaque "folder-{id}/" path

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

apps/Backend/src/routes/cloud-storage.ts

@@ -2,6 +2,7 @@ import express, { Request, Response } from "express";
 import storage from "../storage";
 import { serializeFile } from "../utils/prismaFileUtils";
 import { CloudFolder } from "@repo/db/types";
+import { prisma as db } from "@repo/db/client";
 
 const router = express.Router();
 
@@ -133,6 +134,35 @@ router.get(
   }
 );
 
+// ---------- Patient-dedicated folder (get or create) ----------
+// GET /patient-folder/:patientId?userId=XXX
+router.get(
+  "/patient-folder/:patientId",
+  async (req: Request, res: Response): Promise<any> => {
+    const patientId = Number.parseInt(req.params.patientId ?? "", 10);
+    const userId = Number.parseInt(String(req.query.userId ?? ""), 10);
+
+    if (!Number.isInteger(patientId) || patientId <= 0)
+      return sendError(res, 400, "Invalid patientId");
+    if (!Number.isInteger(userId) || userId <= 0)
+      return sendError(res, 400, "Missing or invalid userId");
+
+    try {
+      const patient = await db.patient.findUnique({
+        where: { id: patientId },
+        select: { firstName: true, lastName: true },
+      });
+      if (!patient) return sendError(res, 404, "Patient not found");
+
+      const patientName = `${patient.firstName} ${patient.lastName}`.trim();
+      const folder = await storage.getOrCreatePatientFolder(userId, patientId, patientName);
+      return res.json({ error: false, data: folder });
+    } catch (err) {
+      return sendError(res, 500, "Failed to get or create patient folder", err);
+    }
+  }
+);
+
 // ---------- Folder CRUD ----------
 router.get(
   "/folders/:id",

apps/Backend/src/storage/cloudStorage-storage.ts

@@ -7,8 +7,20 @@ import path from "path";
 const CLOUD_ROOT = path.join(process.cwd(), "uploads", "cloud-storage");
 const CLOUD_TMP = path.join(CLOUD_ROOT, "tmp");
 
-function cloudFolderDir(folderId: number | null): string {
-  const dir = path.join(CLOUD_ROOT, folderId != null ? `folder-${folderId}` : "root");
+function sanitizeDirName(name: string): string {
+  return name.replace(/[/\\?%*:|"<>]/g, "-").trim() || "unnamed";
+}
+
+function cloudFolderDir(folderId: number | null, folderName?: string): string {
+  let dirName: string;
+  if (folderId == null) {
+    dirName = "root";
+  } else if (folderName) {
+    dirName = sanitizeDirName(folderName);
+  } else {
+    dirName = `folder-${folderId}`;
+  }
+  const dir = path.join(CLOUD_ROOT, dirName);
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -124,6 +136,13 @@ export interface IStorage {
 
   // Streaming
   streamFileTo(resStream: NodeJS.WritableStream, fileId: number): Promise<void>;
+
+  // Patient folder
+  getOrCreatePatientFolder(
+    userId: number,
+    patientId: number,
+    patientName: string
+  ): Promise<CloudFolder>;
 }
 
 /* ------------------------------- Implementation ------------------------------- */
@@ -295,6 +314,16 @@ export const cloudStorageStorage: IStorage = {
     });
     if (!file) throw new Error("File record not found");
 
+    // Look up folder name so the disk directory uses the human-readable name
+    let folderName: string | undefined;
+    if (file.folderId != null) {
+      const folder = await db.cloudFolder.findUnique({
+        where: { id: file.folderId },
+        select: { name: true },
+      });
+      folderName = folder?.name;
+    }
+
     const tmpDir = path.join(CLOUD_TMP, String(fileId));
     const chunkFiles = fs.existsSync(tmpDir)
       ? fs.readdirSync(tmpDir).filter((f) => f.startsWith("chunk-")).sort()
@@ -302,7 +331,7 @@ export const cloudStorageStorage: IStorage = {
     if (!chunkFiles.length) throw new Error("No chunks uploaded");
 
     // Assemble chunks into final file
-    const destDir = cloudFolderDir(file.folderId);
+    const destDir = cloudFolderDir(file.folderId, folderName);
     const safeName = file.name.replace(/[/\\?%*:|"<>]/g, "-");
     const destPath = path.join(destDir, `${Date.now()}_${safeName}`);
     const out = fs.openSync(destPath, "w");
@@ -500,6 +529,23 @@ export const cloudStorageStorage: IStorage = {
     return { data: files.map(serializeFile) as unknown as CloudFile[], total };
   },
 
+  // --- PATIENT FOLDER ---
+  async getOrCreatePatientFolder(
+    userId: number,
+    patientId: number,
+    patientName: string
+  ) {
+    const existing = await db.cloudFolder.findFirst({
+      where: { patientId },
+    });
+    if (existing) return existing as unknown as CloudFolder;
+
+    const created = await db.cloudFolder.create({
+      data: { userId, name: patientName, parentId: null, patientId },
+    });
+    return created as unknown as CloudFolder;
+  },
+
   // --- STREAM ---
   async streamFileTo(resStream: NodeJS.WritableStream, fileId: number) {
     const file = await db.cloudFile.findUnique({

apps/Frontend/src/pages/cloud-storage-page.tsx

@@ -1,4 +1,5 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
+import { useSearch } from "wouter";
 import { useQueryClient } from "@tanstack/react-query";
 import { Button } from "@/components/ui/button";
 import { Folder as FolderIcon, Search as SearchIcon } from "lucide-react";
@@ -20,6 +21,7 @@ export default function CloudStoragePage() {
   const { toast } = useToast();
   const { user } = useAuth();
   const qc = useQueryClient();
+  const search = useSearch();
 
   // panel open + initial folder id to show when opening
   const [panelOpen, setPanelOpen] = useState(false);
@@ -27,6 +29,16 @@ export default function CloudStoragePage() {
     number | null
   >(null);
 
+  // Deep-link: if navigated here with ?folderId=XXX, open that folder automatically
+  useEffect(() => {
+    const params = new URLSearchParams(search);
+    const id = Number(params.get("folderId"));
+    if (id > 0) {
+      setPanelInitialFolderId(id);
+      setPanelOpen(true);
+    }
+  }, [search]);
+
   // key to remount recent card to clear its internal selection when needed
   const [recentKey, setRecentKey] = useState(0);
 

apps/Frontend/src/pages/documents-page.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useState } from "react";
 import { useQuery, useMutation } from "@tanstack/react-query";
+import { useLocation } from "wouter";
 import {
   Card,
   CardHeader,
@@ -10,7 +11,8 @@ import {
 import { Button } from "@/components/ui/button";
 import { toast } from "@/hooks/use-toast";
 import { apiRequest, queryClient } from "@/lib/queryClient";
-import { Eye, Trash, Download, FolderOpen, FileText } from "lucide-react";
+import { Eye, Trash, Download, FolderOpen, FileText, HardDrive } from "lucide-react";
+import { useAuth } from "@/hooks/use-auth";
 import { DeleteConfirmationDialog } from "@/components/ui/deleteDialog";
 import { PatientTable } from "@/components/patients/patient-table";
 import { Patient, PdfFile } from "@repo/db/types";
@@ -32,6 +34,8 @@ import {
 } from "@/lib/api/documents";
 
 export default function DocumentsPage() {
+  const { user } = useAuth();
+  const [, setLocation] = useLocation();
   const [selectedPatient, setSelectedPatient] = useState<Patient | null>(null);
   const [expandedGroupId, setExpandedGroupId] = useState<number | null>(null);
 
@@ -200,6 +204,22 @@ export default function DocumentsPage() {
     return { map, orderedKeys };
   }, [groups]);
 
+  // FETCH patient's dedicated local (cloud storage) folder
+  const { data: patientCloudFolder, isLoading: isLoadingCloudFolder } = useQuery({
+    queryKey: ["patientCloudFolder", selectedPatient?.id, user?.id],
+    enabled: !!selectedPatient?.id && !!user?.id,
+    staleTime: 5 * 60 * 1000,
+    queryFn: async () => {
+      const res = await apiRequest(
+        "GET",
+        `/api/cloud-storage/patient-folder/${selectedPatient!.id}?userId=${user!.id}`
+      );
+      const json = await res.json();
+      if (json.error) throw new Error(json.message);
+      return json.data as { id: number; name: string };
+    },
+  });
+
   // FETCH PDFs for selected group with pagination (limit & offset)
   const {
     data: groupPdfsResponse,
@@ -324,6 +344,32 @@ export default function DocumentsPage() {
 
             <CardContent className="space-y-4">
 
+              {/* Local Folder (Cloud Storage) */}
+              <div className="border rounded p-3">
+                <div className="flex items-center justify-between">
+                  <div className="flex items-center gap-3">
+                    <HardDrive className="w-5 h-5 text-blue-500" />
+                    <div>
+                      <div className="font-semibold">
+                        {isLoadingCloudFolder
+                          ? "Loading…"
+                          : patientCloudFolder?.name ?? "Local Folder"}
+                      </div>
+                      <div className="text-xs text-muted-foreground">Local disk storage</div>
+                    </div>
+                  </div>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    disabled={!patientCloudFolder}
+                    onClick={() =>
+                      setLocation(`/cloud-storage?folderId=${patientCloudFolder!.id}`)
+                    }
+                  >
+                    Open in Cloud Storage
+                  </Button>
+                </div>
+              </div>
 
               {/* Existing Groups Section */}
               <div>