zui/ARCHITECTURE.md

Architecture Overview

1. Executive Summary

This document provides a high-level overview of the ZUI application's architecture, focusing on component organization, data flow, technology stack, and contribution guidelines for junior developers and AI agents.

2. Technology Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS, Shadcn UI, Zustand (canvasStore), custom hooks, and canvas rendering engine.
• Backend: Node.js 18, TypeScript, Express-like routing, Docker, and environment variable configuration.
• Database/Storage: In-memory state management with optional persistence via cacheRepository.
• Testing: Vitest, React Testing Library, and Jest-like utilities.

3. High-Level Structure

The workspace is divided into two primary directories:

• frontend/: Contains the React application, component library, pages, and styling.
• backend/: Contains server-side code, services, repositories, models, and middleware.

3.1 Frontend Modules

Module	Purpose	Key Files
canvas	Core graph/canvas rendering, nodes, edges, and interactive graph features.	src/app/canvas/*, src/components/graph/*, src/components/nodes/*
recollections	Collection management, browsing, editing, and related UI.	src/app/recollections/*, src/components/ui/*
kosmos	Knowledge organization system, settings, and user preferences.	src/app/kosmos/*
layout	Layout and navigation components shared across pages.	src/app/recollections/layout/*
components	Reusable UI components (buttons, dialogs, avatars, etc.).	src/components/ui/*
hooks	Custom React hooks for state, effects, and utilities.	src/hooks/*
lib	Shared utilities, types, and low-level helpers.	src/lib/*

3.2 Backend Modules

Module	Purpose	Key Files
services	Business logic, external API interactions, and complex computations.	backend/src/services/*
repositories	Data access abstraction, caching, and persistence.	backend/src/repositories/*
models	TypeScript interfaces and type definitions for domain objects.	backend/src/models/*
routes	HTTP route definitions and controllers.	backend/src/routes/*
middleware	Request processing pipeline (e.g., rate limiting, authentication).	backend/src/middleware/*
index.ts	Application entry point that composes services, routes, and middleware.	backend/src/index.ts

4. Data Flow

1. User Interaction (React components) → dispatches actions → updates local state (Zustand) → triggers re-render.
2. State Changes may trigger async calls to services (frontend) → which call backend APIs → responses are cached via cacheRepository.
3. Backend processes requests via routes, applies middleware, interacts with repositories and models, and returns JSON responses.
4. Caching layer reduces repeated expensive computations or DB queries, improving performance.

5. Component Interaction Patterns

• Container Components (e.g., CanvasPage, RecollectionPage) manage layout and state provision.
• Presentational Components (e.g., TreeBrowser, AgentNode) focus on UI rendering only.
• Custom Hooks encapsulate logic (e.g., useResizeHeight, useStreamingContent) and are reused across components.
• Context Providers (KosmosContext, RecollectionSidebarContext) supply global state to deeply nested component trees.

6. Extensibility & Plug‑in Architecture

• Node Types are registered via nodeRegistry.ts and extended through descriptor files.
• New node types can be added by creating a descriptor, implementing rendering logic, and registering it in registerBuiltinNodes.tsx.
• Extensibility points are documented in NODE_TYPE_EXTENSIBILITY_PROPOSAL.md.

7. Performance Considerations

• Large Render Trees: CanvasPage and RecollectionPage handle thousands of nodes; memoization (useMemo, useCallback) and lazy loading are essential.
• State Updates: Prefer granular state updates in canvasStore to avoid full tree re-renders.
• Code Splitting: Dynamic imports are used for heavy modules (e.g., rendering views, graph utilities).

8. Contribution Workflow

1. Fork the repository and clone the workspace.
2. Install dependencies: pnpm install (or npm ci).
3. Run the dev server: pnpm dev (frontend) and pnpm start (backend).
4. Create a feature branch: git checkout -b feat/your-feature.
5. Follow the Coding Standards (see CONTRIBUTING.md for details).
6. Submit a Pull Request with:
   • Descriptive title.
   • Linked issue(s).
   • Updated tests (if applicable).
   • Documentation updates (if relevant).
7. Code Review Checklist:
   • Readability: clear naming, minimal nesting.
   • Maintainability: extracted utilities, JSDoc, TypeScript typings.
   • Performance: no unnecessary re-renders, proper memoization.
   • Accessibility: semantic HTML, ARIA attributes.
   • Security: no hardcoded secrets, proper input validation.

9. Coding Standards

• TypeScript: Strict mode (strict, noImplicitAny, noUnusedVars).
• Naming: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
• File Structure: Feature‑first (features/<feature>/) or domain‑grouped (src/app/recollections/...).
• Documentation: JSDoc for all public APIs, TSDoc for types, and inline comments for complex logic.
• Formatting: Prettier configured via frontend/prettier.config.cjs.

10. Quick Reference for AI Agents

• Key Entry Points: frontend/src/main.tsx, backend/src/index.ts.
• State Management: src/lib/graph/state.ts, src/app/canvas/canvasStore.*.
• Routing: backend/src/routes/agentRoutes.ts.
• Caching: backend/src/repositories/cacheRepository.ts.
• Performance Hotspots: CanvasPage.tsx, RecollectionPage.tsx, large utility functions in src/lib/*.

This overview is intended to serve as a living document; future sections will expand on each module, performance audit findings, and junior developer quickstart guides.