feat: Phase 3 - Fix optimistic updates with stable UUIDs and visual indicators

archon-ui-main/package.json

@@ -44,6 +44,7 @@
     "fractional-indexing": "^3.2.0",
     "framer-motion": "^11.5.4",
     "lucide-react": "^0.441.0",
+    "nanoid": "^5.0.9",
     "prismjs": "^1.30.0",
     "react": "^18.3.1",
     "react-dnd": "^16.0.1",

archon-ui-main/src/features/knowledge/components/KnowledgeCard.tsx

@@ -8,9 +8,11 @@ import { format } from "date-fns";
 import { motion } from "framer-motion";
 import { Briefcase, Clock, Code, ExternalLink, File, FileText, Globe, Terminal } from "lucide-react";
 import { useState } from "react";
+import { isOptimistic } from "../../shared/optimistic";
 import { KnowledgeCardProgress } from "../../progress/components/KnowledgeCardProgress";
 import type { ActiveOperation } from "../../progress/types";
 import { StatPill } from "../../ui/primitives";
+import { OptimisticIndicator } from "../../ui/primitives/OptimisticIndicator";
 import { cn } from "../../ui/primitives/styles";
 import { SimpleTooltip } from "../../ui/primitives/tooltip";
 import { useDeleteKnowledgeItem, useRefreshKnowledgeItem } from "../hooks";
