fix: documentation

PERFORMANCE_IMPROVEMENTS.md

@@ -0,0 +1,70 @@
+# Performance Improvements Plan
+
+## 1. Executive Summary
+
+This document outlines identified performance bottlenecks in the ZUI application and proposes concrete actions to improve render efficiency, state management, and code splitting. The plan is targeted at enabling junior developers to contribute measurable performance gains while maintaining code quality.
+
+## 2. Current Performance Issues
+
+| Issue | Location | Impact | Root Cause |
+|-------|----------|--------|------------|
+| **Large Component Renders** | `frontend/src/app/canvas/CanvasPage.tsx`, `frontend/src/app/recollections/RecollectionPage.tsx` | High CPU usage, frame drops | These components render thousands of nodes without memoization; state updates trigger full re-renders. |
+| **Unmemoized Expensive Calculations** | Various utility functions in `src/lib/*` (e.g., graph layout calculations) | Delayed response to user interactions | Calculations recomputed on every render cycle. |
+| **Frequent State Updates** | `canvasStore` mutations in response to mouse/touch events | Unnecessary re-renders of unrelated nodes | State updates not granular; multiple mutations in quick succession. |
+| **Lack of Code Splitting** | Heavy modules imported globally (e.g., rendering views, graph utilities) | Initial bundle size > 2MB, slow load | All modules loaded upfront even if not used. |
+| **Inefficient List Rendering** | Lists of nodes in sidebar components | Scrolling lag | No virtualization; all items rendered simultaneously. |
+| **Repeated API Calls** | Agent service calls without proper caching | Latency spikes | Calls bypass `cacheRepository` in some paths. |
+
+## 3. Recommended Improvements
+
+### 3.1 Component Refactoring
+
+- **Split `CanvasPage` and `RecollectionPage`** into smaller, feature‑specific sub‑components.
+- **Extract pure logic** (e.g., node layout calculations) into standalone utility functions with `useMemo`.
+- **Apply `React.memo`** to pure presentational components that receive static props.
+
+### 3.2 State Management Optimization
+
+- **Granular State Updates**: Use `canvasStore` selectors to update only the affected node slices.
+- **Batch Updates**: Wrap multiple mutations in `runWithTiming` or `unstable_batchedUpdates` to reduce render cycles.
+
+### 3.3 Memoization & Lazy Loading
+
+- **Memoize Callbacks**: Replace inline event handlers with `useCallback` references stored in context or hooks.
+- **Dynamic Imports**: Use `import()` for heavy modules (e.g., `RenderingNode`, `AnimatedEdge`) to split the bundle.
+- **Virtualized Lists**: Integrate `react-window` or `react-virtualized` for large node lists in sidebars.
+
+### 3.4 Code Splitting & Bundle Optimization
+
+- **Remove Unused Dependencies**: Audit `package.json` for deprecated libraries.
+- **Enable `vite-plugin-dynamic-import`** for on‑demand loading of route‑specific components.
+- **Compress Assets**: Configure `gzip`/`brotli` in `nginx.conf` for large SVG and texture assets.
+
+### 3.5 Caching Strategy Enhancements
+
+- **Centralize Caching**: Ensure all external API calls route through `cacheRepository`.
+- **Add TTL** to cached responses to avoid stale data while still reducing repeat calls.
+
+### 3.6 Testing & Verification
+
+- **Performance Tests**: Add Vitest benchmarks for render times using `performance.now()`.
+- **Profile with React DevTools**: Capture flame graphs before and after each optimization.
+- **CI Gate**: Enforce that PRs must include a performance regression test if changes affect rendering.
+
+## 4. Contribution Path for Junior Developers
+
+1. **Familiarize** with the `canvasStore` architecture and the `CanvasPage` component structure.
+2. **Pick** a low‑risk optimization (e.g., memoizing a utility function).
+3. **Implement** the change, add JSDoc comments, and write a simple benchmark.
+4. **Submit** a PR with:
+   - Description of the performance gain.
+   - Updated tests/benchmarks.
+   - Documentation in `PERFORMANCE_IMPROVEMENTS.md`.
+
+## 5. Success Metrics
+
+- **Target**: Reduce average frame time from ~16 ms to < 10 ms for `CanvasPage`.
+- **Bundle Size**: Decrease initial load by ≥ 15 %.
+- **API Latency**: Cut repeated call overhead by ≥ 30 %.
+
+*This plan is living; subsequent sections will track progress and update targets.*