Initial commit: Port Nimara CRM (Layers 0-4)

Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/hooks/use-realtime-invalidation.ts

@@ -0,0 +1,47 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useQueryClient, type QueryKey } from '@tanstack/react-query';
+
+import { useSocket } from '@/providers/socket-provider';
+
+/**
+ * Subscribes to socket events and invalidates React Query caches.
+ *
+ * @param eventMap - Maps socket event names to arrays of query keys to invalidate.
+ *
+ * @example
+ * useRealtimeInvalidation({
+ *   'client:created': [['clients']],
+ *   'client:updated': [['clients'], ['clients', clientId]],
+ *   'client:archived': [['clients']],
+ * });
+ */
+export function useRealtimeInvalidation(
+  eventMap: Record<string, QueryKey[]>,
+) {
+  const socket = useSocket();
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    if (!socket) return;
+
+    const handlers: Array<{ event: string; handler: (...args: unknown[]) => void }> = [];
+
+    for (const [event, queryKeys] of Object.entries(eventMap)) {
+      const handler = () => {
+        for (const key of queryKeys) {
+          queryClient.invalidateQueries({ queryKey: key });
+        }
+      };
+      socket.on(event as any, handler);
+      handlers.push({ event, handler });
+    }
+
+    return () => {
+      for (const { event, handler } of handlers) {
+        socket.off(event as any, handler);
+      }
+    };
+  }, [socket, queryClient, eventMap]);
+}