@@ -44,6 +46,9 @@ export const KnowledgeCard: React.FC<KnowledgeCardProps> = ({
   const deleteMutation = useDeleteKnowledgeItem();
   const refreshMutation = useRefreshKnowledgeItem();
 
+  // Check if item is optimistic
+  const optimistic = isOptimistic(item);
+
   // Determine card styling based on type and status
   // Check if it's a real URL (not a file:// URL)
   // Prioritize top-level source_type over metadata source_type
@@ -168,6 +173,7 @@ export const KnowledgeCard: React.FC<KnowledgeCardProps> = ({
           getBorderColor(),
           isHovered && "shadow-[0_0_30px_rgba(6,182,212,0.2)]",
           "min-h-[240px] flex flex-col",
+          optimistic && "opacity-80 ring-1 ring-cyan-400/30",
         )}
       >
         {/* Top accent glow tied to type (does not change size) */}
@@ -235,6 +241,7 @@ export const KnowledgeCard: React.FC<KnowledgeCardProps> = ({
               description={item.metadata?.description}
               accentColor={getAccentColorName()}
             />
+            <OptimisticIndicator isOptimistic={optimistic} className="mt-2" />
           </div>
 
           {/* URL/Source */}

archon-ui-main/src/features/knowledge/hooks/useKnowledgeQueries.ts

@@ -5,6 +5,7 @@
 
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useEffect, useMemo, useState } from "react";
+import { createOptimisticId } from "@/features/shared/optimistic";
 import { useActiveOperations } from "../../progress/hooks";
 import { progressKeys } from "../../progress/hooks/useProgressQueries";
 import type { ActiveOperation, ActiveOperationsResponse } from "../../progress/types";
@@ -139,8 +140,8 @@ export function useCrawlUrl() {
       const previousOperations = queryClient.getQueryData<ActiveOperationsResponse>(progressKeys.active());
 
       // Generate temporary IDs
-      const tempProgressId = `temp-progress-${Date.now()}`;
-      const tempItemId = `temp-item-${Date.now()}`;
+      const tempProgressId = createOptimisticId();
+      const tempItemId = createOptimisticId();
 
       // Create optimistic knowledge item
       const optimisticItem: KnowledgeItem = {
@@ -353,8 +354,8 @@ export function useUploadDocument() {
       const previousOperations = queryClient.getQueryData<ActiveOperationsResponse>(progressKeys.active());
 
       // Generate temporary IDs
-      const tempProgressId = `temp-upload-${Date.now()}`;
-      const tempItemId = `temp-item-${Date.now()}`;
+      const tempProgressId = createOptimisticId();
+      const tempItemId = createOptimisticId();
 
       // Create optimistic knowledge item for the upload
       const optimisticItem: KnowledgeItem = {

archon-ui-main/src/features/projects/components/ProjectCard.tsx

@@ -1,6 +1,8 @@
 import { motion } from "framer-motion";
 import { Activity, CheckCircle2, ListTodo } from "lucide-react";
 import type React from "react";
+import { isOptimistic } from "../../shared/optimistic";
+import { OptimisticIndicator } from "../../ui/primitives/OptimisticIndicator";
 import { cn } from "../../ui/primitives/styles";
 import type { Project } from "../types";
 import { ProjectCardActions } from "./ProjectCardActions";
@@ -27,6 +29,9 @@ export const ProjectCard: React.FC<ProjectCardProps> = ({
   onPin,
   onDelete,
 }) => {
+  // Check if project is optimistic
+  const optimistic = isOptimistic(project);
+
   return (
     <motion.div
       tabIndex={0}
@@ -59,6 +64,7 @@ export const ProjectCard: React.FC<ProjectCardProps> = ({
           : "shadow-[0_10px_30px_-15px_rgba(0,0,0,0.1)] dark:shadow-[0_10px_30px_-15px_rgba(0,0,0,0.7)]",
         "hover:shadow-[0_15px_40px_-15px_rgba(0,0,0,0.2)] dark:hover:shadow-[0_15px_40px_-15px_rgba(0,0,0,0.9)]",
         isSelected ? "scale-[1.02]" : "hover:scale-[1.01]", // Use scale instead of translate to avoid clipping
+        optimistic && "opacity-80 ring-1 ring-cyan-400/30",
       )}
     >
       {/* Subtle aurora glow effect for selected card */}
@@ -71,7 +77,7 @@ export const ProjectCard: React.FC<ProjectCardProps> = ({
       {/* Main content area with padding */}
       <div className="flex-1 p-4 pb-2">
         {/* Title section */}
-        <div className="flex items-center justify-center mb-4 min-h-[48px]">
+        <div className="flex flex-col items-center justify-center mb-4 min-h-[48px]">
           <h3
             className={cn(
               "font-medium text-center leading-tight line-clamp-2 transition-all duration-300",
@@ -84,6 +90,7 @@ export const ProjectCard: React.FC<ProjectCardProps> = ({
           >
             {project.title}
           </h3>
+          <OptimisticIndicator isOptimistic={optimistic} className="mt-1" />
         </div>
 
         {/* Task count pills */}

archon-ui-main/src/features/projects/hooks/useProjectQueries.ts

@@ -1,4 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createOptimisticEntity, replaceOptimisticEntity, removeDuplicateEntities, type OptimisticEntity } from "@/features/shared/optimistic";
 import { DISABLED_QUERY_KEY, STALE_TIMES } from "../../shared/queryPatterns";
 import { useSmartPolling } from "../../ui/hooks";
 import { useToast } from "../../ui/hooks/useToast";
@@ -54,21 +55,20 @@ export function useCreateProject() {
       // Snapshot the previous value
       const previousProjects = queryClient.getQueryData<Project[]>(projectKeys.lists());
 
-      // Create optimistic project with temporary ID
-      const tempId = `temp-${Date.now()}`;
-      const optimisticProject: Project = {
-        id: tempId, // Temporary ID until real one comes back
-        title: newProjectData.title,
-        description: newProjectData.description,
-        github_repo: newProjectData.github_repo,
-        created_at: new Date().toISOString(),
-        updated_at: new Date().toISOString(),
-        prd: undefined,
-        features: [],
-        data: undefined,
-        docs: [],
-        pinned: false,
-      };
+      // Create optimistic project with stable ID
+      const optimisticProject = createOptimisticEntity<Project>(
+        {
+          title: newProjectData.title,
+          description: newProjectData.description,
+          github_repo: newProjectData.github_repo,
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+          docs: [],
+          features: [],
+          prd: null,
+          data_schema: null,
+        }
+      );
 
       // Optimistically add the new project
       queryClient.setQueryData(projectKeys.lists(), (old: Project[] | undefined) => {
@@ -77,7 +77,7 @@ export function useCreateProject() {
         return [optimisticProject, ...old];
       });
 
-      return { previousProjects, tempId };
+      return { previousProjects, optimisticId: optimisticProject._localId };
     },
     onError: (error, variables, context) => {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -94,18 +94,14 @@ export function useCreateProject() {
       // Extract the actual project from the response
       const newProject = response.project;
 
-      // Replace optimistic project with real one from server
-      queryClient.setQueryData(projectKeys.lists(), (old: Project[] | undefined) => {
-        if (!old) return [newProject];
-        // Replace only the specific temp project with real one
-        return old
-          .map((project) => (project.id === context?.tempId ? newProject : project))
-          .filter(
-            (project, index, self) =>
-              // Remove any duplicates just in case
-              index === self.findIndex((p) => p.id === project.id),
-          );
-      });
+      // Replace optimistic with server data
+      queryClient.setQueryData(
+        projectKeys.lists(),
+        (projects: (Project & Partial<OptimisticEntity>)[] = []) => {
+          const replaced = replaceOptimisticEntity(projects, context?.optimisticId || "", newProject);
+          return removeDuplicateEntities(replaced);
+        }
+      );
 
       showToast("Project created successfully!", "success");
     },

archon-ui-main/src/features/projects/tasks/components/TaskCard.tsx

@@ -2,6 +2,8 @@ import { Tag } from "lucide-react";
 import type React from "react";
 import { useCallback } from "react";
 import { useDrag, useDrop } from "react-dnd";
+import { isOptimistic } from "../../../shared/optimistic";
+import { OptimisticIndicator } from "../../../ui/primitives/OptimisticIndicator";
 import { useTaskActions } from "../hooks";
 import type { Assignee, Task, TaskPriority } from "../types";
 import { getOrderColor, getOrderGlow, ItemTypes } from "../utils/task-styles";
@@ -34,6 +36,9 @@ export const TaskCard: React.FC<TaskCardProps> = ({
   selectedTasks,
   onTaskSelect,
 }) => {
+  // Check if task is optimistic
+  const optimistic = isOptimistic(task);
+
   // Use business logic hook with changePriority
   const { changeAssignee, changePriority, isUpdating } = useTaskActions(projectId);
 
@@ -152,7 +157,7 @@ export const TaskCard: React.FC<TaskCardProps> = ({
       }}
     >
       <div
-        className={`${cardBaseStyles} ${transitionStyles} ${hoverEffectClasses} ${highlightGlow} ${selectionGlow} w-full min-h-[140px] h-full`}
+        className={`${cardBaseStyles} ${transitionStyles} ${hoverEffectClasses} ${highlightGlow} ${selectionGlow} ${optimistic ? "opacity-80 ring-1 ring-cyan-400/30" : ""} w-full min-h-[140px] h-full`}
       >
         {/* Priority indicator with beautiful glow */}
         <div
@@ -177,8 +182,11 @@ export const TaskCard: React.FC<TaskCardProps> = ({
               </div>
             )}
 
+            {/* Optimistic indicator */}
+            <OptimisticIndicator isOptimistic={optimistic} className="ml-auto" />
+
             {/* Action buttons group */}
-            <div className="ml-auto flex items-center gap-1.5">
+            <div className={`${optimistic ? "" : "ml-auto"} flex items-center gap-1.5`}>
               <TaskCardActions
                 taskId={task.id}
                 taskTitle={task.title}

archon-ui-main/src/features/projects/tasks/hooks/useTaskQueries.ts

@@ -1,4 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createOptimisticEntity, replaceOptimisticEntity, removeDuplicateEntities, type OptimisticEntity } from "@/features/shared/optimistic";
 import { DISABLED_QUERY_KEY, STALE_TIMES } from "../../../shared/queryPatterns";
 import { useSmartPolling } from "../../../ui/hooks";
 import { useToast } from "../../../ui/hooks/useToast";
@@ -55,26 +56,29 @@ export function useCreateTask() {
       // Snapshot the previous value
       const previousTasks = queryClient.getQueryData<Task[]>(taskKeys.byProject(newTaskData.project_id));
 
-      // Create optimistic task with temporary ID
-      const tempId = `temp-${Date.now()}`;
-      const optimisticTask: Task = {
-        id: tempId, // Temporary ID until real one comes back
-        ...newTaskData,
-        created_at: new Date().toISOString(),
-        updated_at: new Date().toISOString(),
-        // Ensure all required fields have defaults (let backend handle assignee default)
-        task_order: newTaskData.task_order ?? 100,
-        status: newTaskData.status ?? "todo",
-        assignee: newTaskData.assignee ?? "User", // Keep for now as UI needs a value for optimistic update
-      } as Task;
+      // Create optimistic task with stable ID
+      const optimisticTask = createOptimisticEntity<Task>(
+        {
+          project_id: newTaskData.project_id,
+          title: newTaskData.title,
+          description: newTaskData.description || "",
+          status: newTaskData.status ?? "todo",
+          assignee: newTaskData.assignee ?? "User",
+          feature: newTaskData.feature,
+          task_order: newTaskData.task_order ?? 100,
+          priority: newTaskData.priority ?? "medium",
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+        }
+      );
 
       // Optimistically add the new task
       queryClient.setQueryData(taskKeys.byProject(newTaskData.project_id), (old: Task[] | undefined) => {
         if (!old) return [optimisticTask];
         return [...old, optimisticTask];
       });
 
-      return { previousTasks, tempId };
+      return { previousTasks, optimisticId: optimisticTask._localId };
     },
     onError: (error, variables, context) => {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -85,20 +89,21 @@ export function useCreateTask() {
       }
       showToast(`Failed to create task: ${errorMessage}`, "error");
     },
-    onSuccess: (data, variables, context) => {
-      // Replace optimistic task with real one from server
-      queryClient.setQueryData(taskKeys.byProject(variables.project_id), (old: Task[] | undefined) => {
-        if (!old) return [data];
-        // Replace only the specific temp task with real one
-        return old
-          .map((task) => (task.id === context?.tempId ? data : task))
-          .filter(
-            (task, index, self) =>
-              // Remove any duplicates just in case
-              index === self.findIndex((t) => t.id === task.id),
-          );
+    onSuccess: (serverTask, variables, context) => {
+      // Replace optimistic with server data
+      queryClient.setQueryData(
+        taskKeys.byProject(variables.project_id),
+        (tasks: (Task & Partial<OptimisticEntity>)[] = []) => {
+          const replaced = replaceOptimisticEntity(tasks, context?.optimisticId || "", serverTask);
+          return removeDuplicateEntities(replaced);
+        }
+      );
+
+      // Invalidate counts since we have a new task
+      queryClient.invalidateQueries({
+        queryKey: taskKeys.counts(),
       });
-      queryClient.invalidateQueries({ queryKey: taskKeys.counts() });
+
       showToast("Task created successfully", "success");
     },
     onSettled: (_data, _error, variables) => {